Treat coding-agent memory as a cache

Memory is an input, not a record

When an assistant carries knowledge between threads, a useful convenience changes shape: context becomes a mutable input to future work. Anthropic’s September 2026 Claude Projects update describes threads that both add to and draw from shared project memory, including details such as a changed release plan or why a feature was dropped (Anthropic’s announcement). That can reduce repeated setup. It does not make the memory a dependable account of why the system is designed as it is.

I would treat coding-agent memory as a cache. A cache helps retrieve information quickly, but it is not where I would establish the authoritative meaning of a design. It may be incomplete, outdated, or too compressed to preserve the reasoning behind a choice. And when several threads contribute to the same memory, a statement that was useful in one context can be carried into another without its original qualifications.

That distinction matters because architectural decisions are not just facts to recall. “The service uses PostgreSQL” is different from “we chose PostgreSQL because these queries need relational constraints, and we rejected a document store for this access pattern.” The first may describe the current state. The second records a decision, its context, and the trade-off that made it reasonable. If the assistant remembers only the conclusion, it may confidently apply it where the original reasoning no longer fits.

The assistant’s memory can still be valuable. It can remind a new thread where to look, what terms the team uses, or which document might answer a question. But I would not ask it to settle a disagreement about the system. When memory and reviewed documentation conflict, the documentation wins until someone changes it deliberately.

Put decisions where change can be reviewed

I want architectural decisions in version-controlled documents next to the code they explain. That gives a reviewer a place to see what changed, discuss it, and connect the choice to the implementation. A short decision record can capture the problem, the options considered, the choice, and the costs accepted. A diagram can show the boundaries and interactions that prose alone makes harder to inspect.

The important property is not a particular template or file format. It is that a person can review the record as a change, and that the record has an owner who can update it when the design changes. If the service boundary moves, update the diagram and the decision. If the reason for a constraint no longer applies, say so rather than letting an old explanation quietly persist in a prompt or memory store.

I would keep the documentation concise enough to maintain. A sprawling architecture document that nobody changes is not more trustworthy just because it lives in the repository. Record decisions that affect future work: boundaries, data ownership, important integration contracts, security constraints, and consequential trade-offs. Link to relevant code where that helps readers verify the current behavior. Treat the document as a maintained explanation, not an attempt to describe every implementation detail forever.

Agent memory serves a different purpose. It can point toward those records and carry lightweight working context between tasks. For example, it might say, “Check the service-boundary decision before changing this integration.” That is a useful pointer. It should not replace the decision record with a compressed recollection of what the assistant thinks the decision was.

Make stale memory cheap to correct

A cache is useful partly because I do not need to preserve every cached entry forever. The same attitude helps with agent memory: make it easy to check, correct, pause, or discard. If an assistant has learned a deadline, a local naming convention, or a temporary constraint, that information can help the next task. If it has retained an old assumption about a service or a design choice, keeping it around may do more harm than asking it to inspect the current source of truth.

I would give the assistant an explicit precedence rule in its project instructions: use memory as a lead, not as authority; check reviewed architecture documents and current code for consequential decisions; surface conflicts instead of resolving them silently. This does not guarantee the assistant will always follow the rule. It does make the intended ownership clear and gives a reviewer a basis for spotting when the process failed.

There is also a difference between a helpful reminder and a durable decision. “Check with the owning team before changing this boundary” may be useful operational context. “This boundary exists to keep customer data isolated” is a design claim that deserves a reviewable record and evidence in the system. If the assistant stores both, the first can be a convenience; the second should point back to the documentation that people maintain.

When memory appears wrong, I would correct the underlying record first if the design changed, then correct or remove the memory. Otherwise, the system of record and the assistant’s carried context keep disagreeing. If the memory is merely a mistaken summary, discard or rewrite it rather than bending the architecture document to match. The correction path should preserve that distinction.

Decide who owns the truth

The useful question is not whether the assistant remembers. It is who owns the truth when its memory goes stale. I would make the answer explicit: people own architectural decisions through reviewed documentation; the assistant can help retrieve and apply context, but does not become the authority by remembering it.

That choice has a cost. Maintaining decision records takes attention, and the assistant may ask for context that already exists somewhere else. I would accept that friction over treating mutable memory as a hidden design repository. The hidden version is harder to review, harder to update deliberately, and harder to distinguish from a current decision.

When I ask an assistant to change a system, I want it to find the relevant decision, show how the proposed work fits it, and flag any conflict. If the decision is missing, that is a reason to ask for judgment or document a new choice—not a reason to let the most recent remembered sentence silently become architecture.