# Directing the summary before compaction

> Load a session log with three planted facts, compact it on command with instructions that name decisions, open items and rules, and check which facts the summary kept.

Page: https://schubergphilis.github.io/ai-training/customizing-agents/compaction/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

Claude Code reads `CLAUDE.md` and its auto-memory notes at the start of
every session (How Claude remembers your project, Claude Code documentation). 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.

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

## A long session, and a summary in its place

[Where memory comes from](https://schubergphilis.github.io/ai-training/concepts/memory/#when-the-window-holds-too-much)
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 (Memory and context: context engineering, memory kinds, memory versus RAG, context rot, Agent Engineer Course). 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 (Memory and context: context engineering, memory kinds, memory versus RAG, context rot, Agent Engineer Course).

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
(Explore the context window, Claude Code documentation). 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` (Commands, Claude Code documentation).
The instructions tell the summary what to keep. Without them, the automatic
pass decides for itself what matters (Explore the context window, Claude Code documentation).
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 (How Claude Code works, Claude Code documentation). The page of best
practices says that the pass keeps code patterns, the state of files and
key decisions (Best practices for Claude Code, Claude Code documentation).

## 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
(Explore the context window, Claude Code documentation):

- 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` (How Claude remembers your project, Claude Code documentation). 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
(Explore the context window, Claude Code documentation).

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: 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.md
- A rule you typed in the chat an hour ago, word for word
- The notes in the auto-memory
- A rule with paths: in its front matter that loaded when the agent read a file

## 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
(How Claude remembers your project, Claude Code documentation). 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 (How Claude remembers your project, Claude Code documentation). If you see one, auto-memory is still
on, so start again in a new folder with the command below.

```sh
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 (Explore the context window, Claude Code documentation), 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.`
(Manage costs effectively, Claude Code documentation). 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: Check the summary without instructions

Run this, and compare with the output below.

```sh
python3 check_summary.py samples/unguided.md
```

Output:

```text
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
```

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:

```text
/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 (Explore the context window, Claude Code documentation). 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:

```text
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
(Explore the context window, Claude Code documentation). Leave Claude Code with `/exit`, and go back
to the course directory to check the file:

```sh
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: Check the summary with instructions

Run this, and compare with the output below.

```sh
python3 check_summary.py samples/directed.md
```

Output:

```text
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
```

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: 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.

#### Checkpoint: 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.

## 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 (How Claude remembers your project, Claude Code documentation). 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 (Best practices for Claude Code, Claude Code documentation) (Manage costs effectively, Claude Code documentation).

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
(Commands, Claude Code documentation), 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: 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.

#### 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 (How Claude Code works, Claude Code documentation). 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 (Memory and context: context engineering, memory kinds, memory versus RAG, context rot, Agent Engineer Course).
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 (Commands, Claude Code documentation) (Explore the context window, Claude Code documentation).
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 (How Claude remembers your project, Claude Code documentation)
   (Explore the context window, Claude Code documentation).
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 (Explore the context window, Claude Code documentation).
5. Save what the next session needs to a file, and move a rule every
   session needs into `CLAUDE.md`.

#### 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

- How Claude remembers your project, Claude Code documentation, https://code.claude.com/docs/en/memory
- Memory and context: context engineering, memory kinds, memory versus RAG, context rot, Agent Engineer Course, https://lsimons.github.io/agent-engineer-course/05-memory-and-context/
- Explore the context window, Claude Code documentation, https://code.claude.com/docs/en/context-window
- Commands, Claude Code documentation, https://code.claude.com/docs/en/commands
- How Claude Code works, Claude Code documentation, https://code.claude.com/docs/en/how-claude-code-works
- Best practices for Claude Code, Claude Code documentation, https://code.claude.com/docs/en/best-practices
- Manage costs effectively, Claude Code documentation, https://code.claude.com/docs/en/costs