Pattern Matrix/White Paper/P2

P2 · Semantic Compaction

What problem it solves

The information has already come in, the agent has run dozens of turns, and the context is full, so it has to be compacted before it can continue. Once a 487-token connection-pool-exhaustion stack trace gets compressed into "a database error occurred," the agent no longer knows that enlarging the pool or adding retries has already been ruled out, so it repeatedly retries options that were already rejected, wasting both time and tokens.

Semantic compaction turns this into an engineering practice: a three-level cascade (clean up verbose tool results → summarize old conversation → compress further) is triggered progressively against context-occupancy thresholds, each level more aggressive than the last. It governs the capacity of the context window within a single session. It does not aim for unlimited compression but for every segment of history to be produced by high-quality reasoning, so that it does not poison the next segment.

Why the coordinate is "Perception × Chain"

• Vertical axis · Perception: Compaction operates on the input history that has "already been taken in," performing an input → semantically-preserving-compression. It is not about writing information into cross-session storage (memory), nor about reasoning through a problem (reasoning); it decides which evidence to keep in the current window.
• Horizontal axis · Chain: The three levels of compression form a cascade, each level taking the output of the previous one. The original text is relayed through cleanup, summarization, and further compression, getting tighter at each step. What flows along the chain is the compressed history.

Core mechanism

Compaction is triggered in tiers, from light to heavy according to context occupancy, with the error stack protected across the whole flow:

Two mechanisms are key to industrial-grade compaction. First, the trigger threshold. Claude Code triggers at 95% by default, but quality degradation begins as early as 70%-80%. Waiting until 95% to compact means the last stretch of reasoning is itself low-quality reasoning, and once compressed into history it poisons the whole chain. The community consensus is to set it to 60%-70% and compact early, giving up some window space in exchange for stable reasoning quality. Second, the persistent anchor. Re-summarizing loses a little every time (like the grain that builds up when you repeatedly enlarge a photo); iterative merging does not lose what has already been remembered. The anchor maintains four fixed fields—intent, changes made, decisions made, next step—of which "ruled-out options" is the most critical. The root cause of an agent repeatedly trying rejected options is precisely that this field is missing.

Production scenarios that fit

• Long-session customer-support agent: A user reports a complex fault, the agent both converses with the user and calls internal tools, and over 4 hours runs 80-120 turns, which inevitably hits compaction. The anchor fields can also be exported directly as a handoff sheet for second-line engineers.
• Multi-step debugging and coding agents: Runs of more than 40 turns where tool output is often very long (logs, data queries, API responses), well suited to keeping "what was done" while masking the old "what was seen."
• Research assistants, data analysis, and consulting-style long-session agents: Any task that runs beyond 20-30 turns and exceeds 60% context occupancy should start compaction.

Where it tends to go wrong

• Summary loses key information: Compressing "line 47, max_connections=20, queue_depth=347" into "a database error occurred" loses all three locating numbers, and a few loops later the agent has to re-read the log. The summary prompt must hard-code "all numbers, file paths, and function names must be preserved."
• Compacting across an error boundary: Triggering compaction in the middle of the agent's active reasoning—say, just after it has narrowed the bug down to two candidate files and is about to decide—causes the reasoning context to be lost when compaction kicks in, forcing a restart. Compact only conversation segments that are complete and that the agent has already moved on from.
• Drift from repeated compaction: Compressing already-compressed content amplifies the information into distortion. The same segment of history may not be compressed more than twice; if that is still not enough, hand off to a human or open a new session rather than forcing Level 3.
• Compacting too late: Claude Code triggers at 95% by default, meaning compaction happens after "a stretch of low-quality reasoning has already occurred." Set it to 60%-70%.
• Never compact the error stack: The error stack is the agent's feedback loop; losing it is amnesia. It must be specially protected across the entire compaction flow.

Key metrics

• Level 3 trigger rate (healthy zone < 5%): The share taken by the most aggressive tier. Every L3 means a +30% probability of information drift; a class of sessions repeatedly entering L3 indicates its token budget is misconfigured or that it should exit early.
• Average compression ratio (healthy zone 0.30-0.50): after/before. Below 0.20 is over-compression with a high probability of losing key information; above 0.60 is under-compression that soon has to be compacted again.
• Error stacks preserved per compaction (any zero preservation triggers a P0 alert): The most critical metric. Zero preservation means the error-recognition patterns leaked through, and the next time the agent hits the same bug it has no memory of it.

Minimal implementation skeleton

should_compact(total, budget): total / budget >= 0.60   # 60% early compaction
            compact(turns, target):
                Split: old compressible | protected (most recent N turns + all error stacks, never compacted)
                Level 1: clean up verbose tool output → return if enough
                Level 2: summarize and merge old turns into anchor (intent/changes/decisions/excluded/next) → return if enough
                Level 3: compress old errors into a list but keep core numbers, keep the most recent 3 in full
            Record one CompactionEvent per compaction (level / before-and-after tokens / error stacks preserved)
            

The anchor's "ruled-out options" field must be hard-coded in the summary prompt as "ruled-out options must be preserved; new decisions are appended, not overwritten." The summarization call can use a cheap model.

Enterprise deployment example

An enterprise customer reported a P1 API gateway fault, a support agent picked it up, and the session ran from 2 p.m. for 4 hours over 80-120 turns, with context occupancy climbing to 150K-200K. The rhythm is designed around three points in time: at about 100K (55%) the first compaction runs Level 1, cleaning up only verbose tool output, and the anchor is written for the first time with the diagnoses made and the options ruled out; at about 120K (67%) the second compaction runs Level 2, the old conversation verbatim is gone, and the anchor becomes the only historical memory thereafter; on entering the SLA countdown zone, Level 3 is triggered proactively and a handoff is exported, sending the anchor plus the ruled-out options in full to second-line engineers. The key discipline is that after Level 3 the agent is no longer allowed to reason through important decisions—L3 is the signal that the agent should exit, not an instruction to compact once more. This handoff sheet lets a human agent read it and take over in 5 minutes.

Relationship to other patterns

• Context Triage (P1): Complementary. Triage governs future tokens (which ones come in), compaction governs past tokens (how to compress what has already come in without losing the key parts). P1's "load after P2-level compaction" is precisely where the two connect.
• Progressive Discovery (P3): The three divide the labor across different time dimensions of tokens. Triage governs the future, compaction the past, and discovery the unknown. A production agent needs all three; doing one fewer leaks in that dimension.
• Layered Memory (Memory module): The boundary must be held. Compaction governs window capacity within a single session, and all compaction events are cleared the moment the session ends. Remembering "this user reported a similar bug last week" is memory's job; do not make the compactor do memory's work.

What this pattern teaches

Good compaction is itself a form of cognition—what the agent chooses to keep determines what it can reason clearly about next; compacting away an error stack is like deleting the tests during a refactoring, so that on the next regression you won't know where it broke.

This page is part of the ADPS pattern white papers. Back to the pattern matrix, or see the runnable code catalog.