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

> Easily implement automatic context compaction in Claude tool use. This guide explains how Claude's context management beta prunes history to prevent overflow and preserve key interactions.

- Repository: [Anthropic/claude-cookbooks](https://github.com/anthropics/claude-cookbooks)
- Tags: how-to-guide
- Published: 2026-04-14

---

**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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/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:

```python
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`](https://github.com/anthropics/claude-cookbooks/blob/main/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:

```python
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`](https://github.com/anthropics/claude-cookbooks/blob/main/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:

```python
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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/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`](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_demo/demo_helpers.py) or display it via `print_context_management_info`.