Compaction — and why you shouldn't fully trust it
A short explainer on how Claude Code keeps long conversations alive, what it costs you, and what to do about it.
---
The everyday version
Picture this. You're on the family WhatsApp group, planning your cousin's wedding. It's been going on for weeks — aunts, uncles, cousins, everyone has opinions. Hundreds of messages a day. Menu debates, sangeet song lists, who's picking up the grandparents from the airport, which sweet shop is making the jalebi.
At some point WhatsApp is bursting at the seams. Imagine your phone got clever and replaced last week's chunk with a sticky note:
▎ "Venue finalised: Hotel Sahara, Lucknow. Catering: Bikaner Sweets. Sangeet on the 14th. Cards being handled by uncle. Cousin bringing the outfit from Delhi."
The recent messages stay intact, exactly as written. The older ones become a gist.
That sticky note is great. It captures the decisions — who's doing what, what's been picked. But it also quietly drops the fine grain. The exact sweet box order — "two kilos of one sweet, one kilo of another, skip the third one because Grandpa doesn't like it"? Reduced to "Bikaner Sweets, finalised." The specific time slot the priest gave for the ceremony? Paraphrased into something fuzzier.
Now imagine you come back to the group next week and ask, "what time did the priest say for the ceremony?" Your cousin, looking at the sticky note, answers confidently — but with the gist, not the exact time. You don't notice until the morning of the wedding when the groom's procession arrives 40 minutes off.
That's compaction.
---
The technical version
A Claude Code session is a growing list of messages — your prompts, the model's responses, tool calls, tool results — and that entire list gets re-sent to the model every turn. The model has a fixed context window (typically around 200K tokens). As cumulative tokens approach that ceiling, the harness intervenes: it slices off the older portion of the message history and replaces it with a single model-generated summary.
Recent turns stay verbatim.
The next turn, the model sees:
[ summary of turns 1–40 ] ← compacted
[ turns 41–60 verbatim ] ← recent, intact
[ your new message ]
A few properties worth internalizing:
Threshold-driven, not turn-driven. Compaction fires on token usage, not message count. A session full of long tool outputs compacts much sooner than one with chatty back-and-forth.
Lossy and non-deterministic. The summary is itself produced by a model call — best-effort, not deterministic compression. Decisions, file paths, and stated intent usually survive. Verbatim text — regexes, config blocks, exact error messages, raw tool output — frequently does not.
Sticky. Once a session is compacted, the summary becomes part of its canonical history. When you resume via --continue or --resume, you inherit the summary. There's no "uncompact."
Per-session. Memory and CLAUDE.md are unaffected — they load fresh every turn from disk. They're durable in a way the transcript isn't.
---
Where it goes wrong
Three failure modes are worth naming, because if you don't know they exist, you'll get bitten by them:
Model drift. The summary emphasizes what seemed salient to the summarizer. Nuance, minority threads, and dissenting arguments get flattened. If you spent ten turns debating whether to use approach A or approach B, the summary likely says "decided on A" — and the reasoning you'd want to retrieve next month is gone. Like the family group quietly forgetting why you ruled out the first venue.
False confidence. This is the most dangerous one. The model still answers as if it remembers, but it's working from a paraphrase. "As we discussed earlier" can become a confident hallucination, with no obvious tell.
You'll only notice when the answer is subtly wrong — and by then, the wedding procession is already late.
Tool-output erosion. Long stdout blobs — test failures, logs, JSON dumps — compress hardest. If you pasted a 500-line stack trace and didn't act on it, the summary will reduce it to "test failed in module X." Good luck recovering the actual error.
---
What to actually do
The mental model that works: the session is great for in-flight work, but it's not durable storage. Plan accordingly.
1. Treat important decisions like a small shopkeeper's ledger. Write them down the moment you make them. Memory file. CLAUDE.md. A progress.md checkpoint in the repo. Anything that lives on disk and gets re-read fresh. The neighbourhood shopkeeper doesn't trust memory for the month's credit — he writes it in a notebook the same minute.
2. Manually checkpoint at logical boundaries. Ask Claude: "summarize where we are, what we've decided, and what's next." Then save that output yourself, in a location you control. It's exact, it's durable, and it survives any future compaction.
3. Trigger compaction explicitly with /compact before a known-long stretch. Choose where the boundary lands, instead of letting it happen mid-thought.
4. Move stable facts to CLAUDE.md. Project conventions, build commands, architectural decisions — anything that's true across sessions belongs there. It gets re-injected every turn rather than relying on transcript recall.
5. Keep sessions task-scoped. One focused task → one focused summary. Cramming a week of unrelated work into one mega-session means the compaction summary becomes vague, because the source material was vague.
6. Read the room. If a session has gone very long and Claude is starting to misremember, that's a signal — wrap up, save what matters, start fresh. Don't push through.
---
The takeaway
Compaction is the right design for the problem it solves. Without it, long sessions would hit a wall. With it, you get continuity at the cost of fidelity — and most of the time that trade is correct.
The cost only shows up when you treat the session like a perfect transcript. Don't. Treat it like a friend who came back from a long wedding-planning meeting and told you "don't worry, everything's sorted." They remember the gist, the vibe, the broad strokes. But for the exact ceremony time and the exact sweet order? You want the WhatsApp messages, or better still, a notebook you wrote in yourself.
Disclaimer - Views are based on my usage/perception and may change as specifics may evolve. Always go by the official docs.
