Why Claude Code compaction drops your decisions

Compaction does not forget evenly

The mechanics are documented. As a session fills the context window, Claude Code “manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed.” The summary is lossy by design: it has to be, or it would not free any room. Most guides stop there, at “summaries are lossy.” That is true and it is not the interesting part.

The interesting part is that the loss is not random. A summarizer is answering one implicit question: what does the next turn need to know? The most obvious answer is the current state of the code, so it keeps state. A decision is not state. A decision is a constraint on future actions: use Postgres, not SQLite. The auth module is frozen, do not touch it. We tried the websocket approach and abandoned it. To a summarizer scanning for “what is happening now,” those read as old conversation about something already settled, and settled conversation is what a summary compresses hardest.

Why a decision is dropped before a file path

Sort everything in a long session into two piles and the pattern is obvious. One pile is re-derivable: if the summary forgets it, the agent can recover it by reading the filesystem. The other pile exists only in the conversation. Compaction can only actually destroy the second pile.

Anything in the left column survives whether the summary keeps it or not, because the code itself is the backup. Anything in the right column is single-copy: the conversation is the only place it ever lived. So compaction’s blast radius lands precisely on the highest-value, least-redundant content in the session. The decisions are not collateral damage. They are the target the summary is least equipped to protect.

The loss is silent, and that is the dangerous part

There is an asymmetry between the two piles that matters more than the piles themselves. When compaction drops a file path, the failure is loud. The agent calls a tool, the path is wrong, you get a file-not-found error, and you notice in the same turn. The loss announces itself.

When compaction drops a decision, nothing happens. There is no error to fire. The agent simply re-derives a choice from the code in front of it, and the new choice is plausible. It compiles. Tests may even pass, because a contradictory decision is not a syntax error, it is a divergence. You find out three commits later, when two parts of the codebase quietly disagree about how retries work, or when a constraint you stated once gets violated and no one flags it. The model is not being careless. It is doing exactly what the summary told it the situation was.

This is why “the agent re-did work it already finished” and “the agent made an edit that conflicts with an earlier one” are the same bug wearing two coats. Both are a dropped decision. Your code is safe through a compaction. The agent’s awareness of why your code is shaped the way it is, is not.

Compaction begets compaction

A dropped decision is rarely a one-time event, because the recovery behavior feeds the problem. After the first compaction the agent notices it is missing context, so it re-reads files and re-runs commands to rebuild a picture of the current state. That recovery work is bulky, and it lands right back in the window. The window refills faster than it did the first time, the next boundary comes sooner, and now the summarizer is compacting a window that already contains a summary.

Each pass compresses the survivors harder. A decision that made it through the first boundary at low resolution gets flattened again on the second, and by the third pass the agent is reasoning from a summary of a summary of a summary. The decisions that were already thin do not survive that.

What actually keeps a decision alive

The fix follows directly from the two piles. A decision you cannot afford to lose does not belong in the conversation. The conversation is volatile working memory. Move the decision into a file the moment you make it, and it joins the re-derivable pile that compaction cannot touch.

• Standing rules go in CLAUDE.md. The docs are blunt about this: “Put persistent rules in CLAUDE.md rather than relying on conversation history.” Conventions, frozen modules, the libraries you have committed to, anything that should hold for the whole project.
• Steer the summary with Compact Instructions. A section titled Compact Instructions in CLAUDE.md tells the summarizer what to keep on every compaction. Or run /compact with a focus when you see the wall coming.
• Session-specific calls go in a plan or decisions file. For choices that only matter for this task, a short DECISIONS.md or the plan file works: chose A over B because C. Files get re-read on demand and survive every compaction, every fork, and every restart.

The catch is honest and worth stating: this only protects decisions you remember to write down. The dangerous ones are made in passing, in a single sentence, mid-debugging, and those are exactly the ones that never get filed. For the full set of levers, including what /compact with a focus does and why there is no off switch, see controlling Claude Code context compaction.

The durable layer: keep the transcript, not a summary of it

Start with the honest limit. Nothing that runs Claude Code can delete the compaction boundary. The Claude Code SDK owns when compaction fires, so a wrapper cannot switch it off, and Fazm does not pretend otherwise. A single unbroken window will still compact when it hits the ceiling.

What a wrapper can change is what the conversation is stored as between windows. Claude Code already writes every message, tool use, and result to a plaintext JSONL transcript under ~/.claude/projects/. That file is the verbatim record. Every decision you ever typed is in it, uncompacted. Compaction only summarizes what the model sees in a live window. It never edits the JSONL on disk.

Fazm, an open-source native macOS app that runs Claude Code through the Agent Client Protocol, treats that transcript as the source of truth. The clearest place to see it is what happens when a chat’s working directory changes, because the Claude SDK addresses transcripts by an encoded-cwd directory. A naive host would fall back to replaying a capped summary of recent turns. Fazm does not. The function migrateJsonlForCwdChange in acp-bridge/src/index.ts (line 2506) physically relocates the transcript file into the new workspace’s project directory so session/resume finds the full record. The comment on that function states the intent in one line:

// acp-bridge/src/index.ts, line 2493
// Carry a Claude SDK transcript across a workspace (cwd)
// change so the session can be resumed with its FULL
// history instead of a capped priorContext summary.

That is not marketing language, it is a code comment explaining why the function exists. The move is logged so you can watch it happen:

The same principle runs through the rest of the app. Forking a chat is one click, and the branch carries the full prior transcript, not a paragraph about it. The compact_boundary event the terminal hides is surfaced in the UI, so you can fork before the wall instead of discovering it after. Sessions are persistent: a Mac restart reopens the window from the same verbatim transcript. None of this stops a window from eventually compacting. What it does is make sure a compaction is never the only copy of your decisions. The conversation always exists on disk in full, and resume and fork rebuild from it.