What you will be able to do
- Set output_config.effort for a workload's latency and accuracy target, and say why thinking budgets and max_tokens are the wrong levers on current models
- Distinguish tool-result clearing, thinking-block clearing, compaction and the memory tool by what each removes or keeps
- Choose on-demand, background or threshold compaction based on whether the agent can pause, and fix a summary that drops needed facts
- Use the memory tool to carry state across sessions that each start with an empty history
- Match a context lifecycle strategy to a workload's stated session length, latency and accuracy requirements
Key concept
Active context as a curated, finite resource — Each turn, an agent's context should hold only what the next step needs. Effort sets how many tokens Claude spends on a turn, and the lifecycle strategy (clearing, compaction, memory) sets which earlier tokens come along with it.
1.Effort controls how much Claude spends per turn
A long-running agent has two budgets to manage: how much it reasons on each turn, and how much history it carries into the next one. The effort parameter sets the first. A context lifecycle strategy sets the second. Getting either one wrong looks the same from outside: slow turns, rising cost, or an agent that loses track of its work. So you choose them together, against the workload's session length, latency target and accuracy bar.
Effort is one request field, output_config.effort. It trades thoroughness against token efficiency on the same model, and it is not an on/off switch for thinking. It applies to every output token: the reply text, the arguments of tool calls, and thinking when thinking is active. Lowering it makes an agent faster and cheaper in two ways at once. The model thinks less, and it makes fewer, shorter tool calls.
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
output_config={"effort": "medium"},
)| Level | Behaviour | Typical use |
|---|---|---|
| max | No limit on token spending; the deepest reasoning | Tasks that need the most thorough analysis possible |
| xhigh | More capability for long-horizon work | Agentic and coding tasks that run over 30 minutes, with token budgets in the millions |
| high | Spends as many tokens as the task needs | Complex reasoning, difficult coding, agentic tasks |
| medium | Balanced, with moderate token savings | Agentic tasks that must balance speed, cost and performance |
| low | Most efficient, with some loss of capability | Simple tasks that need the best speed and lowest cost, such as subagents |
The default level depends on the model, which matters when you migrate. Most models default to high. Claude Opus 5.5 and Claude Haiku 5.5 default to medium, so a request that omits effort runs one level lower on Opus 5.5 than it did on Claude Opus 5. Claude Sonnet 5.5 defaults to high on the Claude API. Not every model that supports max also supports xhigh.
On some models, effort is the only control you have over thinking. Adaptive thinking is always on in Claude Opus 5.5, and a request that tries to disable it fails at every effort level. On that model, the amount of reasoning is set entirely by effort. Some models let you change effort per message mid-conversation without invalidating the prompt cache. The caching rules themselves are covered in cache breakpoints and invalidation.
Checkpoint 1 of 9· Fill the gap
This request should run Claude Opus 5.5 at medium effort. Which request field completes it?
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
? ={"effort": "medium"},
)Effort goes in one request field, output_config.effort. It is not part of the thinking configuration. It also applies to every output token (reply text, tool-call arguments and thinking), not only to reasoning.
Source: platform.claude.comSources1
2.Tuning effort against a latency target
The token budget from older designs no longer exists. On Claude Sonnet 5.5, Opus 5.5, Haiku 5.5 and any model numbered 4.7 or higher, thinking: {type: "enabled"} returns a 400 error. To migrate, remove budget_tokens, use adaptive thinking, and control depth with effort. max_tokens is a different kind of control. It is a hard limit on all output, thinking plus reply text. Set it low and long answers get truncated, but the model doesn't decide any more carefully when to think. At high effort and above, it needs to be large.
For latency-sensitive work on Sonnet 5.5, start low. For chat, begin at medium or low. For agentic coding and multistep tool use, begin at medium on well-specified tasks and move to high for harder or longer ones. Use xhigh or max only where your evals show a quality gain. Sonnet 5.5 also has a way to answer without thinking first: send thinking: {"type": "between_tools"}, not "disabled". This works at low, medium and high, and returns a 400 at xhigh or max. It has a catch. With between_tools, changing effort with a per-message output_config returns a 400 error. If you need effort to vary turn by turn, stay on adaptive thinking.
The system prompt and effort control different things. On Claude Opus 5, effort sets how much the model thinks, not how long its visible reply is, so you get shorter replies by asking for them in the prompt. Thinking frequency works the other way round. Effort is the lever calibrated for it, and a stronger instruction is not.
Lowering effort has an accuracy cost, and you should measure it before shipping. Sonnet 5.5's levels are calibrated differently from Claude Sonnet 5's, so run a fresh effort sweep on your own evals rather than reusing old settings. On a representative traffic sample, compare these before and after the change:
- how often turns produce thinking
- output tokens per turn
- tail latency
- answer quality
The quality check matters most for long agent prompts. Haiku 5.5 at low effort tends to skip steps there.
Checkpoint 2 of 9· Check yourself
A latency-sensitive support agent on Claude Sonnet 5.5 sends thinking: {"type": "between_tools"} at medium effort. The team now wants harder turns to go to high effort, using a per-message output_config. What happens, and what should they do?
On Sonnet 5.5, between_tools fixes effort for the whole conversation, so a per-message effort at a different level is rejected with a 400. Changing effort turn by turn needs adaptive thinking. On this model you send between_tools, not "disabled", to skip up-front thinking.
“With between_tools, effort can’t change mid-conversation: a per-message output_config.effort at a different level returns a 400 error.”Source: platform.claude.com
Checkpoint 3 of 9· Exam question
A customer-support agent on Claude Sonnet 5.5 through the Messages API must meet a 4-second p95 latency target. Traces show the model emits a thinking block on nearly every turn, including turns that only relay a tool result. A system prompt line telling it to answer directly did not change this behavior. Choose two.(Select 2)
Correct answers: A, D — Lower output_config.effort to medium or low, because effort is the calibrated lever for how often and how deeply Claude thinks on this model.; Compare thinking-block frequency, output tokens, p95 latency and answer quality on a representative traffic sample before and after the effort change.
- A. This is correct. Effort is the primary, calibrated control for thinking, and for Claude Sonnet 5.5 the docs say prompt instructions to think less do not reliably reduce thinking, so lowering effort is the right lever.
- B. This is incorrect because you do not set a thinking token budget with adaptive thinking. The soft control is effort, and a manual budget belongs to legacy configurations.
- C. This is incorrect because
max_tokensis a hard cap on thinking and reply text combined. Lowering it risks truncated answers withstop_reason: max_tokensinstead of reducing how often the model thinks. - D. This is correct. Steering changes behavior and can reduce quality on tasks that benefit from reasoning, so you verify the latency and accuracy effect on representative traffic before shipping it.
- E. This is incorrect because the prompt already failed to change behavior, and for Claude Sonnet 5.5 an instruction to think less does not reliably reduce thinking. Stronger wording does not fix that.
3.Clearing tool results and old thinking
Context editing removes specific content that Claude has already used, and leaves the rest of the conversation intact. It offers two server-side strategies. clear_tool_uses_20250919 targets agents with heavy tool use, where a file read or a search result is dead weight once Claude has processed it. clear_thinking_20251015 removes thinking blocks from earlier assistant turns.
Tool-result clearing starts once input grows past a trigger. It removes the oldest results first, and each cleared result is replaced with placeholder text that tells Claude something was there. By default, Claude's original tool calls stay visible. Setting clear_tool_inputs to true clears the call parameters as well. Clearing happens on the server before the prompt reaches Claude. Your application keeps sending the full, unedited history and never has to sync its copy with the edited one.
| Option | Default | Effect |
|---|---|---|
| trigger | 100,000 input tokens | Clearing starts when the prompt passes this threshold (input_tokens or tool_uses) |
| keep | 3 tool uses | Number of the most recent tool use/result pairs that survive clearing |
| clear_at_least | None | Minimum tokens to clear per activation; if the API can't reach it, nothing is cleared |
| exclude_tools | None | Tools whose uses and results are never cleared |
| clear_tool_inputs | false | Also clear the tool call parameters, not just the results |
Thinking-block clearing is configured with keep, which counts how many recent assistant turns hold on to their thinking. If you include the strategy without keep, you get a value of 1 on every model, including models whose own default keeps all thinking. The choice is a trade-off. Keeping thinking preserves the prompt cache. Clearing it frees space in the context window, and the cache is invalidated at the point where clearing happens. Tool-result clearing also invalidates cached prefixes, so clear_at_least exists to make sure each clearing frees enough tokens to justify a new cache write.
A placeholder saying the result was removed, not the file contents. Unless the file was excluded through exclude_tools or Claude saved the number somewhere else first, the agent has to read the file again.
Checkpoint 4 of 9· Check yourself
Your team turns on clear_tool_uses_20250919 for a long-running coding agent. A developer proposes changing the client so that, after each response, it keeps only the cleared version of the conversation. What should the team do with the client's history?
Context editing runs on the server before the prompt reaches Claude. The client keeps managing its full, unmodified history and never needs to sync it with the edited version.
“Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version.”Source: platform.claude.com
Sources3
4.Compaction for one long conversation
Compaction replaces whole stretches of older turns with a summary. Clearing removes individual items, but compaction summarizes the conversation itself. Claude writes the summary on the server, so you don't write any summarization code. It keeps a long task inside the context window and keeps the active context small, which matters because response quality drops as a conversation grows. Server-side compaction comes in two modes, and they differ in who decides when it runs and whether the agent has to wait.
| Question | On demand | At a token threshold |
|---|---|---|
| Who decides when | You, by sending a request | The API, when input tokens reach your trigger |
| Code you write | A loop that requests the summary and swaps it in | One parameter on ordinary requests |
| Runs in the background | Yes | No: it runs inside the request that reaches the threshold |
| Recent turns kept word for word | Yes | Yes, by pausing after compaction and reinserting them |
| Kept turns keep their thinking (preserved-thinking models) | Yes, under conditions | No |
Background compaction keeps work moving. You send the compaction request with the history as it stands and note how many messages it covered. The conversation continues on the full history while the request runs. When the block comes back, you drop exactly the messages it summarized from the front of the history and put the block in their place. Every turn added in the meantime stays after it. Use on-demand compaction wherever it is available. Choose it over threshold compaction when operators can't let the agent stall.
A summary that loses facts is fixed through the prompt that writes it. The default prompt covers the task, current state, discoveries, next steps and preferences. It won't necessarily keep the specific identifiers a later turn depends on, such as ticket numbers, account IDs or open decisions. Writing your own summarization prompt that names those as required content replaces the default prompt. Settings applied after the summary can't bring them back. Raising effort doesn't help, because the facts are no longer in context to reason about. Keeping old thinking blocks doesn't help either, because the summarized turns are gone.
Some workloads are a poor fit for compaction. These include tasks that need precise recall of early conversation details, tasks that must track exact state across many variables, and workflows that use server-side tools heavily. The last case applies to the client-side SDK variant, compaction_control in the TypeScript and Ruby tool_runner. That variant adds up cache-read tokens from a server tool's internal calls and can trigger compaction too early. Server-side compaction is generally preferred.
Checkpoint 5 of 9· Check yourself
After server-side compaction, a support agent on a long ticket-handling session keeps losing the account IDs and ticket numbers that later turns need. Which change fixes this at the source?
A missing fact has to be fixed in the prompt that writes the summary. A custom summarization prompt replaces the default one and can require these identifiers. Higher effort cannot reason about facts that are no longer in context, and keeping old thinking does not help because the summarized turns are gone.
“Write your own summarization prompt: when the default summary drops something a later turn needs. Your prompt replaces the default one.”Source: platform.claude.com
Checkpoint 6 of 9· Exam question
An autonomous operations agent on Claude Sonnet 5.5 through the Messages API runs for many hours in one conversation. Operators cannot let work stall while a summary is written, and after the first compaction the agent forgot ticket IDs and open decisions. Choose two changes that fit these constraints.(Select 2)
Correct answers: C, E — Use on-demand compaction in the background, sending the summary request while work continues and swapping the returned block in when it arrives.; Write your own summarization prompt that names ticket IDs and open decisions as required content, replacing the default summary instructions.
- A. This is incorrect because threshold compaction runs inside the request that reaches the trigger, so that request waits for the summary. It does not run in the background.
- B. This is incorrect because effort changes how deeply Claude thinks, not what the summary contains. Details dropped during summarization are no longer visible to the model at any effort level.
- C. This is correct. On-demand compaction in the background lets the conversation keep working while the summary request runs, and you swap the block in when it returns, which meets the no-stall requirement.
- D. This is incorrect because thinking block clearing is a separate context editing strategy. Retaining thinking does not make the summary hold identifiers, and compaction replaces the history it covers.
- E. This is correct. A custom summarization prompt replaces the default and can require specific identifiers and open decisions, which addresses the loss of details after the first compaction.
5.Memory for work that spans sessions
Clearing and compaction both work inside a single conversation. A session that starts with an empty message history gets nothing from either one. The memory tool covers that gap. Claude creates, reads, updates and deletes files under /memories, and those files persist between sessions. The tool runs on the client. Claude requests file operations, and your handler carries them out against storage you control, such as a per-user directory or keys in a database. A handler must reject any path outside /memories.
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[{"role": "user", "content": "Hello"}],
tools=[{"type": "memory_20250818", "name": "memory"}],
betas=["context-management-2025-06-27"],
context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)For a multi-day project, set up the memory files deliberately rather than writing them ad hoc. Without them, an agent can spend each morning re-exploring the repository and reopening design decisions it already made. The recovery pattern has three parts:
- An initializer session creates a progress log, a feature checklist, and a pointer to any startup script before substantive work starts.
- Every later session opens by reading those files. That restores state without re-exploring the code base or retracing decisions.
- Before a session ends, it updates the progress log with what was finished and what remains.
Work on one feature at a time, and mark it done only after end-to-end verification. That keeps the log trustworthy.
Memory works alongside the other strategies, not instead of them. Combined with tool-result clearing, Claude gets an automatic warning as context nears the clearing threshold, so it can write important results to memory before they are removed. Combined with compaction, compaction keeps the working context small, and memory holds whatever must survive summarization.
Checkpoint 7 of 9· Put it in order
A coding agent works on one project over several days, and each day starts a new session with an empty message history. Put the steps of the memory-based recovery pattern in the order a well-run project follows them.
- 1.The session works on one feature and marks it done only after end-to-end verification
- 2.An initializer session creates a progress log, a feature checklist and a pointer to the startup script before substantive work begins
- 3.A later session opens by reading those memory files to restore the project state
- 4.Before the session ends, it updates the progress log with what was finished and what remains
The memory files must exist before work starts. Each new session restores state by reading them, because compaction and clearing carry nothing into an empty history. Each session records its progress before it ends, so the next one starts from an accurate point.
“Each new session opens by reading those memory files. This restores the project state without re-exploring the code base”Source: platform.claude.com
Checkpoint 8 of 9· Exam question
A Messages API agent migrates a legacy codebase over roughly two weeks of daily sessions. Every session starts with an empty message history, and engineers report that each morning the agent re-explores the repository and repeats earlier design decisions. Accuracy matters more than first-turn latency. Which context lifecycle strategy addresses the problem?
Correct answer: D — Enable the memory tool, seed a progress log and feature checklist in an initializer session, and have every session read then update those files.
- A. This is incorrect because compaction summarizes older turns inside one ongoing conversation. A new session with empty history has no conversation to compact, so nothing carries over.
- B. This is incorrect because context editing only changes what Claude sees within the request's own history. Tool results from a prior session are not in the new session's messages to begin with.
- C. This is incorrect because a larger window enlarges capacity within a single conversation but does not persist anything between sessions that start empty.
- D. This is correct. The memory tool is client-side file storage that survives across sessions, and the documented multisession pattern uses an initializer session plus a progress log and feature checklist that each session reads and updates.
6.Matching the strategy to the workload
Start from the workload's constraints. Session length decides whether you need anything beyond a single conversation. The latency requirement decides whether the agent can wait while a summary is written. The accuracy requirement decides how much loss you can accept from summarizing or clearing. Effort is set alongside all of this, using the measured sweep described earlier, because a long agent at max effort fills its context faster than one at medium.
| Workload constraint | Strategy | Why |
|---|---|---|
| One long conversation that can pause briefly | On-demand compaction, or compaction at a token threshold for the least code | Summarizes older turns so the task fits in the window |
| One long conversation that must never stall | On-demand compaction in the background | Work continues on the full history until the summary block is swapped in |
| Heavy tool output that is disposable once used | clear_tool_uses_20250919 plus the memory tool | Removes stale results; the pre-clearing warning lets Claude save what matters |
| Thinking blocks crowding the window | clear_thinking_20251015 with a chosen keep | Trades cache hits against window space |
| Work spanning sessions that start empty | Memory tool with initializer, read and update steps | Only memory files persist between sessions |
| Precise recall of early details or exact state across many variables | Avoid relying on compaction; keep facts in memory files | Summaries are lossy for this kind of state |
Two common combinations are worth knowing. A research agent that runs for hours in one conversation, with a strict accuracy bar on cited identifiers, should use background on-demand compaction with a custom summary prompt, and also write identifiers to memory. A coding agent that works in daily sessions needs the memory protocol first. Within each session it can add tool-result clearing, with exclude_tools covering any tool whose output must stay visible. To check what clearing will save before you commit to it, the token-counting endpoint accepts context_management and returns both the count after clearing and the original count.
Checkpoint 9 of 9· Match them up
Match each workload constraint to the context lifecycle strategy that fits it.
Tap a term, then the definition that fits it.
Threshold compaction runs inside the request that reaches the trigger, so only background on-demand compaction avoids a stall. Clearing removes stale tool results or old thinking within one conversation, and only memory files persist into a session that starts empty.
“Compaction in the background: when the conversation can’t pause for the summary.”Source: platform.claude.com
Sources3
Practise it for real
Use the token-counting endpoint to measure what tool-result clearing would save on a real agent transcript before you enable it.
1.Take a long agent transcript with many tool results and call client.beta.messages.count_tokens with betas=["context-management-2025-06-27"] and a clear_tool_uses_20250919 edit with trigger 30000 input tokens and keep 5 tool uses.
Why: The counting endpoint applies context management, so you can see the effect without running the agent.
You should see: A response with input_tokens and context_management.original_input_tokens.
2.Subtract input_tokens from original_input_tokens.
Why: The difference is the number of tokens clearing would remove on this request.
You should see: A positive saving when the transcript exceeds the trigger, and zero when it doesn't.
3.Add clear_at_least with a value larger than the saving you measured and count again.
Why: clear_at_least stops clearing when the saving is too small to justify invalidating the prompt cache.
You should see: input_tokens equals original_input_tokens, because the strategy wasn't applied.
Stuck? Get a nudge
If the saving is small, raise the trigger or lower keep before accepting the cache cost.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Because effort applies to every output token, it works with or without thinking. Lower effort also means fewer and terser tool calls.”
↩︎ Effort controls how much Claude spends per turn“Claude Opus 5.5 and Claude Haiku 5.5 default to medium.”
↩︎ Effort controls how much Claude spends per turn“Requests that set thinking: {"type": "disabled"} return a 400 error at every effort level.”
↩︎ Effort controls how much Claude spends per turn“Long-running agentic and coding tasks (over 30 minutes) with token budgets in the millions”
↩︎ Effort controls how much Claude spends per turn“For chat and other latency-sensitive work, start with medium or low.”
↩︎ Tuning effort against a latency target“To have the model respond without thinking first, send thinking: {"type": "between_tools"}, not "disabled".”
↩︎ Tuning effort against a latency target“Run a fresh effort sweep on your evals rather than carrying over the setting you used on Claude Sonnet 5.”
↩︎ Tuning effort against a latency target“Effort controls thinking volume, not visible response length”
↩︎ Tuning effort against a latency target“In long agent prompts, the model is more likely to skip a search, stop early, or skip a check at low.”
↩︎ Tuning effort against a latency target“With between_tools, effort can’t change mid-conversation: a per-message output_config.effort at a different level returns a 400 error.”
↩︎ Checkpoint - 2.
“remove budget_tokens, set thinking: {type: "adaptive"}, and control reasoning depth with output_config: {effort: ...} instead of a token budget.”
↩︎ Tuning effort against a latency target“remove budget_tokens, set thinking: {type: "adaptive"}, and control reasoning depth with output_config: {effort: ...} instead of a token budget.”
↩︎ Exam trap 1 - 3.
“The API replaces each cleared result with placeholder text indicating to Claude that it was removed.”
↩︎ Clearing tool results and old thinking“Context editing is applied server-side before the prompt reaches Claude.”
↩︎ Clearing tool results and old thinking“Invalidates cached prompt prefixes when content is cleared.”
↩︎ Clearing tool results and old thinking“Avoid compaction when using server-side tools extensively.”
↩︎ Compaction for one long conversation“Claude receives an automatic warning to preserve important information.”
↩︎ Memory for work that spans sessions“Tasks requiring precise recall of early conversation details”
↩︎ Matching the strategy to the workload“The token counting endpoint supports context management, allowing you to preview how many tokens your prompt will use after context editing is applied.”
↩︎ Matching the strategy to the workload“context is a finite resource with diminishing returns, and irrelevant content degrades model focus.”
↩︎ Key concept“Context editing is applied server-side before the prompt reaches Claude.”
↩︎ Exam trap 4“Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version.”
↩︎ Checkpoint - 4.
“Compaction replaces the older turns of a conversation with a summary that Claude writes on the server”
↩︎ Compaction for one long conversation“Write your own summarization prompt: when the default summary drops something a later turn needs. Your prompt replaces the default one.”
↩︎ Compaction for one long conversation“No: it runs inside the request that reaches the threshold”
↩︎ Exam trap 2“Compaction in the background: when the conversation can’t pause for the summary.”
↩︎ Checkpoint - 5.
“the compaction request runs while the conversation continues on its full history, and the swap waits until the block arrives.”
↩︎ Compaction for one long conversation - 6.
“Claude can create, read, update, and delete files that persist between sessions”
↩︎ Memory for work that spans sessions“The memory tool operates client-side: Claude requests file operations, and your application runs them.”
↩︎ Memory for work that spans sessions“compaction keeps the active context small without client-side bookkeeping, and memory preserves the information that must survive summarization.”
↩︎ Memory for work that spans sessions“Each new session opens by reading those memory files.”
↩︎ Exam trap 3“Each new session opens by reading those memory files. This restores the project state without re-exploring the code base”
↩︎ Checkpoint