Memory and session context
Customizing agents · topic customizing-agents/memory
An agent forgets everything when a session ends unless something is written down. This topic covers automatic memory notes, curated context files, compaction of a long session, handing work from one session to the next, and turning work the agent repeats into knowledge it can reuse.
Concepts
- Auto-memory
- Notes an agent writes for itself during a session and reads back in later ones: preferences it learned, facts about the project, decisions made. It reduces re-explaining but is unreviewed by default, so it can carry a wrong assumption forward for weeks. Read what the agent remembers now and then, and correct or delete entries that have gone stale. glossary
- Context files
- Files a person curates for the agent to read: project instructions, design notes, a plan, a glossary of domain terms. Unlike auto-memory they are deliberate, versioned and reviewed like code. They are the right place for anything the whole team wants every session to know, and the place to move a fact once auto-memory has proven it useful. glossary
- Compaction
- Replacing a long session's history with a summary so work can continue inside the context window. Compaction keeps the goal and recent state and drops the raw detail, so anything not in the summary is lost. Ask for a summary that names open items and decisions before compacting, and save it to a file when the work will span sessions. glossary
- Session handoff
- Ending one session so the next can pick up without loss: a written state of what was done, what remains, what was decided and why, and where the relevant files are, stored in the repository or a plan file. A good handoff lets a fresh session, or a colleague's, start productive in one turn instead of rediscovering the work. glossary
- Turning repeated work into reusable knowledge
- Noticing when the agent is explained the same thing or walked through the same steps twice, and moving it somewhere durable: a fact into project instructions, a procedure into a skill, a check into a hook, an example into a context file. Each move removes a future explanation and a future mistake. It is the compounding part of working with agents. glossary
Links
- Builds on: Agent skills, Grounding and memory
- Leads to: nothing yet
- Competencies drawing on it: Configures an agent for a project
Lessons
- Directing the summary before compaction (tutorial)
- Reading what the agent remembers (tutorial)
- Turning repeated work into something the agent keeps (explanation)
- Handing work to the next session (tutorial)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Directing the summary before compaction
Unlocks when you finish Directing the summary before compaction.
Takeaways
- Compaction replaces a long conversation with a summary. The detail and anything else the summary leaves out are gone, and the model that writes it can miss something important.
- In Claude Code,
/compacttakes instructions for the summary, and the automatic pass near the window's limit guesses what to keep without them. - The project-root
CLAUDE.mdand the auto-memory come back after a compaction. A rule or a decision given only in the chat survives only if the summary states it. - Claude Code doesn't show the summary in the terminal, so ask the agent what it knows after a compaction, and compare with the facts you planted or decided.
- Save what the next session needs to a file, and move a rule every session needs into
CLAUDE.md.
Example
Check the summary without instructions · open in the lesson
Run this, and compare with the output below.
python3 check_summary.py samples/unguided.mdPrints the lines below (verified in CI from site/examples/customizing-agents/compaction/unguided.py)
samples/unguided.md rule, don't change migrations/: lost decision, keep /v1/export until March 31: lost open item, test_export_timezone: kept kept 1 of 3
Reading what the agent remembers
Unlocks when you finish Reading what the agent remembers.
Takeaways
- Auto memory is notes the agent writes for itself. In Claude Code they are in one folder per repository on your machine, with a
MEMORY.mdindex and one topic file per note, and the feature is on by default. - A session loads the first 200 lines or 25KB of
MEMORY.mdat start, and reads topic files only when it needs them. The index line is what every session sees. - A stale note is applied in every session with the same confidence as a true one, because the model reads it as context. Check each note against what it describes, and delete the file and its index line.
- A fact the whole team needs belongs in a context file in the repository, where it is versioned and reviewed. An instruction file loads it with
@path, resolved from the importing file's folder, and a path in backticks stays text.
Example
What a session starts with · open in the lesson
Run this from site/examples/customizing-agents/memory-review/, and compare what you see with the output below.
python3 startup.pyPrints the lines below (verified in CI from site/examples/customizing-agents/memory-review/startup.py)
loaded at start: MEMORY.md, 4 of 4 lines read when needed: project_done_rewrite.md (project) read when needed: project_item_length.md (project) read when needed: project_tests_touch_data.md (project) read when needed: user_diff_first.md (user)
Turning repeated work into something the agent keeps
Unlocks when you finish Turning repeated work into something the agent keeps.
Takeaways
- The sign to look for is the same explanation given twice. Each one can move to a place the agent reads without being told, so no later session needs it.
- A fact that most tasks need goes into the project instructions, and a procedure goes into a skill, which loads only when a task needs it.
- A rule where one miss costs too much goes into a hook, which runs every time. An instruction is a request, even one the agent has read.
- In this course, an example to copy goes into a context file, with one line in the instructions that says when to read it.
- A hook enforces only the tool calls it sees. Delete a line that a shared hook or a skill holds in full, and shorten a line that a hook covers in part, such as a rule a shell command can still break. The instructions file gets shorter, and the rules left in it stand out.
Example
What came up more than once · open in the lesson
Run this in site/examples/customizing-agents/repeated-work/, and compare with the output below.
python3 find_repeats.pyPrints the lines below (verified in CI from site/examples/customizing-agents/repeated-work/find_repeats.py)
Said by the user in more than one session: sessions 1, 2, 3: Don't edit files in src/api/generated/ by hand. Change the spec or regenerate the client. sessions 1, 2, 3: Set SPEC_URL to https://billing.example.com/staging/openapi.json, that's the staging spec. sessions 1, 3: Amounts from the billing API are in cents. Use formatMoney() from src/lib/money.ts, it divides by 100 and adds the currency. sessions 2, 3: Call the billing API the way this snippet does, through useApi(), so the page gets the loading and error states: Run by the agent in every session: npm run generate make api-client SPEC_URL=https://billing.example.com/staging/openapi.json make api-client npm run lint npm run format -- src/api/generated npm test -- src/api npm test
Handing work to the next session
Unlocks when you finish Handing work to the next session.
Takeaways
- A new Claude Code session starts without the old conversation. It loads
CLAUDE.mdand auto-memory and reads the rest from the repository. - A session handoff is the state of the work written to a file before the session ends: what is done, what is left, the decisions with their reasons, what was ruled out, and where the files are.
- The diff shows what changed. The reasons and the rejected approaches are only in the conversation, so they are what the handoff must hold.
- Resuming works on your own machine, and it brings back the approaches that went wrong too. A handoff works for any session and for a colleague.
- Keep the handoff with the work and delete it when the work is done. Move a lasting decision to a decision file and a rule for every session to
CLAUDE.md.
Example
Look at the practice repository · open in the lesson
Run these in ~/handoff-diff-only, and compare with the output below. The last line is the verdict of python3 -m unittest -q, which prints Ran 4 tests and then OK in your terminal.
git status --shortgit diff --stat=60python3 -m unittest -qPrints the lines below (verified in CI from site/examples/customizing-agents/session-handoff/diff_only.py)
M test_reports.py test_reports.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) tests: OK
Sources
AEC-05Memory and context: context engineering, memory kinds, memory versus RAG, context rot, Agent Engineer Course (course)Brilliant MEMMemory (listed under SPC), Brilliant, Coding with AI skills map (reference)Academy claude-code-101Claude Code 101, Claude Academy (course)Academy claude-code-in-actionClaude Code in action, Claude Academy (course)