Pattern Matrix/White Paper/P2

Problem

As a long task progresses, the context approaches capacity and some history must be compacted. If a stack trace containing connection-pool settings, queue depth, and call sites becomes only “a database error occurred,” the evidence and previously rejected remedies disappear. The agent may then repeat work that the earlier session already ruled out.

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.

Classification: 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.

Solution and mechanics

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

The trigger and the persistent anchor determine compaction quality. Set the trigger from evaluations of the chosen model, tool-output mix, and local long-running tasks, leaving margin before quality begins to decline. Merge new information into a stable anchor instead of repeatedly summarizing the whole history. The anchor should record intent, changes, decisions, ruled-out options, and the next step. Ruled-out options keep the agent from retrying paths that have already failed.

Applicability

• Long-session customer-support agent: An intermittent fault may require conversations and internal tool calls across shifts. The anchor can also become a handoff packet for second-line engineers.
• Multi-step debugging and coding agents: Long logs, data queries, and API responses can be replaced with re-fetchable pointers after their evidence has been recorded.
• Research, analysis, and consulting agents: Trigger compaction when context growth begins to affect task quality in local evaluations.

Known failure modes

• Summary loses key information: Reducing an error with line numbers, pool settings, and queue depth to “a database error occurred” removes the basis for diagnosis. Require the summary to preserve business figures, file paths, function names, and error codes.
• 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: Repeatedly summarizing the same material compounds omissions. Track summary lineage and limit re-compaction; if capacity is still insufficient, hand off or start a new session with a structured packet.
• Compacting too late: Waiting until the window is nearly exhausted may allow degraded reasoning before compaction begins. Determine the trigger through replay evaluation.
• 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.

Verification and metrics

• Level 3 trigger rate: Observe how often each task class reaches the deepest tier. Repeated Level 3 use points to a budget, handoff, or early-exit problem.
• Average compression ratio: Record after/before together with downstream task quality. A smaller context is not automatically better; replay must confirm that key facts and exclusions remain recoverable.
• Critical-evidence retention: Check that error stacks, test results, file paths, and business parameters survive. Missing safety evidence should trigger an alert.

Reference implementation

should_compact(total, budget, threshold): total / budget >= threshold
            compact(turns, target):
                Split: old compressible | protected (recent evidence + all error stacks)
                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: reduce old errors to structured records while keeping key parameters and recent evidence
            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.

Illustrative scenario

Consider a customer reporting an API that fails intermittently during peak traffic and succeeds on retry. A support agent works across shifts, calling log search, metrics, and configuration tools while raw outputs accumulate. The system first removes verbose outputs whose evidence has already been captured and writes an anchor containing symptoms, actions, and ruled-out paths. If the session keeps growing, earlier dialogue is merged into the anchor. If the investigation still does not converge, the runtime exports the anchor and evidence pointers for a second-line engineer.

The handoff should be operational: current symptoms, evidence for and against each hypothesis, rejected paths, and the next untested step. Deep compaction is also an exit signal. Set thresholds from observed session distributions and replay quality rather than inferring them from ticket severity.

Related 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.

Design conclusion

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.