A context window is the worst place to keep anything you need later. It is finite, it is lossy the moment you compact it, and it disappears when the session ends. Yet the default way people work treats the conversation as the record of what happened.
Externalized state inverts that. The plan lives in a file. Decisions live in a file. Progress lives in a file. The window holds the current task and pointers to the rest.
What changes
plan.md what we are doing and why, updated as it changes
decisions.md what was chosen, what was rejected, and the reason
progress.md what is done, what is nextThe agent reads what it needs and writes back as things change. Nothing important depends on the conversation surviving, which means the conversation is now free to end.
Why it fixes several problems at once
- [Context rot](/context-engineering-dictionary/context-rot) stops mattering. When the durable facts are on disk, a bloated window is an inconvenience rather than a loss. Clear it and reload.
- Handoff becomes free. A new session reads three files and is caught up. There is no summarising step to get wrong.
- Decisions stop being re-litigated. A rejected approach written down with its reason does not get re-proposed every time history is compacted away.
- It is inspectable. You can read what the agent believes, and correct it, which you cannot do with a summary buried in a transcript.
Getting it right
- Write at decision points, not continuously. Files updated every turn become noise and cost tokens to re-read.
- Keep them short enough to reload whole. If
decisions.mdgrows past what you would paste into a window, it needs splitting or pruning. - **Record the *why*.** "Chose Postgres" ages badly. "Chose Postgres because we need transactional writes and already run it" survives the next agent asking why not SQLite.
- Treat them as the source of truth. If the file and the conversation disagree, the file wins, and the agent should be told so explicitly.
Related terms
Checkpoint
A checkpoint is a deliberate save point holding enough state to resume a task from there. It turns a long run from something that either finishes or is lost into something that can be picked up.
Read definition →PatternValidatedScratchpad
A scratchpad is a place the model writes intermediate work it will read back later, rather than holding it in the answer. It separates thinking from output, and gives the working a home that is not the context window.
Read definition →AntipatternProvenContext rot
Context rot is the gradual decay of a long session as stale, superseded, and irrelevant text accumulates in the window. Nothing breaks at any single step, which is why it is usually diagnosed as the model getting worse.
Read definition →ConceptConversation history
Conversation history is the running list of past turns you re-send on every request so the model appears to remember. It is the simplest form of memory, and the first thing to overflow a context window if you never prune it.
Read definition →