All chapters
  1. Start hereMemory is what you keep. A checkpoint is where you stopped
  2. Memory · 1The stateless request: why anything has to be stored at all
  3. Memory · 2Five kinds of memory: working, episodic, semantic, procedural and preference
  4. Memory · 3Conversation history, summaries, retrieval and durable facts
  5. Memory · 4Files as memory in coding agents: instructions, journals, artifacts and checkpoints
  6. Memory · 5Database stores: tables, JSON, documents, objects and vectors
  7. State · 6Run identity: run_id, thread_id, trace_id, correlation_id and task_id
  8. State · 7State machines, checkpoints, event sourcing and where replay must stop
  9. State · 8Failure and resume: idempotency keys, retry policy and the exactly-once illusion
  10. State · 9The transactional outbox: side effects, compensation and deduplication
  11. Policy · 10Memory write policy: extraction, confidence, provenance, expiry and deletion
  12. Policy · 11Retrieval and ranking: relevance, recency, salience and scope
  13. Policy · 12Shared memory between agents: consistency, isolation, ownership and races
  14. Policy · 13Security: tenant separation, personal data, secrets, consent and retention
  15. Practice · 14Evaluation: memory correctness, stale facts, contamination and recovery tests
  16. Practice · 15Frameworks and standards: what each one stores for you
  17. Practice · 16The insurance lab: one run that fails, resumes and remembers, end to end
  18. Practice · 17Advanced: migration, conflict resolution, forgetting, summary drift and disaster recovery
  19. ReferenceGlossary
  20. AboutAbout this site and its sources
Memory · 4

Files as memory in coding agents: instructions, journals, artifacts and checkpoints

A coding agent keeps its memory in plain files. Project instructions, a work journal, produced artifacts and file checkpoints, and which of them survives what.

What you will understand
Six holders
Instructions, auto memory, a journal, artifacts, file checkpoints and the transcript: who writes each, and when it is read.
What survives what
Which of them outlives the session, the machine, and the person, and why the commit outlives them all.
Same ideas, plain files
Memory and checkpoints in a coding agent, mapped to the insurance example.

Every other page of this site uses the insurance agent. This page uses a second example on purpose, because it makes the same ideas visible with nothing but files.

A developer on the insurer's platform team uses a coding agent, Claude Code, to change the example's memory store: every read must carry the broker's scope in the query, so that case UW-M11 cannot leak another broker's note. On Monday afternoon the agent reads the repository's instructions, edits memory.py, adds two tests, runs them, and gets one of them passing. At six o'clock the developer closes the laptop.

On Tuesday morning she opens a new terminal and starts the agent again. What does it know? It does not know that the read was half rewritten. It does not know that one test still fails, or why. It does not know that on Monday she told it twice to run the tests with python -m unittest, not with another runner. The model call keeps nothing, as Stateless showed. Everything the agent will know on Tuesday has to come from a file.

This page lists those files, says who writes each one and when it is read, and checks which of them survives what. Every statement about Claude Code on this page comes from its documentation, read on 2026-11-17; other coding agents have similar files under other names.

The holders, one at a time#

Project instructions: what the team wrote down#

Project instructions are a file in the repository that tells the agent how this project works. For example, a CLAUDE.md at the root that says: "Run tests with python -m unittest in examples/uw-memory. Never edit content/glossary.json; it is generated."

Claude Code's documentation describes CLAUDE.md files at several levels: a managed file set by the organization, a user file at ~/.claude/CLAUDE.md for one person's preferences across projects, a project file at ./CLAUDE.md or ./.claude/CLAUDE.md shared with the team through version control, and a local file ./CLAUDE.local.md for one person's notes on one project, which should be added to .gitignore. Files above the working directory load when a session starts; files in subdirectories load when the agent touches a file there. One file can import another with @path, up to four hops deep. Larger projects can split rules into .claude/rules/, scoped to paths.

In the terms of Memory kinds, project instructions are mostly procedural memory ("how work is done here") and some semantic memory ("this file is generated"). The team writes them, through review, like code.

What this is not. The documentation is explicit that Claude treats these files "as context, not enforced configuration". An instruction is a strong request. If an action must be blocked whatever the agent decides, the documentation points to a hook instead. Hooks and review gates for coding agents are covered on Diff to Deploy.

Auto memory: what the agent wrote down#

Memory file is this site's name for a file the agent writes to remember something for later sessions. In Claude Code this is auto memory. For example, after Monday the agent may keep a note that tests in this project run with python -m unittest, because the developer corrected it twice.

The documentation describes auto memory as notes Claude writes itself, on by default in local sessions, kept at ~/.claude/projects/<project>/memory/: a MEMORY.md index and one topic file per memory. All worktrees of one repository share it. It is machine-local: it is not shared across machines. The first 200 lines or 25KB of MEMORY.md, whichever comes first, are loaded at the start of every conversation; topic files are read when needed. It can be turned off per user, per project, or with an environment variable.

Notice the difference in who writes it. Project instructions are written by people and reviewed. Auto memory is written by the agent from what happened in sessions. That is exactly the line Write policy draws for the insurance agent: a memory the agent writes needs a source and should be easy to inspect and remove. Here the files are plain markdown that the developer can read, edit and delete, which is the inspection.

The journal: where the work stopped#

A journal is a file in the repository where the agent records the state of a task in progress: what is done, what is next, what failed and why. For example, a PROGRESS.md with three lines at six o'clock on Monday: "Scope filter moved into the query in read_memories. Test test_scope_before_ranking passes. test_top_k_not_emptied fails: the filter runs after the cut; fix next."

A journal is not a Claude Code feature. It is a practice: the developer asks the agent to keep one, or writes it into the project instructions ("Update PROGRESS.md at the end of each task step"). It matters because it is the coding agent's checkpoint in the sense of this site. It answers "where were we?", not "what do we know?". It is plain text, committed or not as the team decides, and read by the next session because the instructions say to read it.

Artifacts: what the work produced#

An artifact is a file the work produced that someone will use later: a test report, a generated diagram, a migration script, a benchmark output. For example, the test runner's output saved to out/report.json by the example's runner.

Artifacts are evidence, the counterpart of EV-ROOF-0412 in the insurance example. They record what happened. They are not instructions and not memory: the next session may read them to see the last result, but nothing in them tells it how to behave.

File checkpoints: undo within a session#

A file checkpoint is a saved snapshot of the files before an agent's edits, so that the edits can be undone. For example, the state of memory.py before Monday's second prompt, kept so that the developer can rewind when an edit goes the wrong way.

Claude Code's checkpointing, as documented, captures the state of the code before each prompt that starts a turn. /rewind, or pressing Esc twice, offers to restore the code, the conversation, or both, or to summarize part of the conversation. Checkpoints are saved with the conversation, so rewind still works after resuming a session. Snapshots are deleted by a retention sweep, by default about 30 days after the session last saved one. The documentation lists limits: a file changed only by shell commands is not tracked, changes made outside the session are normally not captured, and edits by subagents are usually not restored. It states that checkpoints are "designed for quick, session-level recovery" and that version control remains the permanent history.

This is a checkpoint in a slightly different sense from the rest of the site. A workflow checkpoint lets a run continue forward after a crash. A file checkpoint lets a person go back. Both are saved execution state; neither is memory.

The transcript and session resume: the conversation itself#

The documentation says sessions are saved continuously to local transcript files, JSONL at ~/.claude/projects/<project>/<session-id>.jsonl, whose entry format is internal and may change. Session resume is continuing an earlier conversation from its transcript: claude --continue reopens the most recent session in the current directory, and claude --resume opens a picker or takes a session name, id or transcript path.

The transcript is conversation history in the sense of History or facts: everything that was said, in order. Resuming it brings back Monday's conversation. It is local to the machine and subject to retention. And as that page showed, a long conversation is a poor place to look for the one fact that matters.

Which holder survives what#

The diagram puts the holders in order of how long they last and who can see them.

Diagram: Where a coding agent keeps what it knows · from one call to the commit history

Read left to right, from the shortest-lived holder to the longest. The conversation exists in the model's input only during a call. The transcript and file checkpoints stay on one machine for a retention period. Auto memory stays on one machine. Committed instructions and the journal reach every clone. The commit history outlives every machine and every person.

  1. One call
    1. Conversation: What the model sees during one call. Gone when the call returns.
  2. One machine, with retention
    1. Transcript: The saved conversation, resumable on the same machine until the retention sweep.
    2. File checkpoints: Snapshots of files before each prompt, for undo inside a session. Not shell changes.
  3. One machine
    1. Auto memory: Notes the agent keeps for later sessions; the index loads at session start. Machine-local.
  4. Every clone
    1. Project instructions: How work is done in this repository, loaded at session start. Context, not enforcement.
    2. Journal: The task's checkpoint: done, next, failing and why. A practice, not a product feature.
  5. Outlives everyone
    1. Git commit: The durable, shared record of the code and the files committed with it.

Read it from left to right. The conversation is in the model's input only during a call. The transcript and the file checkpoints live on one machine for a retention period. Auto memory lives on one machine with no retention sweep. The journal and the project instructions live in the repository, and once committed and pushed they are on every clone. The commit history outlives every other holder, every machine and every person on the team.

Try it in the lab: pick an event and see which holders still have Monday's state.

HolderSession endsMachine restartsLaptop lostA teammate continues on her machine
The conversation (model input)LostLostLostLost
Transcript and file checkpointsKept, until the retention sweep; resumableKeptLostNot there: machine-local
Auto memoryKeptKeptLostNot there: machine-local
Journal file, committed and pushedKeptKeptKeptKept
Project instruction file, committedKeptKeptKeptKept
The git commitKeptKeptKeptKept

The table explains Tuesday morning. If the developer resumes on the same laptop, the transcript brings Monday back, and auto memory carries the note about the test runner. If her laptop had been replaced, or if a teammate took over, only what was committed would be there: the instructions, the journal if it was committed, and the code. The commit is the only holder that survives every row.

For a backend engineer. This is the classic split between a developer's local state and the shared state of a team. Your IDE's workspace, its local history and your shell history are machine-local; they help you and nobody else. The repository is shared state, reviewed and versioned. A coding agent adds two holders on the local side (transcript and auto memory) and asks you to decide what gets promoted into the shared side.

The same ideas as the insurance example#

Each holder has a counterpart in the insurance agent, and seeing the pairs is the point of this page.

Coding agentInsurance agentKind of thing
Project instruction fileWorkflow code, rules, instructionsProcedural memory, written by people through review
Auto memorymemories rows written by the write policyLong-term memory written from runs
Journal fileCheckpoint of a run (state_version)Saved execution state: where were we?
Artifact (test report)Evidence (EV-ROOF-0412)What happened, kept as proof
File checkpoint, /rewind(no direct counterpart)Undo for a person, inside a session
Transcript, --continueConversation history with the brokerEverything said, in order
Git commitdecisions table, kept for yearsDurable, shared, reviewed record

The most useful pair is the journal and the checkpoint. A coding agent that keeps no journal behaves like a workflow without checkpoints: after an interruption it starts the task over, re-reads everything, and may redo steps that had side effects, such as a migration it already ran.

The failure, shown#

Here is Tuesday morning twice.

Without a journal, and on a new laptop: the agent reads the project instructions, sees nothing about the task, and the developer explains it again. The agent rewrites the read in memory.py from scratch, in a slightly different way than Monday's half-finished version still in the working copy, so now there are two partial approaches in one file. The failing test is discovered again an hour later.

With a journal committed at six on Monday: the agent reads the instructions, which say to read PROGRESS.md; it learns that the scope filter is in the query, that one test passes and why the other fails; it fixes the cut order and runs the tests with the runner the instructions name. Nothing was repeated, and the developer said nothing twice.

A checklist for Monday#

  1. Does the repository have project instructions, reviewed like code? Do they say how to run the tests?
  2. Is there a journal practice for tasks that span sessions, and do the instructions say to read and update it?
  3. What has auto memory stored for this project? Open MEMORY.md and read it. Is anything there that should be in the shared instructions instead?
  4. Which important state lives only on one laptop: the transcript, auto memory, an uncommitted journal?
  5. Before a risky multi-file change, commit. A file checkpoint is a session-level undo, not a history.
Advanced: promoting what the agent learned into what the team agrees

Auto memory and project instructions solve the same problem from two sides. The agent learns something in a session and writes it down for itself; the team decides something and writes it down for everyone. The interesting moment is promotion: a note in auto memory that should become a rule for the whole team, such as "tests run with python -m unittest".

Promotion should be a change that a person reviews, exactly like the rule on Memory kinds that procedural memory changes only through review. The reason is the same as in the insurance example: memory written by an agent from experience is a generalization from a few episodes, with no second reader. Once it is in the shared instructions, every session of every teammate follows it.

The reverse also matters. Instructions accumulate and contradict each other; the documentation notes that if two instructions contradict each other, Claude may pick one arbitrarily. Reviewing the instruction files periodically is the coding-agent version of conflict resolution on Advanced.

Advanced: what file checkpoints do not cover

File checkpoints track what the agent's own file-editing tools changed. A database migration run through a shell command, a package installed, a file deleted with a shell command, a message posted to a chat: none of these is undone by a rewind. They are side effects outside the agent's tracked files, the coding-agent version of the provider call and the stored recommendation in the insurance example. The same discipline applies: make such steps idempotent or record them in the journal so that a resumed session knows they happened, and rely on version control and the system's own rollback for the rest. Hooks that block or record such commands before they run are covered on Diff to Deploy and the harness around the agent on Harness Engineering.

In one breath#

A coding agent forgets everything between sessions; it knows on Tuesday only what is in its files. Project instructions are procedural memory written by people, auto memory is long-term memory the agent writes for itself on one machine, a journal is the task's checkpoint, artifacts are evidence, file checkpoints are a session-level undo, and the transcript is the conversation. Only what is committed survives a lost laptop or a new teammate.

The coding agent keeps everything in files. The insurance agent needs something more structured: tables, transactions and indexes that many runs can query at once. The next page compares the stores that provide them: Database stores.