Memory Systems

The question is what to write down

An agent with a memory file will fill it. The mechanism is the easy half; external memory covers the tool and the handler behind it. The hard half is editorial: deciding what deserves to survive the session, and what is noise that will mislead a later run.

A memory directory that accumulates everything is worse than none. The agent reads it on every task, so a wrong note is a wrong note repeated on every later task.

Two kinds of thing worth keeping

Most useful memory falls into one of two buckets, and they age differently.

Facts that persist. The customer prefers email. The deploy script lives at scripts/release.sh. The database uses snake case. These stay true until something changes them, and their value is that a later session skips rediscovering them.

Progress on unfinished work. What has been done, what is next, what was tried and failed. These are true only about a moment, and stale progress notes are harmful: an agent that reads "authentication is complete" will not check.

Keep them in separate files. It sounds fussy, and it is the difference between a note that expires cleanly and one that quietly rots.

The pattern for work that spans sessions

Anthropic documents a concrete version of this for multi-session software work, and it generalizes to any long task.

An initializer session sets up the files before any real work starts. A progress log, a checklist defining the scope, and a pointer to whatever script the project needs to come up. Doing this first is what makes the rest mechanical.

Each later session opens by reading them. That restores the state without re-exploring the codebase or re-deriving decisions that were already made, which is the expensive part of resuming.

Each session updates the log before it ends, recording what was completed and what remains.

One rule holds the pattern together: mark work complete only after end-to-end verification confirms it, never when the code is written. A progress log that records intentions instead of outcomes is the stale-note problem with extra steps.

Write on transition

Two failure modes sit either side of the right answer.

An agent that writes after every action fills its store with narration and spends tokens doing it. An agent that writes only at the end loses everything when the session dies, which is the case memory exists for.

Write when something changes that a future session would need to know. A task finished. A decision made with a reason behind it. A dead end that should not be retried. Those are transitions, and they are rare enough to be cheap and important enough to be worth the write.

Retrieval decides whether any of it counts

A memory the agent does not open is a memory it does not have.

This is why organization matters more than volume. One file per concern, named for what it holds, beats a single growing log the agent has to read in full to find one fact. The prompt Anthropic injects tells Claude to check its memory directory before anything else, so the listing is what it sees first: make the filenames answer the question of what is in them.

Keeping the store small enough to read is a real constraint, not tidiness. When a file grows past what is worth loading, split it or summarize it down.

Contradiction is the failure to plan for

The hard problem is a memory that was true and is not any more.

Nothing detects this. The file says the API returns snake case; it was changed last month; the agent believes the file. Worse, the note carries no date and no provenance, so nothing about reading it suggests doubt.

Two habits help, neither complete. Record when a note was written and what it came from, so a later reader can weigh it. And prefer notes that point at a source over notes that copy one: "the schema is defined in db/schema.ts" stays true far longer than a copy of the schema.

Treat memory as a cache over the real state, not as the real state. When the two disagree, the world wins, and the note needs rewriting.

Further reading

• Anthropic, Memory tool: the injected prompt, and the multi-session development pattern.
• External memory: the tool, the handler, and the security burden.
• Context isolation: why durable information belongs outside the transcript.
• Compaction: what happens to everything you did not write down.