Prompt Caching, Context Editing and Compaction in Claude

1.Prompt caching: pay less for a prefix you repeat

Many requests begin with the same content: a long system prompt, a set of examples, a reference document, or the conversation so far. Prompt caching lets Claude resume from a stored prefix instead of processing it again, which cuts both cost and processing time. The documentation names four good fits: prompts with many examples, large background context, repetitive tasks with the same instructions, and long multi-turn conversations.

There are two ways to turn it on. Automatic caching is a single cache_control field at the top level of the request. The API places the breakpoint on the last cacheable block and moves it forward as the conversation grows, so each turn reads the earlier prefix from cache and writes only the new part. Explicit breakpoints put cache_control on individual blocks when you want exact control. The two can be combined: the automatic breakpoint takes one of the four breakpoint slots.

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

Some combinations fail. If the last block already has an explicit cache_control with a different TTL, the API returns a 400 error. It also returns a 400 if four explicit breakpoints already fill every slot.

Lifetime. The default cache lives for five minutes, and each use refreshes it at no extra cost. You can set a 1-hour TTL, which charges cache writes at 2x the base input price. The clock starts when the request that reads or writes the cache *starts*. So if a response takes four minutes to stream, the follow-up request has roughly one minute left to hit the cache.

Sources1

2.Context editing: clear what Claude no longer needs

Caching makes a long context cheaper but leaves it just as long. To actually shrink the window, remove content. Context editing does this on the server before the prompt reaches Claude. The docs frame it as curation: irrelevant content hurts model focus as well as your bill.

Tool result clearing (clear_tool_uses_20250919) targets agent loops. After Claude has processed a file read or a search result, the result is usually no longer needed. Once input passes your trigger, the API clears the oldest tool results first and replaces each with placeholder text saying it was removed. keep keeps the most recent tool uses, exclude_tools protects specific tools, and clear_tool_inputs also clears the tool-call parameters.

    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Trigger clearing when threshold is exceeded
                "trigger": {"type": "input_tokens", "value": 30000},
                # Number of tool uses to keep after clearing
                "keep": {"type": "tool_uses", "value": 3},
                # Optional: Clear at least this many tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Exclude these tools from being cleared
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

Thinking block clearing (clear_thinking_20251015) handles the reasoning that extended thinking leaves behind. Its keep setting, for example {"type": "thinking_turns", "value": 2}, sets how much recent thinking survives.

Both strategies interact with caching, and this is where the budgeting trade-off lies. Clearing tool results invalidates the cached prefix, so each clear costs a new cache write. Use clear_at_least so each invalidation removes enough tokens to pay for itself. With thinking, keeping blocks preserves the cache and clearing them breaks it at the point of clearing, so keep is a choice between cache performance and free space in the window. In both cases your client keeps the full, unedited history; you do not need to sync it with the edited version the server sends to Claude.

Sources2

3.Compaction: summarise instead of deleting

Clearing removes content by rule. Compaction replaces the older turns with a summary that Claude writes on the server, so a conversation can go past the window limit without you writing any summarisation code. For long conversations and agent workflows, the context windows doc calls server-side compaction the primary strategy. It is in beta for Claude 4.6 and later models. There are three ways to run it:

The docs recommend on-demand compaction wherever it is available. It uses the compact-2026-09-04 beta header and a top-level compaction parameter. You send back the returned block first in messages, in place of the turns it summarises. On-demand compaction can keep recent turns word for word and can run in the background. If the default summary drops something a later turn needs, you can supply your own summarisation prompt. Threshold compaction runs inside the request that crosses the trigger, so it cannot run in the background.

Sources34

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.The five-minute cache timer starts when the previous response finishes streaming.Why is that wrong?

   The lifetime is measured from the start of the request that wrote or read the cache, so time spent generating a long response uses it up.

   Covered in Prompt caching: pay less for a prefix you repeat

2. 2.Tool result clearing and prompt caching work together with no cost, so clearing a little on every turn is harmless.Why is that wrong?

   Clearing tool results invalidates the cached prefix, so each clear triggers a new cache write. Use clear_at_least so each clear frees enough tokens to justify that cost.

   Covered in Context editing: clear what Claude no longer needs

Practise it for real

Measure a request before sending it, then confirm prompt caching reduces the cost of a repeated prefix.

1. 1.Call client.messages.count_tokens with your model, a long system prompt and one user message.

   Why: Measuring first tells you how big the prefix is before you pay for it.

   You should see: A JSON response with a single input_tokens value.

2. 2.Send the same request with client.messages.create and a top-level cache_control={"type": "ephemeral"}, then print response.usage.

   Why: Automatic caching places the breakpoint on the last cacheable block and writes the prefix to the cache.

   You should see: A non-zero cache_creation_input_tokens on this first call.

3. 3.Within five minutes of the first request starting, send the same prefix with a new user message and print usage again.

   Why: A request that reuses the cached prefix within the TTL reads it instead of reprocessing it.

   You should see: A non-zero cache_read_input_tokens. The sum of the three input fields is still what the request takes up in the window.