This tutorial is inspired by Anthropic's flagship Agentic AI product - Claude Code, see ClaudeAPIDocs.
Automatically manage conversation context as it grows with context editing.
Context editing is the process of:
- Removing unnecessary information from an AI system’s memory
- Keeping only the most relevant data for decision-making
👉 It is a more controlled and selective approach than summarization.
📌 From the source:
Context editing allows selective clearing of content to maintain focus and efficiency :contentReference[oaicite:0]{index=0}
In business environments, AI systems often:
- Process large amounts of data
- Interact with multiple tools (databases, APIs)
- Run long workflows
- Too much information leads to:
- Slower performance
- Reduced accuracy
- Higher operational costs
👉 Context editing helps optimize what the system “remembers”
| Approach | Description | Use Case |
|---|---|---|
| Compaction | Summarizes past information | General long conversations |
| Context Editing | Removes specific pieces of data | Fine-grained control scenarios |
👉 Context editing = precision control
👉 Compaction = broad summarization
- Removes results from tools (e.g., search results, file data)
- Keeps only recent or relevant outputs
👉 Example:
- A system analyzing multiple reports:
- Old reports can be removed once processed
- Removes internal reasoning steps used by the AI
- Keeps only final outputs or recent reasoning
👉 Helps reduce:
- Memory usage
- Processing overhead
- Keep only:
- Recent actions
- Important decisions
- Remove:
- Repetitive or outdated information
- System monitors context size
- When threshold is reached:
- Identifies unnecessary content
- Removes selected elements
- Continues processing with a cleaner, focused context
- Removes:
- Old conversation details
- Keeps:
- Current issue
- Customer preferences
👉 Result: Faster and more relevant responses
- Removes:
- Raw data already analyzed
- Keeps:
- Key insights and results
- Removes:
- Completed task logs
- Keeps:
- Current workflow state
- ✔ Improved performance
- ✔ Better focus on relevant data
- ✔ Lower computational costs
- ✔ Scalable long-running systems
- ❗ Risk of removing important information
- ❗ Requires careful configuration
- ❗ May affect continuity if overused
Context editing can be combined with:
- Databases / storage systems
- Knowledge management systems
- Store important information externally
- Remove it from active memory
👉 This creates:
- Efficient systems
- Persistent knowledge storage
Effective systems don’t store everything—they store what matters.
An AI system helps analysts process large datasets.
-
Identify:
- What data should be removed after use
- What should be retained
-
Discuss:
- How this improves:
- System efficiency
- Decision quality
- How this improves:
- Context editing is about selective information removal
- It improves efficiency and accuracy
- It is critical for complex, tool-based business systems
- Works best when combined with external memory systems
For most use cases, server-side compaction is the primary strategy for managing context in long-running conversations. The strategies on this page are useful for specific scenarios where you need more fine-grained control over what content is cleared.
Context editing allows you to selectively clear specific content from conversation history as it grows. Beyond optimizing costs and staying within limits, this is about actively curating what Claude sees: context is a finite resource with diminishing returns, and irrelevant content degrades model focus. Context editing gives you fine-grained runtime control over that curation. For the broader principles behind context management, see Effective context engineering. This page covers:
- Tool result clearing - Best for agentic workflows with heavy tool use where old tool results are no longer needed
- Thinking block clearing - For managing thinking blocks when using extended thinking, with options to preserve recent thinking for context continuity
- Client-side SDK compaction - An SDK-based alternative for summary-based context management (server-side compaction is generally preferred)
| Approach | Where it runs | Strategies | How it works |
|---|---|---|---|
| Server-side | API | Tool result clearing (clear_tool_uses_20250919)Thinking block clearing ( clear_thinking_20251015) |
Applied before the prompt reaches Claude. Clears specific content from conversation history. Each strategy can be configured independently. |
| Client-side | SDK | Compaction | Available in Python, TypeScript, and Ruby SDKs when using tool_runner. Generates a summary and replaces full conversation history. See Client-side compaction below. |
Context editing is in beta with support for tool result clearing and thinking block clearing. To enable it, use the beta header context-management-2025-06-27 in your API requests.
Share feedback on this feature through the feedback form.
This feature is in beta and is not eligible for Zero Data Retention (ZDR). Beta features are excluded from ZDR.
The clear_tool_uses_20250919 strategy clears tool results when conversation context grows beyond your configured threshold. This is particularly useful for agentic workflows with heavy tool use. Older tool results (like file contents or search results) are no longer needed once Claude has processed them.
When activated, the API automatically clears the oldest tool results in chronological order. The API replaces each cleared result with placeholder text so Claude knows it was removed. By default, only tool results are cleared. You can optionally clear both tool results and tool calls (the tool use parameters) by setting clear_tool_inputs to true.
The clear_thinking_20251015 strategy manages thinking blocks in conversations when extended thinking is enabled. This strategy gives you control over thinking preservation: you can choose to keep more thinking blocks to maintain reasoning continuity, or clear them more aggressively to save context space.
Default behavior: When extended thinking is enabled without configuring the clear_thinking_20251015 strategy, the API automatically keeps only the thinking blocks from the last assistant turn (equivalent to keep: {type: "thinking_turns", value: 1}).
To maximize cache hits, preserve all thinking blocks by setting keep: "all".
An assistant conversation turn may include multiple content blocks (e.g. when using tools) and multiple thinking blocks (e.g. with interleaved thinking).
Context editing is applied server-side before the prompt reaches Claude. Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version. Continue managing your full conversation history locally as you normally would.
Context editing's interaction with prompt caching varies by strategy:
-
Tool result clearing: Invalidates cached prompt prefixes when content is cleared. To account for this, clear enough tokens to make the cache invalidation worthwhile. Use the
clear_at_leastparameter to ensure a minimum number of tokens is cleared each time. You'll incur cache write costs each time content is cleared, but subsequent requests can reuse the newly cached prefix. -
Thinking block clearing: When thinking blocks are kept in context (not cleared), the prompt cache is preserved, enabling cache hits and reducing input token costs. When thinking blocks are cleared, the cache is invalidated at the point where clearing occurs. Configure the
keepparameter based on whether you want to prioritize cache performance or context window availability.
Good use cases:
- Long-running agent tasks that process many files or data sources
- Research workflows that accumulate large amounts of information
- Multi-step tasks with clear, measurable progress
- Tasks that produce artifacts (files, reports) that persist outside the conversation
Less ideal use cases:
- Tasks requiring precise recall of early conversation details
- Workflows using server-side tools extensively
- Tasks that need to maintain exact state across many variables