Yesterday's session ruled out one library, agreed where a folder of shared code should live, and left a database change half finished. Today Claude Code opens cold. It proposes the ruled-out library, creates a second folder for the same thing, and cannot say which half of the change exists.
Nothing was lost by accident. Those three decisions only ever existed inside a conversation, and a conversation is not a place things are kept.
The idea
Every session starts with an empty The working memory a model has for one conversation. It starts empty every time, so nothing carries over unless a file is read., so whatever the next session needs to know has to be readable from disk. Durable project memory is a small set of plain files that answer four questions: how this project works, what was decided and why, what is true right now, and what to do first on resuming. Everything else stays in the conversation and is allowed to disappear.
| Memory | The question it answers | Written by | Shape that works |
|---|---|---|---|
| Instructions | How does this project work? | You, deliberately | Short, specific, verifiable rules |
| Decisions | Why is it this way? | You, when a choice sticks | Date, choice, consequence |
| Progress | What is true right now? | Whoever finishes a session | Done, active, next |
| Handoff | Where do I start? | The session that stops | Entry file plus the check to run |
How it works
The instruction file is the one every tool has. Claude Code reads CLAUDE.md at
the start of every session; Cursor and several other agents read an equivalent,
commonly AGENTS.md. Anthropic's memory documentation describes two
complementary systems: instruction files you write, and an automatic memory
Claude Code keeps for itself from your corrections and preferences. Both are
loaded at the start of every conversation, which is the whole mechanism. Nothing
here remembers you. Something loads a file.
Loaded and obeyed are different states. The same documentation says these files are treated as context rather than enforced configuration, that there is no guarantee of strict compliance, and that if two instructions contradict each other the model may pick one arbitrarily. For something that must happen at a fixed moment every time, the documented answer is a A small script Claude Code runs automatically at a set moment, such as after every file edit. that runs as a script.
Length is the failure everyone walks into. Anthropic targets under 200 lines per instruction file, because longer files consume more context and reduce adherence, and it names the bloated instruction file as a common failure pattern: important rules get lost in the noise, so half of them get ignored. The test it offers for each line is worth stealing. Would removing this line cause a mistake? If not, cut it. That rules out anything the model can work out by reading the code.
One fact needs one owner. If the active task appears in a plan, a progress file and a README, the copies drift and a cold session cannot tell which one is current. Put the fact in one place and link to it from the others.
What to do
- Move a rule into
CLAUDE.mdthe second time you type it into chat, and delete rules Claude Code already follows without them. - Record a decision when it changes what the next session should do, with its consequence rather than only its conclusion.
- End every session by writing four lines: current result, open risk, the next file to open, the next check to run.
Where it breaks
Written memory is a second project, and it rots. A stale file does more damage than a missing one, because it is read with the same trust as a true one. Do not preserve routine conversation, raw command output, or facts the code already states plainly. A file earns its place only when a cold session would make a better decision for having read it.
Files also do not enforce anything. A rule in CLAUDE.md changes the odds. When
something must be true every time, back it with a check that fails loudly.