Claude Automatic Context Compaction for Long-Running AI Agents

 

Claude Automatic Context Compaction: Keep Long-Running AI Agents Working Beyond Context Limits

Long-running AI agents can perform impressive multi-step tasks, but they face a practical limitation: their conversation history keeps growing.

Every instruction, model response, tool request and tool result occupies space in the context window. In a tool-heavy workflow, this information can accumulate quickly. Eventually, the agent may become slower, consume significantly more tokens or approach its context limit.

Anthropic’s Claude Cookbook presents a solution called automatic context compaction.

Instead of carrying the complete conversation history through every step, Claude can summarize the important information, remove unnecessary historical details and continue the task using a smaller, focused context.

What Is Automatic Context Compaction?

Automatic context compaction is a context-management technique for long-running Claude agent workflows.

It monitors the number of tokens being used in the conversation. When usage passes a configured threshold, the system asks Claude to create a concise summary of the work completed so far.

The workflow then:

1. Monitors conversation token usage.

2. Detects when the configured threshold has been exceeded.

3. Generates a summary of essential information.

4. Clears the lengthy conversation history.

5. Continues the task using the summary as the new working context.

The agent does not restart the task from the beginning. It retains the decisions, progress, unresolved steps and other information required to continue.

Why Context Growth Becomes a Problem

Consider an AI customer-service agent that processes support tickets.

For every ticket, the agent may need to:

• Retrieve the ticket.

• Classify the issue.

• Search a knowledge base.

• Set its priority.

• Route it to the appropriate team.

• Draft a customer response.

• Mark the ticket as complete.

When the agent processes many tickets, every tool result remains in its conversation history. While working on the fifth ticket, it may still carry complete knowledge-base searches, classifications and draft responses from the previous four tickets.

This produces several problems.

1. Token usage grows continuously

The complete conversation may be sent back to the model during every new turn. As the history grows, each request becomes larger.

2. Old information pollutes the active context

Details from completed tasks can distract the agent from the current task. The agent usually needs only a short completion record, not every intermediate tool result.

3. Costs can increase

Larger model inputs generally mean greater token consumption. Repeatedly sending old information can make an agentic workflow unnecessarily expensive.

4. Responses may become slower

Processing an increasingly large context requires more work than processing a compact, focused history.

5. The agent may reach its context limit

A sufficiently long workflow can eventually exceed the model’s available context window and interrupt the task.

How Claude’s Compaction Process Works

In the Claude Agent Python SDK workflow shown in the cookbook, automatic compaction is enabled through the compaction_control setting.

A simplified configuration looks like this:

runner = client.beta.messages.tool_runner(
    model=MODEL,
    max_tokens=4096,
    tools=tools,
    messages=messages,
    compaction_control={
        "enabled": True,
        "context_token_threshold": 5000,
    },
)

The most important options include:

• enabled: Turns automatic compaction on or off.

• context_token_threshold: Determines the token level that triggers compaction.

• model: Optionally specifies a different model to generate the summary.

• summary_prompt: Allows developers to customize what the summary should preserve.

The default threshold described in the cookbook is 100,000 tokens, although the demonstration uses a lower threshold so the compaction process can be observed during a smaller workflow.

What Should the Summary Preserve?

A useful compaction summary should not simply shorten the conversation. It should preserve the information the agent needs to finish the task correctly.

For a customer-support workflow, the summary may retain:

• Tickets already completed.

• Issue categories.

• Assigned priorities.

• Routing decisions.

• Current ticket status.

• Steps completed for the active ticket.

• Remaining steps.

• Important knowledge-base findings.

• The next action the agent should perform.

At the same time, it can discard verbose intermediate results that are no longer needed, such as full knowledge-base articles or complete drafts for already resolved tickets.

Why Custom Summary Prompts Matter

Different agents need different types of memory.

A coding agent may need to remember:

• Files that were changed.

• Tests that passed or failed.

• Outstanding bugs.

• Architecture decisions.

• Commands already executed.

A research agent may need to preserve:

• Sources reviewed.

• Findings supported by each source.

• Conflicting evidence.

• Unanswered questions.

• The current research outline.

A customer-service agent may need ticket IDs, classifications, priorities and resolution status.

A customized summary prompt helps ensure that compaction retains task-critical information instead of creating a generic summary.

Good Use Cases for Context Compaction

Automatic context compaction can be especially useful for:

• Customer-support ticket queues.

• Multi-step research agents.

• Coding and debugging agents.

• Document-processing pipelines.

• Data-analysis workflows.

• Browser and computer-use agents.

• Agents performing repeated tool calls.

• Long-running operational assistants.

It is most valuable when the task contains many completed intermediate steps that no longer need to remain in full detail.

Requirements Mentioned in the Cookbook

The SDK-based example lists the following prerequisites:

• Python 3.11 or later.

• An Anthropic API key.

• Anthropic SDK version 0.74.1 or later.

• Basic knowledge of tool calling and agentic workflows.

The guide also notes that developers using Claude Opus 4.6 should consider Anthropic’s server-side compaction, which handles context management without requiring the same SDK-level configuration.

Important Design Considerations

Compaction should be implemented carefully.

A poor summary could remove a decision, constraint or unresolved task that the agent still needs. For that reason, developers should test summaries and verify that they consistently retain:

• Original goals.

• User requirements.

• Completed work.

• Current progress.

• Important identifiers.

• Errors and unsuccessful attempts.

• Pending actions.

• Safety and operational constraints.

The threshold also matters. Triggering compaction too frequently may add unnecessary summarization steps, while triggering it too late may allow excessive context growth.

Final Thoughts

Long-running AI agents need more than intelligent tool use. They also need effective memory management.

Claude’s automatic context compaction offers a practical way to control conversation growth. By replacing lengthy histories with focused progress summaries, an agent can retain essential information while discarding details that no longer contribute to the task.

The result is a workflow that can remain more focused, token-efficient and capable of continuing through many iterations.

For developers building agents that process queues, conduct research, modify code or repeatedly call tools, context compaction is an important pattern to understand.

Read the original Claude Cookbook guide:
https://platform.claude.com/cookbook/tool-use-automatic-context-compaction