Context compaction: what it is and how to stop losing your work

Short version: Context compaction is what happens when your client hits the context window limit and replaces the conversation history with an automatic summary. The summary keeps the plot but drops the load-bearing details: exact wording of decisions, numbers, the “why”, and what’s left to do. To stop losing work, write important facts to external memory the moment they appear, close out stages explicitly, and don’t drag a session into an emergency compaction.

What compaction is

Every model has a context limit — the maximum number of tokens it can see at once. A long session eventually hits it. The client (Claude Code, Cursor, others) then compacts: it hands the conversation history to the model with a “summarize the important parts” request and continues with that summary instead of the full history.

Mechanically, this is reasonable: the alternative is cutting the session off mid-task. The problem isn’t that compaction happens — it’s what the summary drops.

What gets lost

Summarization is a one-pass judgment call about what mattered. In practice, the summary holds the plot (“we were fixing auth”) and loses the load-bearing details:

• Exact wording of decisions. “We decided to use JWT” survives compaction. “JWT, because the mobile app can’t do cookies and sessions don’t scale across two regions” is a coin flip. A week later the agent confidently proposes sessions — the arguments are gone.
• Numbers and constraints. A 200 ms threshold, a 10,000-row limit, the agreement to not touch the users table until the migration — trivia to a summarizer, critical to the work.
• Open threads. “Migration still unfinished, worker needs updating” tends to collapse into “task nearly done”.
• Rejected options. The sneakiest loss: “we ruled out Redis because of infra cost” compresses to nothing, and the agent proposes Redis again. You explain again. Every week.

How to tell compaction already hit you

Three characteristic symptoms mid-session:

1. The agent “forgot” an agreement from the start of the conversation — proposes the thing you talked it out of an hour ago.
2. Answers stay right in spirit but go blurry: specific file names, numbers, references to “that bug” disappear.
3. The agent re-asks settled questions, or gets excited about a “new” idea you rejected together.

Many clients show a compaction indicator — but noticing it in time rarely works. The symptoms above are more reliable than the UI.

How to work so compaction doesn’t matter

Write facts down the moment they appear, not at the end. A decision exists once it’s recorded. If the agreement “deploys go only through the script with the preflight guard” lives only in chat history, it vanishes at the first compaction. If it’s written to external memory (in our case, the MaxGraph graph via add_observations), compacting the history doesn’t touch it: the agent restores it from memory at any point. This is the core habit change: “recorded as soon as I learned it” instead of “we’ll summarize later”.

Close out stages explicitly. Finished a chunk of work — record the outcome: what’s done, what’s left, which decisions were made. Our session_close does this: outcomes go into memory, and the next session starts from a digest rather than archaeology.

Short sessions over marathons. An all-day session is guaranteed to hit compaction — probably more than once. A one-stage session almost never reaches the limit. It’s also cheaper: a long history is paid for on every request, and by our measurements session discipline is one of the main ways to save tokens.

After compaction, restore from memory. If compaction already happened, don’t trust the summary: have the agent re-read the memory digest (session_start) and check the current task against recorded decisions. The summary is about the plot; memory is about facts.

Where the memory combo solves the whole problem

Compaction only cuts what lives inside the window. Everything stored outside it — in a memory graph, in project files, in the issue tracker — is untouchable. So the working setup looks like this: the window is for the current conversation, memory is for everything that must outlive the conversation. Separate those two layers and compaction stops being a source of losses and becomes a technical detail you don’t even notice.

FAQ

Is compaction the same as “the model forgot”? No. The model doesn’t “forget” — the client physically replaces the full history with a summary, and from then on the model sees only the summary. Forgetting between sessions is a separate mechanism: the history simply isn’t loaded. More on that: why your AI agent forgets your project.

Can I disable compaction? Usually not — it’s the client’s emergency mechanism for window overflow. What you can do is never reach it: short sessions, explicit stage closures, moving facts into memory before the window fills.

Doesn’t a huge context window solve this? It postpones it, not solves it. A million-token window still ends, and long contexts hurt accuracy: the model gets worse at finding details in the middle of a long transcript. Plus every request with a giant history costs noticeably more.

Why not just re-read the summary after compaction? A summary is the summarizer’s opinion of what mattered. It has no exact wording and can confidently distort details. Check against primary records — memory — not a derivative of the history.

What’s next

• Set up memory in 10 minutes: for Claude Code or for Cursor.
• Terminology — compaction, context window, digest: the agent memory glossary.
• The big picture of approaches: the agent memory guide.