Directing the summary before compaction

Claude Code reads CLAUDE.md and its auto-memory notes at the start of every session [1]. This lesson is about what happens inside one long session, when the conversation gets too long for the window and the agent replaces it with a summary. We load a session log with three facts planted in it and compact it on command, with instructions for what the summary must keep. Then we check which facts are still there.

The lesson uses Claude Code, and the files are in the course repository at site/examples/customizing-agents/compaction/. transcript.md is the session log. check_summary.py is a short Python script that only reads the file you give it, and the course checks its output on every build. Run the commands in this lesson from that directory. In the cd line, replace <course-repo> with the path to your copy of the course repository.

cd <course-repo>/site/examples/customizing-agents/compaction

A long session, and a summary in its place

Where memory comes from described context rot: as a session goes on, the window fills with old turns and tool output, and the model starts to lose facts that are still in the window [2]. A long coding session gets there fast, because every file the agent reads and every test run adds to the window.

Compaction is the way out that keeps you in the same session. The agent replaces the conversation so far with a summary and goes on from the summary. The summary is much shorter than the turns it replaces. The raw detail is gone, and so is anything else the summary leaves out. The model that writes the summary can miss something important [2].

In Claude Code, compaction happens in two ways. It runs by itself as the window gets close to its limit, and the session goes on after it [3]. You can also run it yourself with the /compact command and add instructions for the summary after it, as in /compact keep the decisions about the export route [4]. The instructions tell the summary what to keep. Without them, the automatic pass decides for itself what matters [3]. According to the overview of how Claude Code works, it keeps what you asked for and the important code, and detailed instructions given early in the session can be lost [5]. The page of best practices says that the pass keeps code patterns, the state of files and key decisions [6].

What the summary replaces, and what comes back

Some of what the agent knows doesn’t depend on the summary. Claude Code keeps these outside the conversation and puts them back after a compaction [3]:

• the project-root CLAUDE.md and the auto-memory notes, read again from disk
• the plan the agent wrote in plan mode, read again from disk
• up to five of the files the agent read or edited, the most recently modified first

Everything that was said in the conversation goes into the summary, and that includes a rule you typed in the chat. One cause the memory page names for an instruction that disappeared after compaction is that it was given only in the conversation, and the page says to put such a rule in CLAUDE.md [1]. A rule with paths: in its front matter, or a CLAUDE.md in a subdirectory, is loaded into the conversation when the agent reads a matching file. So it is summarized away too, and comes back only when the agent reads such a file again [3].

So a compaction puts at risk each fact that exists only in the chat. In this lesson that means a rule you set, a decision with its reason, and an open item that nobody wrote down. The log plants one of each.

Checkpoint · multi-choice

What is back after the compaction?

You run /compact with nothing after it. Which two of these come back from disk afterwards, whatever the summary says?

Select exactly 2.

The instructions in the project-root CLAUDE.mdA rule you typed in the chat an hour ago, word for wordThe notes in the auto-memoryA rule with paths: in its front matter that loaded when the agent read a file

CheckHintSkip

Load the session

The log in transcript.md is a coding session on a small report service, written for this lesson. Read it once. It plants three facts:

• a rule the user sets in the first message: don’t change anything under migrations/
• a decision from the middle: keep the old /v1/export route until March 31, because version 4.2 of the mobile app still calls it
• an open item from later on: the test test_export_timezone fails, and the user wants it fixed after the release

Make an empty folder for the practice session and start Claude Code in it with auto-memory turned off. The folder has no project files, so the agent has nothing to change. Auto-memory is on by default, and the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns it off [1]. With auto-memory on, the agent could save the decision from the log as a memory note. That note comes back after a compaction whatever the summary says, so the check would no longer test the summary. A message such as “Saved 1 memory” means the agent wrote a memory note [1]. If you see one, auto-memory is still on, so start again in a new folder with the command below.

mkdir -p ~/compaction-practice
cd ~/compaction-practice
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

Open transcript.md in an editor, copy from the first **User:** line to the end, and paste it as your first message. Then ask one or two questions about it, such as “What does to_json() do?” and “Which test did the agent add?”. Paste the log and don’t ask the agent to read the file, because after a compaction Claude Code reads recently used files again [3], and a file the agent read would bring all three facts back. In a fresh session with no history, /compact answers Not enough messages to compact. [7]. If you see that after pasting the log, ask one more question and try again.

Before you compact, write down which of the three facts you expect a summary without instructions to keep. Then look at the file samples/unguided.md. It is a summary of the same log that shows how a summary without instructions might read. The course wrote it for the lesson, and no model produced it. The script check_summary.py looks for the words that name each fact and prints kept or lost.

Example · run it

Check the summary without instructions

Run this, and compare with the output below.

python3 check_summary.py samples/unguided.md

Output

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

Output verified in CI from site/examples/customizing-agents/compaction/unguided.py.

The sample shows one way a summary can go wrong. Everything in it about the work is correct, down to the changed files and the next step. It keeps the open item, which comes late in the log and again in the last test run. It drops the rule and the decision, which come up only in the first part of the log.

Compact on command, and check

Now compact with instructions that name the kinds of facts at risk. In the practice session, type:

/compact Keep every decision with its reason, every open item, and every rule I set for this work. Drop the tool output.

When the summary is written, Claude Code prints a message that the conversation was compacted, and the summary itself isn’t shown in the terminal [3]. So you check it by asking. Work on this project goes on in another session, so have the agent write the answer to a file:

Write summary.md with the goal of this work, the current state, every decision with its reason, every open item, and every rule I set. Use only what you know from this conversation.

The agent writes summary.md from the compacted summary, because the summary has replaced the log in the conversation [3]. Leave Claude Code with /exit, and go back to the course directory to check the file:

cd <course-repo>/site/examples/customizing-agents/compaction
python3 check_summary.py ~/compaction-practice/summary.md

The course repository has a summary made for the same instructions, in samples/directed.md. The course wrote it for the lesson, and no model produced it. Run the script on it to see the output that a summary with all three facts gives.

Example · run it

Check the summary with instructions

Run this, and compare with the output below.

python3 check_summary.py samples/directed.md

Output

samples/directed.md
  rule, don't change migrations/: kept
  decision, keep /v1/export until March 31: kept
  open item, test_export_timezone: kept
kept 3 of 3

Output verified in CI from site/examples/customizing-agents/compaction/directed.py.

The script only matches words. A summary that says “the old export route” in place of /v1/export is reported as lost, so open summary.md and read it before you trust a lost. Your result may differ from the samples, because a model writes a different summary each time. The check tells you which facts to state again.

Checkpoint · choice

Which instruction protects the decision?

You are about to compact the session. Which command gives the best chance that the summary still has the rule and the decision?

/compact with no instructions, because the automatic pass already keeps the facts that matter most./compact Keep it short, under a hundred words, so that the next task has room in the window./compact Keep every decision with its reason, every open item, and every rule I set for this work./compact Keep the last ten messages word for word, and summarize everything before them.

CheckHintSkip

Checkpoint · choice

How do you find out what survived?

You compacted with instructions. How do you find out whether the decision about the old route is still in the agent’s context?

Scroll up in the terminal and read the summary that the /compact command printed.Trust the summary, because a summary made with instructions keeps every fact they name.Run /context and look at how many tokens the summary takes up in the window.Ask the agent to list the decisions, open items and rules it knows of, and compare them with your own list.

CheckHintSkip

Where a fact belongs

A summary is right for the work of one session. A fact that every session needs belongs in a file that compaction doesn’t touch. For a rule such as “don’t change anything under migrations/”, that file is the project-root CLAUDE.md, which Claude Code reads again after every compaction [1]. You can also add a section to CLAUDE.md that says what every compaction must keep, for example the list of changed files and the test commands, and Claude Code uses it when it compacts [6] [7].

The summary.md you saved is for the next session on the same work. A new session, or a /clear, starts with an empty conversation [4], and the file is the part of this session it can read. The next lesson in this part writes a full handoff for the next session.

Checkpoint · scenario

The agent wants to clean up

After a compaction without instructions, the agent writes: “Next I’ll clean up. /v1/export is unused, so I’ll remove it.” You remember deciding to keep it. What do you do?

Stop it, state the decision and its reason again, and add the decision to summary.md.Approve the change. If the route is still needed, one of the tests will fail.Run /compact again, this time with instructions to keep every decision.Ask the agent whether a decision about /v1/export was made, and approve if it knows of none.

DecideHintSkip

Pitfall: The summary that kept everything except the decision

A developer works all afternoon in one session. Early on they decide to keep an old route until a mobile app version is retired, and say so once in the chat. The session compacts by itself, and its summary lists every changed file, the tests and the next step, all of it correct. The decision isn’t in it. An hour later the agent removes the old route as dead code, the tests pass, and the app stops working the next morning. Before you compact, tell the summary to keep decisions, open items and rules, and ask the agent afterwards what it still knows.

Exercise

If you followed the steps above, your ~/compaction-practice/summary.md is the exercise, and you can go to the result below. Otherwise do them now: paste transcript.md into a new Claude Code session in an empty folder with auto-memory off, ask one or two questions, and compact with the instructions from the section “Compact on command, and check”. Then have the agent write summary.md and run check_summary.py on it. The folder is empty, so the agent has no project files to change. The steps show you what survives a compaction you directed, in about ten minutes.

A short practice session like this one may keep all three facts even without instructions. The whole log arrived as one message of yours, and Claude Code keeps your requests [5]. You can’t know which facts survived until you check, and that holds for the stretch goal too.

A good result: the script reports kept 3 of 3, or you read summary.md and find each fact the script reported as lost stated in other words. If a fact is really gone, look at your instructions and ask which words would have named it. Which facts from your own last long session were said only in the chat?

Stretch: Repeat the session in a new folder with auto-memory off, run /compact with no instructions, write summary.md the same way, and compare the two results from check_summary.py.

Recap

1. 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 [2].
2. In Claude Code, /compact takes instructions for the summary, and the automatic pass near the window’s limit guesses what to keep without them [4] [3].
3. The project-root CLAUDE.md and 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 [1] [3].
4. 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 [3].
5. Save what the next session needs to a file, and move a rule every session needs into CLAUDE.md.

You can now

• Manages what the agent carries between sessions

Mark lesson finishedI know this, skip it

Habit

The next time you run /compact, give it instructions that name the decisions and open items of the work. Afterwards ask the agent to list them.

References

1. Anthropic. How Claude remembers your project. Claude Code documentation. Reference. Claude Code memory
2. Addy Osmani, Ivar Soares Urdalen, Leo Simons. Memory and context: context engineering, memory kinds, memory versus RAG, context rot. Agent Engineer Course. Course. AEC-05
3. Anthropic. Explore the context window. Claude Code documentation. Reference. Claude Code context window
4. Anthropic. Commands. Claude Code documentation. Reference. Claude Code commands
5. Anthropic. How Claude Code works. Claude Code documentation. Reference. Claude Code how it works
6. Anthropic. Best practices for Claude Code. Claude Code documentation. Reference. Claude Code best practices
7. Anthropic. Manage costs effectively. Claude Code documentation. Reference. Claude Code costs