Context Strategies & Defaults
This is the master reference for context management in PraisonAI Agents. It covers all strategies, default behaviors, and how to customize them.
Context management is opt-in via the context= parameter. When disabled (default), there is zero performance overhead.
Quick Start
from praisonaiagents import Agent
from praisonaiagents.context import ManagerConfig
# Simple: Enable with defaults
agent = Agent(
instructions="You are helpful.",
context=True, # Enable context management
)
# Custom: Fine-tune behavior
agent = Agent(
instructions="You are a code assistant.",
context=ManagerConfig(
auto_compact=True,
compact_threshold=0.8,
strategy="smart",
output_reserve=16384,
),
)
Default Behavior
Interactive Mode (praisonai chat)
| Setting | Default | Reason |
|---|
context= | False | Zero overhead for simple chats |
| When enabled: | | |
- auto_compact | True | Prevent overflow automatically |
- compact_threshold | 0.8 | Trigger at 80% usage |
- strategy | smart | Best balance of preservation |
- output_reserve | Model-specific | 8K-16K tokens |
praisonai chat --context # Enable with defaults
Auto-Agents Mode (PraisonAIAgents)
| Setting | Default | Reason |
|---|
context= | False | Zero overhead for simple tasks |
| When enabled: | | |
- auto_compact | True | Handle long multi-agent tasks |
- compact_threshold | 0.8 | Trigger at 80% usage |
- strategy | smart | Preserve important context |
from praisonaiagents import PraisonAIAgents
agents = PraisonAIAgents(
agents=[...],
context=True, # Enable for all agents
)
Optimization Strategies
Strategy Overview
| Strategy | Description | Pros | Cons |
|---|
truncate | Remove oldest messages first | Fast, simple | Loses early context |
sliding_window | Keep N most recent messages | Preserves recent | Loses early context |
prune_tools | Truncate old tool outputs | Keeps messages | May lose tool details |
summarize | Replace old messages with summary | Preserves meaning | Slower, uses API |
smart | Combine strategies intelligently | Best balance | More complex |
When to Use Each
truncate: Simple chatbots, Q&A agentssliding_window: Long conversations where recent context matters mostprune_tools: Tool-heavy agents with large outputssummarize: When historical context is criticalsmart (recommended): Production use, balances all concerns
Overflow Handling
Threshold Playbook
| Usage | Level | Action |
|---|
| 70% | INFO | Monitor usage, no action needed |
| 80% | NOTICE | Consider optimization soon |
| 90% | WARNING | Trigger auto-compact if enabled |
| 95% | CRITICAL | Aggressive optimization required |
| 100% | OVERFLOW | Immediate truncation to prevent API error |
Automatic Handling
When auto_compact=True, the system automatically:
- Monitors token usage before each API call
- Triggers optimization when threshold is reached
- Applies the configured strategy
- Logs the optimization event
# Example: Custom threshold
agent = Agent(
instructions="...",
context=ManagerConfig(
auto_compact=True,
compact_threshold=0.7, # Earlier trigger
strategy="smart",
),
)
Budgeting
Token Allocation
The context budget is divided into segments:
| Segment | Default | Description |
|---|
| System Prompt | 2,000 | Agent instructions |
| Rules | 500 | Behavioral rules |
| Skills | 500 | Skill definitions |
| Memory | 1,000 | Long-term memory |
| Tools Schema | 2,000 | Tool definitions |
| Tool Outputs | 20,000 | Tool call results |
| History | Remaining | Conversation history |
| Buffer | 1,000 | Safety margin |
Custom Budgets
from praisonaiagents.context import ContextBudgeter
budgeter = ContextBudgeter(
model="gpt-4o",
system_prompt_budget=3000,
tools_schema_budget=5000,
memory_budget=2000,
)
budget = budgeter.allocate()
print(f"Usable: {budget.usable:,} tokens")
Monitoring
Enable Context Monitoring
agent = Agent(
instructions="...",
context=ManagerConfig(
monitor_enabled=True,
monitor_path="./context_debug.txt",
monitor_format="human", # or "json"
),
)
Snapshot Output Example
================================================================================
PRAISONAI CONTEXT SNAPSHOT
================================================================================
Timestamp: 2026-01-08T12:00:00Z
Model: gpt-4o-mini
Model Limit: 128,000 tokens
Output Reserve: 16,384 tokens
Usable Budget: 111,616 tokens
--------------------------------------------------------------------------------
TOKEN LEDGER
--------------------------------------------------------------------------------
Segment | Tokens | Budget | Usage
--------------------------------------------------------------------------------
System Prompt | 150 | 2,000 | 7.5%
History | 5,230 | 84,616 | 6.2%
Tool Outputs | 1,200 | 20,000 | 6.0%
--------------------------------------------------------------------------------
TOTAL | 6,580 | 111,616 | 5.9%
Percentage Display
Context utilization is displayed with smart formatting:
- Values < 0.1%: Shows
<0.1%
- Values < 1%: Shows 2 decimal places (e.g.,
0.02%)
- Values >= 1%: Shows 1 decimal place (e.g.,
5.3%)
Multi-Agent Policies
Isolated (Default)
Each agent has its own context ledger:
from praisonaiagents.context import ManagerConfig
agent1 = Agent(
instructions="Researcher",
context=ManagerConfig(policy="isolated"),
)
agent2 = Agent(
instructions="Writer",
context=ManagerConfig(policy="isolated"),
)
Shared
Agents share a common context ledger:
from praisonaiagents import PraisonAIAgents
agents = PraisonAIAgents(
agents=[agent1, agent2],
context=ManagerConfig(policy="shared"),
)
Redaction & Security
Sensitive data is automatically redacted in snapshots:
- API keys (OpenAI, Anthropic, Google, AWS, etc.)
- Passwords and secrets
- Email addresses (optional)
- Custom patterns
agent = Agent(
instructions="...",
context=ManagerConfig(
monitor_enabled=True,
redact_sensitive=True,
),
)
Configuration Reference
ManagerConfig Options
| Option | Type | Default | Description |
|---|
auto_compact | bool | True | Auto-optimize on threshold |
compact_threshold | float | 0.8 | Trigger at this usage % |
strategy | str | "smart" | Optimization strategy |
output_reserve | int | Model-specific | Reserved for output |
monitor_enabled | bool | False | Enable snapshots |
monitor_path | str | None | Snapshot file path |
monitor_format | str | "human" | "human" or "json" |
redact_sensitive | bool | True | Redact secrets |
policy | str | "isolated" | Multi-agent policy |
See Also
