> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Context Management
> How AgentUse manages conversation context efficiently
## Overview
AgentUse automatically manages conversation context to keep your agents running efficiently within token limits. This ensures long-running agents don't hit token limits while preserving important information.
## Automatic Compaction
When conversations approach token limits, AgentUse automatically:
1. Detects when context usage exceeds the threshold
2. Compacts older messages into a concise summary
3. Preserves recent messages for continuity
4. Continues the conversation seamlessly
Compaction happens transparently - your agent continues working without interruption.
## How It Works
### Token Tracking
AgentUse tracks token usage throughout the conversation and compacts when approaching limits. The system uses character-based estimation (approximately 4 characters per token) and updates with actual usage data from the AI models.
### Compaction Strategy
AgentUse uses a **summarization-based** approach:
* Older messages are summarized using the same model as the agent
* Recent messages are preserved intact for continuity
* The summary captures key decisions, tool results, and progress
* System prompts and tool definitions are always preserved
## Configuration
### Environment Variables
Control context management globally using environment variables:
```bash theme={"system"}
# Enable/disable context compaction (default: enabled)
CONTEXT_COMPACTION=true
# Set compaction threshold as percentage (default: 0.7 = 70%)
COMPACTION_THRESHOLD=0.8
# Number of recent messages to preserve (default: 3)
COMPACTION_KEEP_RECENT=5
# Compact at approval gates once active context reaches this size (default: 64000)
APPROVAL_COMPACTION_MIN_TOKENS=64000
# Compact between LLM steps after tool calls once active context reaches this size (default: 64000)
STEP_COMPACTION_MIN_TOKENS=64000
# Maximum agent steps before stopping (default: 1000)
MAX_STEPS=2000
```
## What Gets Preserved
### Always Preserved
* System prompts
* Recent messages (last 3 by default, configurable)
* Tool definitions remain available
### What Gets Compacted
* Older conversation history
* Previous tool calls and results
* Assistant responses from earlier in the conversation
The compaction creates a summary that preserves:
* Key decisions and outcomes
* Important tool results and errors
* Current state and progress
* Critical information needed for continuation
## Compaction Details
### Compaction Process
When compaction is triggered:
1. Older messages are separated from recent ones
2. A summarization request is sent to the same model
3. The summary is created with a specialized system prompt
4. Recent messages are kept intact for continuity
5. The conversation continues with the compacted context
### Compaction Prompt
The system uses this prompt for summarization:
```
You are a conversation summarizer. Summarize the following agent context concisely, preserving:
1. Key decisions and outcomes
2. Important tool results and errors
3. Current state and progress
4. Any critical information needed for continuation
Be concise but comprehensive.
```
## Monitoring
### Token Usage
AgentUse displays token usage at the end of each run:
```
Tokens used: 12,450
```
For agents with sub-agents:
```
Tokens used: 18,750 (main: 12,450, sub-agents: 6,300)
```
### Compaction Events
When compaction occurs, you'll see:
```
Context approaching limit (85% used). Compacting agent context...
Context compacted successfully. Continuing...
```
## Context Limits by Model
AgentUse automatically detects context limits for different models:
* **Anthropic models**: Retrieved from models.dev API
* **OpenAI models**: Retrieved from models.dev API
* **Unknown models**: Default to 32,000 tokens (conservative)
The system updates context limits dynamically based on the latest model information.
## Performance Considerations
Compaction requires an additional API call to summarize context, adding 1-3 seconds to processing time
Compaction itself uses tokens (up to 2000 for the summary), but saves significantly more in long conversations
Summaries preserve key information but some nuance may be lost. Recent messages remain fully intact
## Best Practices
### 1. Set Appropriate Thresholds
```bash theme={"system"}
# Conservative (compact early, better context preservation)
COMPACTION_THRESHOLD=0.6
# Aggressive (compact late, more context before compaction)
COMPACTION_THRESHOLD=0.9
# Balanced (recommended default)
COMPACTION_THRESHOLD=0.7
```
### 2. Adjust Recent Messages
```bash theme={"system"}
# Keep more recent messages (better continuity, more tokens used)
COMPACTION_KEEP_RECENT=5
# Keep fewer recent messages (more aggressive compaction)
COMPACTION_KEEP_RECENT=2
```
### 3. Tune Approval-Boundary Compaction
```bash theme={"system"}
# Compact earlier at human approval pauses to reduce repeated input spend
APPROVAL_COMPACTION_MIN_TOKENS=32000
# Disable approval-boundary compaction but keep model-limit compaction
APPROVAL_COMPACTION_MIN_TOKENS=0
```
Approval-boundary compaction is useful for long runs with human review gates.
It can compact before the model window is close to full because the goal is to
avoid resending a large active context after the session resumes.
### 4. Tune Step-Boundary Compaction
```bash theme={"system"}
# Compact less often during autonomous tool loops
STEP_COMPACTION_MIN_TOKENS=128000
# Disable split-turn step compaction but keep approval and model-limit compaction
STEP_COMPACTION_MIN_TOKENS=0
```
Step-boundary compaction runs after the agent has already made at least one
tool call. It preserves the initial prompt, then summarizes older context before
later model calls in long single-turn runs.
### 5. Disable if Not Needed
```bash theme={"system"}
# Disable for short conversations
CONTEXT_COMPACTION=false
```
### 6. Cap and Reduce Tool Output
Every tool result is re-sent to the model on each subsequent step, so a single large output (a big diff, a verbose log, a huge file read) is one of the biggest drivers of input-token usage, often before compaction ever triggers. The most effective fix is to not generate the bloat in the first place, for example `git diff --stat` instead of a full `git diff` of high-churn files.
As a safety net, AgentUse caps `bash` output (head + tail, 30KB default) and `read_file` output (2000 lines default). When session storage is available and `bash` output is truncated, AgentUse keeps the full stdout/stderr stream as a session-local tool output artifact and adds a reference to the preview. Runner-level tool results that are still oversized after a tool returns are reduced the same way. Tune these with the [Tool Output environment variables](/reference/environment-variables#tool-output):
```bash theme={"system"}
# Allow larger bash output before truncation
AGENTUSE_TOOL_MAX_OUTPUT_BYTES=61440
# Return more lines per read_file call
AGENTUSE_TOOL_MAX_LINES=5000
```
## Technical Details
### Token Estimation
* Uses character-based estimation: \~4 characters per token
* Updates with actual token usage from AI models
* Tracks both input and output tokens
### Model Integration
* Context limits are fetched from models.dev API
* Falls back to conservative 32,000 token limit for unknown models
* Caches model information for 24 hours
### Error Handling
* If compaction fails, creates a fallback summary
* Continues execution even if compaction encounters errors
* Logs compaction failures for debugging
## Troubleshooting
* Increase `COMPACTION_KEEP_RECENT` for more preserved messages
* Lower `COMPACTION_THRESHOLD` to compact earlier with more context
* The same model is used for summarization, so quality should be consistent
* Lower `COMPACTION_THRESHOLD` to compact earlier
* Reduce `COMPACTION_KEEP_RECENT` for more aggressive compaction
* Consider the model's actual context limit vs your usage
* Check that `CONTEXT_COMPACTION` is not set to 'false'
* Verify the model supports the context limits being used
* Check logs for compaction errors
## Example: Long-Running Agent
```yaml theme={"system"}
---
name: data-analyzer
model: anthropic:claude-sonnet-5
---
You analyze large datasets over extended periods.
Process data systematically and maintain detailed progress tracking.
```
```bash theme={"system"}
# Configure for long-running analysis
export MAX_STEPS=2000
export COMPACTION_THRESHOLD=0.8
export COMPACTION_KEEP_RECENT=5
# Run the agent
agentuse run data-analyzer.agentuse
```
The agent will automatically:
* Track token usage throughout the analysis
* Compact context when approaching 80% of the model's limit
* Preserve the last 5 messages for continuity
* Continue analysis without interruption
## Next Steps
Build efficient agents
Configuration options