Compaction overview
Learn what compaction does, how compaction on demand and compaction at a token threshold differ, and which page covers your task.
Compaction replaces the older turns of a conversation with a summary that Claude writes on the server, so you need no summarization code of your own. It keeps a long conversation or agent task inside the context window, and it keeps the active context small, because response quality degrades as a conversation grows.
If you want to skip this overview, start with Compaction on demand to add compaction to your application. While both it and Compaction at a token threshold are in beta, Compaction on demand covers more common use cases. To clear old tool results or old thinking blocks by rule instead of summarizing them, see Context editing.
Choose how to compact
Use on-demand compaction wherever it is available.
| Compaction on demand | Compaction at a token threshold | Your own summarizer (Compact on the client) | |
|---|---|---|---|
| Who decides when | You, by sending a request | The API, when input tokens reach the trigger you set | You |
| Code you write | A compaction loop that requests the summary and swaps it in | One parameter on your ordinary requests | The summarization call, its prompt, and the history rewrite |
| What you send back afterward | The returned block first in messages, in place of the messages it summarizes | The response, appended as usual. The API drops what came before the block | Your summary, as a message of your own |
| Recent turns stay word for word | Yes: Compaction that keeps recent turns | Yes, by pausing after compaction and re-inserting them | Yes |
| Runs in the background | Yes: Compaction in the background | No: it runs inside the request that reaches the threshold | Yes, in your own code |
| Kept turns keep their thinking, on models with preserved thinking | Yes, under the conditions in Compaction and preserved thinking | No: on Claude Fable 5.1 and Claude Opus 5.5, remove or drop the thinking in turns you re-insert (see the threshold compaction examples) | No: that thinking fails the check |
| Beta header, parameter, and platforms | compact-2026-09-04 and the top-level compaction parameter. Platforms: see the on-demand Compatibility list | See the threshold Compatibility list and Basic usage | None. It runs in your code |
| Choose it when | Your application needs to control when compaction happens, can't pause while a summary is written, or must keep recent turns and their thinking | You want the API to manage context inside ordinary requests | You already run your own summarizer and it replaces the whole history with the summary |
On-demand compaction options
Compaction on demand shows a loop that summarizes the whole conversation while your application waits. The first two pages in this list change how that loop runs, and you can combine them. The third applies if you send thinking blocks back and do either.
- Compaction that keeps recent turns: when the last few turns must reach Claude word for word. The summary covers only the older turns.
- Compaction in the background: when the conversation can't pause for the summary. The request runs while work continues, and you swap the block in when it arrives.
- Compaction and preserved thinking: if you send thinking blocks back on a model with preserved thinking and you keep recent turns or compact in the background. Otherwise skip it.
- Write your own summarization prompt: when the default summary drops something a later turn needs. Your prompt replaces the default one.
- Compact again: when a conversation that already starts with a compaction block grows long again.
Find these topics on other pages:
- Request a summary is on Compaction on demand.
- Continue from the summary is on Compaction on demand. The conditions that keep thinking valid in the turns you keep are on Compaction and preserved thinking.
- When no summary comes back: see Handle a missing summary or an error on Compaction on demand.
- How it fits with the rest of the API: see Limits and interactions with other features on Compaction on demand.
- Understanding usage: see Count compaction usage for on-demand compaction, or Understanding usage for threshold compaction.
- Compatibility: each kind has its own beta header, so each page has its own list. See the on-demand Compatibility list or the threshold Compatibility list.
Threshold compaction has its own page: Compaction at a token threshold.
Was this page helpful?