# context compaction

Also called: compaction, auto-compaction, conversation summarisation, /compact, compact_20260112

Context compaction is the technique of replacing the older part of a long conversation with a summary of it, so a model can keep working on a task once the raw history would no longer fit in the context window. Anthropic ships it in the Messages API as a server-side edit strategy, compact_20260112, which triggers at a token threshold, writes a summary block, drops the messages above that block on subsequent requests, and lets the next turn continue from the summary. Claude Code exposes the same idea as /compact and as auto-compaction near the window limit.

## What context compaction actually does

A long agent run is a growing transcript: every tool call, tool result and model reply is appended and resent on the next turn. Once the transcript approaches the model's context window, the run cannot continue as it is. Compaction is the specific fix where the harness or the API asks the model to write a summary of the older part of the transcript, then swaps that summary in for the messages it replaces. From that point on, the request carries the summary plus the most recent turns, not the raw history.

The summary is model-written, not a fixed truncation. Anthropic's default prompt tells the model to produce a summary that would let a fresh session continue the task, including current state, open subgoals and anything already learned. That is the whole reason compaction is useful: it keeps the parts of the history that matter for the next decision and throws away the tool outputs and dead ends that no longer do.

## How does the compact API strategy fire?

On the Messages API, compaction is one of the strategies passed under context_management.edits, alongside tool result clearing. You add {"type": "compact_20260112"} and set a trigger in input tokens, default 150000. When a request comes in above the threshold, the server generates a summary, returns a compaction block inside the response, and on subsequent requests drops every content block prior to that block. Your client keeps the full unmodified transcript locally; the server rebuilds the compacted view each time.

Two knobs matter in practice. instructions replaces the default summarisation prompt, useful when the task has invariants a generic summary would lose, for example variable names, file paths or a plan you want carried forward verbatim. pause_after_compaction stops the response after the summary block so the caller can inspect or edit it before the next turn. There is also a beta compact-2026-09-04 header that lets you request a summary on demand rather than at a threshold, which is what a harness wants when it is deciding cadence itself.

Claude Code runs the same idea inside the CLI. /compact summarises the current session on request and takes an optional focus instruction, such as /compact Focus on code samples and API usage. Auto-compaction fires as the session nears the window, and the documented cost tip is to compact at natural breakpoints so the summary is written from a clean state rather than mid-tool-call.

## Compaction, context editing and prompt caching

These three ship in the same API surface and do different things. Compaction rewrites older turns as prose. Prompt caching leaves the turns intact and skips prefill for a prefix that has not changed. Context editing, in the same context_management block, clears specific content types instead of summarising them: the clear_tool_uses_20250919 strategy drops old tool results once the transcript grows past a threshold, keeping the most recent N tool use and result pairs.

The trade is fidelity against cache friendliness. Compaction preserves reasoning across the boundary at the cost of writing a summary and invalidating any cached prefix that covered the dropped turns. Tool result clearing is cheaper and more surgical, but keeps no memory of what those results said. Anthropic's own guidance treats server-side compaction as the primary strategy for long conversations and tool clearing as the finer instrument for agentic loops that produce large outputs and then move on.

## Where compaction hurts you

The summary is a lossy read of the transcript by the same model that will then act on it, so any misreading becomes ground truth for every future turn. Common failure shapes: a constraint stated once at the top of the session vanishes from the summary and the agent quietly stops obeying it; a tool result that looked incidental at the time turns out to have been the answer, and the agent re-runs the tool; a file path or identifier gets paraphrased and the next tool call misses.

Two habits reduce the damage. Put durable instructions somewhere the harness resends on every turn rather than relying on the summary to preserve them, for example the system prompt or an always-open scratchpad. And write instructions that name the concrete things the task needs kept verbatim, so the summariser is not guessing. Compaction is a working memory device, not an archive: if a fact must survive the whole run, do not trust the summary to carry it.

## Enabling threshold compaction on a Messages API request

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,          # full local transcript, unmodified
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 120000},
                "instructions": (
                    "Preserve file paths, variable names, the current plan "
                    "and any unresolved TODOs verbatim."
                ),
            }
        ]
    },
)

# On the turn where the trigger fires, the response carries a compaction
# block. Append the whole response to `messages` as usual; on the next
# request the server drops every block above the compaction block and
# continues from the summary.
messages.append({"role": "assistant", "content": response.content})

The client keeps the full transcript; the server rebuilds the compacted view each turn from the compaction block onward. Custom instructions are how you stop the summariser from paraphrasing away the identifiers you actually need.

## Frequently asked

Q: Is compaction the same as truncation?
A: No. Truncation drops the oldest messages and keeps the recent ones as they were. Compaction asks the model to write a summary of the older messages and then continues from that summary. Truncation loses everything it drops; compaction keeps a lossy read of it. The trade is that compaction spends output tokens on a summary and invalidates cached prefixes, while truncation is free and dumb.

Q: When should I turn compaction off?
A: For short interactive chats that will never approach the window, and for workloads where prompt caching is doing the real work of keeping cost down, because a compaction event invalidates the cached prefix above it. Also skip it when the transcript itself is the deliverable, for example a chat log you plan to replay or audit turn by turn, since the summary replaces the messages it covers on subsequent requests.

Q: Does /compact in Claude Code use the same mechanism?
A: It is the same idea and a separate implementation. Claude Code runs on top of the Messages API and manages its own transcript, so /compact is the CLI trigger for a summarisation pass over the current session, and auto-compaction runs the same pass when the session nears the window. The documented tip is to compact at a natural breakpoint and to add a focus instruction, such as /compact Focus on code samples and API usage, so the summariser knows what to keep.

Q: Does compaction give a model memory?
A: Only within one run. The summary lives in the same conversation and lets that conversation continue past the window; nothing about it persists to the next session unless your harness saves it. For state you want available across sessions, you need memory, which is an out-of-request store your code chooses when to resend, not a property of the model.

## Sources

- Anthropic docs: Compaction: https://docs.claude.com/en/docs/build-with-claude/compaction
  the compact_20260112 strategy, the 150000 input-token default trigger, the compaction block mechanics, and the instructions and pause_after_compaction parameters
- Anthropic docs: Context editing: https://docs.claude.com/en/docs/build-with-claude/context-editing
  the sibling clear_tool_uses_20250919 strategy, its interaction with prompt caching, and the framing of server-side compaction as the primary strategy for long conversations
- Anthropic: Managing context on the Claude Developer Platform: https://www.anthropic.com/news/context-management
  the launch note that introduced context editing and the memory tool as the two mechanisms for long-running agent context
- Anthropic docs: Manage costs (Claude Code): https://docs.claude.com/en/docs/claude-code/costs
  the /compact command, the custom focus instruction pattern, and the guidance to compact at natural breakpoints

## Related terms

- context window: https://ai.developertools.io/context-window/index.md
- memory: https://ai.developertools.io/memory/index.md
- prompt caching: https://ai.developertools.io/prompt-caching/index.md
- session: https://ai.developertools.io/session/index.md
- harness: https://ai.developertools.io/harness/index.md
- agent: https://ai.developertools.io/agent/index.md

Canonical page: https://ai.developertools.io/context-compaction/
Edited by Derek Wonk. Last updated 2026-09-16.