Compaction is a server-side, beta feature of the Messages API: when a conversation approaches a token threshold you set, the API summarizes older content into a compact block and continues from the summary. It is opt-in per request — nothing is summarized unless you enable it, which is also the answer to "how do I opt out": simply don't send the configuration, and your context is never compacted. The beta is available (as beta) on all five surfaces — the Claude API, Claude Platform on AWS, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry.
Enabling and configuring it
Compaction lives under context_management.edits with the beta header anthropic-beta: compact-2026-01-12. Supported models include Claude Fable 5, Opus 4.8/4.7/4.6, Sonnet 5, and Sonnet 4.6.
from anthropic import AnthropicAWS
client = AnthropicAWS()
msg = client.beta.messages.create(
model="claude-opus-4-8", max_tokens=4096, messages=history,
betas=["compact-2026-01-12"],
context_management={"edits": [{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 150000},
# "pause_after_compaction": True,
# "instructions": "Preserve all file paths and open TODOs.",
}]},
)Three knobs matter:
trigger— the input-token count at which compaction kicks in. Default 150,000; minimum 50,000. Multiple compactions can occur within a single request if the conversation keeps growing.instructions— a custom summarization prompt that replaces the default. This is your main defense against losing the wrong things: tell the summarizer explicitly what must survive (identifiers, decisions, outstanding tasks).pause_after_compaction(default false) — when true, the response stops withstop_reason: "compaction"right after the summary is written, letting you inspect it or handle continuation yourself instead of letting generation proceed.
The mechanics: one block replaces the past
When compaction fires, the response contains a compaction content block holding the summary. Your integration stays simple: append the entire response to your messages array as usual, and on the next request the API automatically drops everything before the compaction block. Your client can keep the full history for its own records; the server just stops sending the old turns to the model. When streaming, the block arrives as a normal content_block_start, then a single content_block_delta carrying the whole summary, then content_block_stop.
What you lose, and what it costs
Be clear-eyed about the trade: compaction is lossy. Verbatim detail from the summarized region — exact tool outputs, precise wording, intermediate reasoning — is gone from the model's view, replaced by the summary. For agents, pairing compaction with the memory tool (durable notes outside the window) or context editing (surgically clearing old tool results without summarizing) often works better than compaction alone.
Billing has a subtlety: the summarization pass is itself model work. The response's usage.iterations lists each compaction and message iteration separately, and the top-level input_tokens/output_tokens do not include the compaction iterations — sum all iterations to get the true billed total, or your cost dashboards will undercount. Two caching tips from the official docs: put cache_control: {"type": "ephemeral"} on compaction blocks and cache the system prompt separately, so a new compaction doesn't invalidate your whole cached prefix.
Planning is supported too: the count_tokens endpoint applies existing compaction blocks (returning context_management.original_input_tokens alongside the post-compaction count) but never triggers new compaction. The feature is eligible for Zero Data Retention.
instructions that name what must survive, and log every summary — if an agent goes off the rails after hour three, the compaction block is where you look first.Where to go next
Compaction summarizes; context editing deletes, and the memory tool persists. For sizing the problem before solving it, see 1M-token context strategies.