Implementing Automatic Context Compaction in Claude Tool Use: A Complete Guide

Claude's context-management beta automatically prunes conversation history by clearing older tool uses when token thresholds are exceeded, preserving recent interactions while preventing context window overflow.

The anthropics/claude-cookbooks repository demonstrates how to implement automatic context compaction in Claude tool use workflows using the native context-management API beta. This technique is essential when tools generate large intermediate outputs—such as file system operations or search results—that would otherwise consume the model's limited context window, allowing applications to maintain long-running sessions without manual history truncation.

How Context Compaction Works

The implementation relies on several coordinated components within the anthropics/claude-cookbooks codebase. According to the source code, the architecture combines a specialized memory tool, API request builders, and server-side edit engines to automate context window management.

Memory Tool Handler: Located in tool_use/memory_tool.py, this component validates file paths and executes file-system operations that generate the large responses requiring compaction.

Demo Helpers: The tool_use/memory_demo/demo_helpers.py file contains the run_conversation_loop function, which builds request payloads and automatically injects the required betas=["context-management-2025-06-27"] flag. This file also houses print_context_management_info, which parses the context_management field from API responses (lines 96-125).

Configuration Schema: The CONTEXT_MANAGEMENT dictionary in tool_use/memory_demo/code_review_demo.py (lines 40-49) declares the compaction rules, specifying triggers, retention policies, and minimum clearance requirements.

Research Corpus: Synthetic data in tool_use/context_engineering/research_corpus.py deliberately exceeds the 30,000-token threshold to demonstrate compaction behavior in practice, illustrating how "high-level" versus "obscure" information survives the process.

Configuring the Context Management Object

The CONTEXT_MANAGEMENT dictionary serves as the control center for automatic compaction. The configuration used in the canonical demo illustrates the standard structure:

CONTEXT_MANAGEMENT = {
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": 30000},
            "keep": {"type": "tool_uses", "value": 3},
            "clear_at_least": {"type": "input_tokens", "value": 5000},
        }
    ]
}

Edit Types and Triggers

The type field specifies which edit operation to apply. The demo uses clear_tool_uses_20250919, which removes older tool-use blocks from the conversation history. Other supported types include clear_thinking and clear_output, depending on the specific beta version.

The trigger object defines when compaction fires. In the demo configuration, {"type": "input_tokens", "value": 30000} activates the edit when response.usage.input_tokens exceeds 30,000. Alternative trigger metrics include output_tokens and turns.

Retention Policies

Two parameters control what survives compaction:

Keep: The keep directive preserves recent interaction blocks. Setting {"type": "tool_uses", "value": 3} ensures Claude retains the three most recent tool-use results while removing older ones.

Clear At Least: The clear_at_least field guarantees minimum token reduction. Setting {"type": "input_tokens", "value": 5000} ensures the compaction clears no fewer than 5,000 tokens, preventing trivial edits that would trigger repeatedly.

Practical Implementation Examples

Implementing automatic context compaction requires initializing the Anthropic client with the correct beta flag and constructing the context management configuration. The tool_use/memory_demo/demo_helpers.py file encapsulates this logic in helper functions that manage the API lifecycle.

Minimal Setup with Memory Tools

This example demonstrates a basic implementation that clears tool uses after 20,000 input tokens:

from anthropic import Anthropic
from memory_tool import MemoryToolHandler
from tool_use.memory_demo.demo_helpers import run_conversation_loop, print_context_management_info

# Initialise client and memory handler

client = Anthropic()
memory = MemoryToolHandler()

# Context-management configuration

CONTEXT_MANAGEMENT = {
    "edits": [
        {
            "type": "clear_tool_uses_demo",
            "trigger": {"type": "input_tokens", "value": 20000},
            "keep": {"type": "tool_uses", "value": 2},
            "clear_at_least": {"type": "input_tokens", "value": 3000},
        }
    ]
}

# Run conversation with automatic compaction

response = run_conversation_loop(
    client=client,
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Create three files with some text."}],
    memory_handler=memory,
    context_management=CONTEXT_MANAGEMENT,
    max_tokens=1024,
    verbose=True,
)

# Display compaction summary

print_context_management_info(response)

What to notice: The run_conversation_loop function automatically includes betas=["context-management-2025-06-27"] in the API request. After compaction, print_context_management_info outputs metrics such as "Cleared 1 tool use(s), saved 4,212 tokens".

Multi-Session Code Review Workflow

The code_review_demo.py script provides a production-ready example spanning multiple sessions. This implementation:

1. Populates memory with debugging patterns using the memory_20250818 tool
2. Accumulates tokens across turns until exceeding the 30,000-token threshold
3. Automatically triggers the clear_tool_uses_20250919 edit, retaining only the three most recent tool uses
4. Reports compaction statistics via the context_management response field

Programmatic Inspection of Applied Edits

To react to compaction events in application logic, inspect the response.context_management.applied_edits list:

if hasattr(response, "context_management") and response.context_management:
    for edit in response.context_management.get("applied_edits", []):
        edit_type = edit.get("type")
        cleared = edit.get("cleared_input_tokens", 0)
        print(f"Edit {edit_type} cleared {cleared} input tokens")

Key Source Files and Their Responsibilities

• tool_use/memory_tool.py: Implements the memory_20250818 tool handler, providing file CRUD operations and path validation that generate the large outputs necessitating compaction.

• tool_use/memory_demo/demo_helpers.py: Contains run_conversation_loop for building API requests with context_management parameters and print_context_management_info for parsing edit summaries from responses (lines 96-125).

• tool_use/memory_demo/code_review_demo.py: Demonstrates the CONTEXT_MANAGEMENT configuration with a 30,000-token trigger and three-tool retention policy (lines 40-49).

• tool_use/context_engineering/research_corpus.py: Provides synthetic data exceeding 150,000 tokens to test compaction behavior and demonstrate information loss patterns (lines 14-17, 26-33).

• tool_use/utils/customer_service_api.py: Generates large ticket payloads used in compaction demonstrations.

Summary

• Automatic context compaction prevents conversation history overflow by defining token thresholds that trigger automatic pruning of older tool uses.
• Configuration requires a CONTEXT_MANAGEMENT dictionary specifying edit types (clear_tool_uses_20250919), triggers (input_tokens > 30,000), and retention policies (keep 3 tool uses, clear_at_least 5,000 tokens).
• Beta activation is mandatory via betas=["context-management-2025-06-27"], handled internally in demo_helpers.py by run_conversation_loop.
• Monitoring compaction events is possible through the response.context_management field, which lists applied_edits and cleared token counts.
• Source files in the anthropics/claude-cookbooks repository provide complete working implementations from tool handlers to multi-session demos.

Frequently Asked Questions

What triggers automatic context compaction in Claude?

Automatic compaction fires when the metric defined in the trigger object exceeds its threshold. The standard configuration monitors input_tokens and activates when the count surpasses 30,000, though you can configure triggers based on output_tokens or conversation turns depending on your workflow requirements.

How does the keep parameter work in context management?

The keep parameter preserves a specified number of recent interaction blocks from deletion. When using {"type": "tool_uses", "value": 3}, Claude retains the three most recent tool-use results while removing older ones, ensuring the model maintains access to immediately relevant context even after compaction.

Why is the beta flag required for context compaction?

The betas=["context-management-2025-06-27"] flag activates the server-side edit engine that processes the CONTEXT_MANAGEMENT configuration. Without this flag, the API ignores the edit description and performs no automatic pruning, potentially allowing the conversation to exceed the model's context window limits.

Can I inspect what was removed during context compaction?

Yes. The API response includes a context_management field containing an applied_edits list. Each edit object specifies the type of edit performed and the cleared_input_tokens count. You can parse this programmatically using patterns from tool_use/memory_demo/demo_helpers.py or display it via print_context_management_info.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}