Context Compaction

Context compaction summarizes the older part of an agent's transcript when it approaches the context-window limit, then continues the task on top of that summary instead of the raw history (Claude Platform docs). The core trade-off: the agent keeps working past its token budget, but the summary is lossy — high-level state survives while exact figures, verbatim phrasing, and edge-case details silently drop (Claude Cookbook). Anthropic defines it as "taking a conversation nearing the context window limit, summarizing its contents, and reinitiating a new context window with the summary," and calls it the first lever for long-horizon agent coherence (Anthropic Engineering).

Problem

Long-horizon agent work hits two walls. The hard wall: dialogue, reasoning, and tool results accumulate until the transcript exceeds the model's context-window and the task aborts mid-flight. The soft wall arrives earlier — context-rot. Chroma's July 2025 evaluation of 18 models across the Claude, GPT, Gemini, and Qwen families found accuracy degrading as input grows even when far below the maximum window; on LongMemEval, a focused ~300-token prompt outscored the full ~113k-token prompt across every model family tested (Chroma Research).

The symptoms a practitioner recognizes: the agent quietly forgets instructions given early in the session, per-turn cost climbs because the full history is resent each turn, and multi-hour runs die with a context-limit error. Compaction targets all three by shrinking the working transcript — at the fidelity price documented below.

How to apply

"Compaction" names at least three Anthropic surfaces with different defaults. Pick the surface first and do not carry one threshold across surfaces. Defaults and limits below: as of 2026-07-10.

Surface	Mechanism	Default trigger	Key controls
Messages API compact_20260112 (beta)	Server detects the token threshold, emits a compaction block with the summary; subsequent requests drop everything before that block (platform docs)	150,000 input tokens; configurable down to a 50,000 minimum	instructions, pause_after_compaction, header anthropic-beta: compact-2026-01-12
Claude Agent SDK (Python) tool_runner	Higher-level compaction_control wrapper over the same idea (cookbook)	context_token_threshold: 100,000 tokens	model (route summarization to a cheaper model), summary_prompt
Claude Code	Manual /compact (accepts focus text) plus an automatic pass as context nears the limit; older tool outputs are cleared first, summarization runs only if that is not enough (Claude Code docs)	Model- and mode-dependent; no single published percentage	"Compact instructions" block in CLAUDE.md (costs docs); CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, 1–100, can only lower the threshold (env vars)

Then, in order:

1. Diagnose before enabling. Anthropic's decision rule: use compaction when context climbs from accumulated dialogue and reasoning; use tool-result-clearing when the bloat is large re-fetchable file or API reads; use the memory tool when the next session must build on this one (Claude Cookbook).
2. Write the summarization prompt yourself. A custom instructions string replaces the default prompt entirely — it does not append to it (platform docs). Enumerate what must survive: modified files, test commands, accepted and rejected decisions, hard constraints.
3. Keep invariants outside the compacted transcript. In Claude Code, project-root CLAUDE.md and auto memory are re-injected from disk after compaction; path-scoped rules and nested CLAUDE.md files are lost until a matching file is read again; invoked skill bodies are re-injected but capped at 5,000 tokens per skill and 25,000 tokens total (context-window docs). In the raw API, set pause_after_compaction: true to pause right after the summary and re-attach recent messages or pinned content before continuing (platform docs).
4. Meter the real cost. Top-level usage.input_tokens and output_tokens exclude the summarization call; sum the usage.iterations array, which carries a type: compaction entry (platform docs).
5. Tune the trigger to the workload. Anthropic's worked example — five support tickets processed sequentially with a 5,000-token threshold — cut total tokens from 208,838 to 86,446 (−58.6%) across two compaction events, as of 2026-07-10 (cookbook).

When to use / When not to

Use compaction when:

• context climbs steadily from dialogue and the agent's own reasoning, and the task cannot finish inside the window (Claude Cookbook);
• the workload is sequential with natural phase boundaries — batch processing, multi-phase pipelines — where earlier phases matter only as outcomes (cookbook);
• sessions in claude-code routinely run long enough to hit the limit and you want continuation instead of an abort (Claude Code docs).

Do not use it when:

• the bloat comes from large, re-fetchable tool outputs — tool-result-clearing removes those mechanically, with no inference call and no information loss (Claude Cookbook);
• the next session needs this session's findings — that is cross-session memory's job, not a summary's (Claude Cookbook);
• the task finishes well under 50,000–100,000 tokens, where summarization overhead is not justified (cookbook);
• you need a full audit trail, or each step depends on exact details of prior steps — a lossy summary breaks both (cookbook);
• the loop runs server-side extended thinking or web search — the Agent SDK guidance explicitly recommends against compaction_control there (cookbook).

Trade-offs and failure modes

An extra inference pass. Every compaction is an additional sampling iteration, billed and rate-limited on top of the ordinary turn — and excluded from the top-level usage fields, so naive dashboards undercount it (platform docs).

Lossy by design. In Anthropic's own probe (as of 2026-07-10), a ~2,783-token summary replaced 160K+ tokens of conversation: 3 of 3 high-level facts survived, 0 of 3 obscure specifics — appendix-table values, heterogeneity statistics — did (Claude Cookbook).

Measured loss is large. A 2026 preprint reports summarization destroying roughly 60% of a knowledge base's facts, replicated across four frontier models — architectural rather than model-specific. Under cascading compaction, about 54% of project constraints were lost while the model kept working with full apparent confidence, which the authors call goal drift (arXiv 2603.17781).

Thrashing. If a single file or tool output is large enough that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and raises an explicit error instead of looping (Claude Code docs).

Unguided self-summarization. Cognition found that Devin's model-written CHANGELOG/SUMMARY notes would "paraphrase the task, leaving out important details," producing knowledge gaps — and the agent sometimes spent more tokens writing summaries than solving the problem. They kept a dedicated context-management layer instead of trusting free-form model summaries (Cognition).

Erased error evidence. Manus deliberately leaves failed actions and stack traces in context, because a model that sees its own failure "implicitly updates its internal beliefs" away from repeating it (Manus blog). A compaction prompt that flattens recent failures into "attempted X, failed" removes exactly the signal that in-session adaptation depends on.

Variants and related

• tool-result-clearing — the mechanical sibling: replaces old tool_result blocks with placeholders; no inference cost, and the content stays re-fetchable. Composes with compaction — clear cheap tool bloat at a lower threshold, compact accumulated dialogue at a higher one (Claude Cookbook).
• Memory tool — persistence across sessions rather than compression within one. Anthropic's worked research-agent case combined clearing, compaction, and memory to cut peak context from 335K to roughly 170K tokens, as of 2026-07-10 (Claude Cookbook).
• Restorable compression (Manus). Manus designs its compression to be reversible — drop a web page's content but keep its URL, omit a document body but keep its file path — in deliberate preference over irreversible summarization (Manus blog). Mechanically this is closer to tool-result clearing than to Anthropic's compaction-as-summarization; watch the terminology when reading vendor engineering posts.
• subagent isolation — delegating large reads to a subagent keeps them out of the primary window entirely; only a scoped summary returns, by design rather than by a threshold trigger (Claude Code docs).
• A bigger window is not a substitute. Recent Claude models support a 1,000,000-token context window (as of 2026-07-10), and compaction works identically at the larger limit (Claude Code docs) — while context-rot results show that raw bulk itself degrades recall (Chroma Research). Compaction is one tool inside context-engineering, not a stopgap until windows grow.