Compaction Contracts

Three hours into a long refactor of a payments integration, an engineer types a constraint into the chat rather than into any file: the sandbox environment the agent is testing against goes down for maintenance every night at 02:00 UTC, so nothing that exercises the live payments API should run un-mocked after that hour. The agent takes the constraint on board and works around it for the rest of the session — mocking the relevant calls, timing a few test runs to dodge the window. The session keeps going. Files accumulate, a plan gets revised twice, a test suite grows, and somewhere past the four-hour mark the harness compacts: it replaces the accumulated conversation with a summary and keeps the session alive rather than forcing a restart. Nothing about the moment looks alarming. There may be a one-line notice that the conversation was compacted; there may not be. Either way, work continues.

Two days later, on the same long-running session, the agent kicks off an un-mocked payments call at 02:40 UTC and spends twenty minutes debugging exactly the outage the original constraint existed to prevent. Nobody made an obvious mistake. The engineer said the thing once, clearly, and at the time the agent understood it perfectly well. The constraint simply did not survive the trip through the summarizer four hours later, because nothing about a maintenance-window caveat mentioned in passing told the summarizer it outranked the dozen other details competing for space in that pass. This is not a bug report. It is what happens, reliably, when a harness’s compaction behaves according to a contract nobody wrote down — and therefore nobody could have designed around.

The lightest touch: clearing tool output

Compaction is usually described as a single event — the conversation gets summarized, space gets freed — but harnesses that manage context well treat it as a staircase, not a cliff. Anthropic’s own guidance on context engineering describes tool result clearing as the lightest-touch step, and typically the first one taken: once a tool call sits deep enough in the message history, the reasoning goes, an agent rarely needs the raw output again, only the fact that the call happened. Clearing that raw output is cheap precisely because it is also the easiest thing to lose — if it turns out to matter after all, the tool can usually just be run again. Only when that is not enough does a harness reach for the heavier operation: summarizing the conversation itself.

What survives the summarizer, and what does not

Full compaction — replacing the conversation with a structured summary — is the point where a survival contract stops being an implementation detail and starts being a design decision with consequences. Anthropic’s framing is that a well-built compaction step preserves architectural decisions, unresolved bugs, and implementation details, while discarding redundant tool outputs and message noise. That is a reasonable policy in the abstract. It is also, unavoidably, a judgment call made by a summarizer that has no way of knowing which of the dozen details in front of it is the one an engineer will need in three days — the same uneven-attention problem that produces context rot in the first place, now applied to deciding what to keep rather than what to weight. A maintenance-window caveat mentioned once, in passing, four hours before a compaction pass, looks exactly like the kind of thing a summarizer is built to discard.

Claude Code’s own documentation makes the contract more concrete than most, and is worth reading precisely because it shows how differentiated the outcome actually is depending on where an instruction lived. A project-root CLAUDE.md and its unscoped rules are re-injected from disk after compaction — reloaded, not reconstructed from the summarized conversation. Auto memory works the same way. A rule scoped to specific file paths, or a CLAUDE.md nested in a subdirectory, is not: it is lost until a matching file is read again, because it only entered the conversation in the first place when that file was touched, which makes it indistinguishable from any other message the summarizer is free to compress away. The product’s own troubleshooting guidance names the failure mode plainly: if an instruction seems to have disappeared after a compaction pass, it was either given only in conversation, or it lives in a nested file that has not reloaded yet.

The contract nobody wrote down

Generalize past this one harness and the interesting question is not what Claude Code specifically keeps — a team can look that up — but what happens on any harness whose compaction rules are not published with the same precision. Anthropic’s own guidance on long-running agents is candid that compaction, even done well, is not sufficient on its own: a frontier model looping across multiple compacted context windows can still fall short, in part because compaction does not always pass perfectly clear instructions on to the agent working after it. If the vendor that built the mechanism says as much about its own product, the reasonable default assumption for any other harness is that its compaction contract is at least as leaky — whether or not anyone has bothered to document where.

A compaction contract exists whether or not anyone wrote it down. The only choice a team has is whether to read it, or find out what it says by watching something break.

On undocumented survival rules

This is the sense in which an undocumented contract is not a hypothetical risk but the default state. If nobody on a team can say in advance which category a given instruction falls into — cleared, summarized, or reloaded — then nobody can deliberately move a load-bearing detail into the category that survives. The failure in the payments scene above was not that the engineer forgot to write the constraint down. It is that there was, in that moment, no visible reason to think writing it down mattered more for that particular detail than for any other sentence in the conversation. A contract nobody can see is a contract nobody can design against, and the loss it produces looks, from the outside, exactly like carelessness.

Three fates for anything in context

Strip away any one harness’s specifics and a compaction contract, wherever it is implemented deliberately, sorts everything that enters a session into one of three fates. Making that sort explicit — asking, for any piece of information a team cares about, which fate applies to it — is the entire discipline this chapter is arguing for.

The three fates share one property worth naming precisely: only the third is a decision available to the team using the harness, not just the team that built it. Nobody outside the vendor decides what a given tool clears first or how its summarizer weighs a detail. Every team, on every project, decides what goes into the file that gets reloaded from disk.

What this predicts, and what to check it against

Operon does not have a published cross-team benchmark for how often a compaction pass drops something a team later needed — this is a new enough discipline that the shape of the diagnostic matters more than any number attached to it today. The check is straightforward to run without new tooling: for each long session that compacts, tag whether the work that followed contradicted, ignored, or had to rediscover something established earlier in that same session, and separately note whether the detail in question lived in a reloaded file or only in conversation. A harness contract a team has actually designed around should show that failure concentrated almost entirely in the conversation-only bucket.

Designing for the third category

None of this requires waiting on a vendor to publish a clearer contract, and teams that do wait tend to find out its actual shape the same way the engineer in the payments scene did. The discipline is close kin to the one Context Debt already argues for earlier in this volume: persist decisions rather than trust them to survive a conversation. What a compaction contract adds is precision about which decisions are actually at risk, and which mechanism a team is trusting to save them.

1. Read the actual contract before relying on it. If a harness documents what survives compaction as precisely as Claude Code does, read it once and treat it as a spec. If it does not, test it deliberately: say something once, force a compaction, and check whether it is still true afterward.
2. Sort load-bearing information by fate, not by importance. An engineer who thinks a caveat matters is not the summarizer. Write anything that must survive into the category that reloads from disk, not the category that hopes to be summarized well.
3. Prefer project-root, unscoped memory over nested or path-scoped memory for anything that must always apply. The gap between an unscoped file and a rule that only reloads when a matching file is touched is exactly the gap a maintenance-window caveat can fall through.
4. Compact with a focus where the harness allows it. Directing a summarization pass toward what actually matters beats trusting the default guess.
5. Treat a post-compaction contradiction as a contract violation, not a one-off mistake. Trace which fate the lost detail actually fell into, and fix the filing — not just the immediate bug.

None of this eliminates the summarizer’s judgment call — a harness that tried to reload everything would simply move the context-rot problem forward a session instead of solving it, which is exactly the failure mode the next chapter takes up when a session has to re-ground after a loss compaction could not fully prevent. What a documented, inspected compaction contract buys a team is smaller and more useful than a guarantee: the ability to decide, in advance, which details are too important to leave to a summary.