Compaction in the Claude API: let Claude summarise as long agents run

The longer an agent runs, the longer its history: more tokens per turn, slower responses, and lower quality as context bloats. Previously you had to write your own summarisation code and swap the history. The Claude API now has server-side compaction: Claude writes a summary of older turns on the server, with no summarisation code of your own. It's how you keep long-running agents inside the context window without token costs growing forever.

Two kinds of compaction

The docs recommend on-demand compaction wherever it's available because it's more flexible. But the threshold kind is the fastest way to get started.

Threshold compaction: one parameter

{
  "model": "claude-opus-5-5",
  "max_tokens": 4096,
  "messages": [...],
  "context_management": {
    "edits": [{
      "type": "compact_20260112",
      "trigger": {"type": "input_tokens", "value": 150000},
      "instructions": "Keep design decisions, files changed and unfinished work."
    }]
  }
}

• trigger defaults to 150,000 input tokens, minimum 50,000.
• instructions fully replaces the default summarisation prompt rather than adding to it.
• pause_after_compaction: true returns with stop_reason: "compaction" so you can edit messages (e.g. reinsert the last few turns) before continuing.

When it triggers, the response starts with a {"type": "compaction", "content": "..."} block. Append the whole response to messages as usual; the API ignores everything before the last compaction block.

Counting cost correctly

"usage": {
  "input_tokens": 23000, "output_tokens": 1000,
  "iterations": [
    {"type": "compaction", "input_tokens": 180000, "output_tokens": 3500},
    {"type": "message", "input_tokens": 23000, "output_tokens": 1000}
  ]
}

The top-level input_tokens/output_tokens exclude the compaction iteration. For total billed usage, sum every entry in usage.iterations. Re-sending an existing compaction block adds no compaction cost.

Combining with prompt caching

• Put a cache_control breakpoint at the end of the system prompt: when compaction happens, the system prompt cache stays valid and only the new summary is written.
• You can also put cache_control on the compaction block itself to cache the summary.

Compaction or context editing?

Context editing clears old tool results or thinking by rule, without summarising. Compaction summarises everything older. For agents with bulky tool results that rarely need remembering, context editing is enough; for long conversations that must keep the thread of decisions, use compaction.

Risks and caveats

• Summaries lose detail: anything not in the summary is gone. Write custom instructions listing what must be kept.
• Python SDK serialisation errors: the docs warn that a plain model_dump() on blocks can cause a 400; use to_dict() or model_dump(exclude_none=True).
• Thinking blocks: on models with preserved thinking, threshold compaction doesn't keep thinking for reinserted turns; see the dedicated guide.
• Still in beta: parameter names and headers may change; pin versions and watch the changelog.

How to apply it

• Dev: Add the threshold compaction parameter to long-running agents; log usage.iterations to see the real cost.
• Tech Lead: Write domain-specific summarisation instructions and test with evals: can the agent still finish the task after compaction?
• PM: Compaction makes multi-hour agents feasible; estimate cost by number of compactions, not just turns.