Context Strategies & Defaults

Context strategies decide how an agent compacts history — truncate, prune, or summarise — when the conversation nears the model’s limit.

from praisonaiagents import Agent

agent = Agent(
    name="strategy-agent",
    instructions="Apply the right context strategy when history grows.",
)
agent.start("Continue this long task without losing important details.")

Context management is opt-in via the context= parameter. When disabled (default), there is zero performance overhead.

The user picks a compaction strategy; the agent applies truncation, chunking, or summarisation when context nears the limit.

Quick Start

Enable with defaults

from praisonaiagents import Agent

agent = Agent(
    instructions="You are helpful.",
    context=True,
)

Fine-tune strategy and threshold

from praisonaiagents import Agent, ManagerConfig

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

To enable in CLI:

praisonai chat --context  # Enable with defaults

Auto-Agents Mode (`Agents`)

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

To enable:

from praisonaiagents import AgentTeam

agents = AgentTeam(
    agents=[...],
    context=True,  # Enable for all agents
)

Optimization Strategies

Strategy Overview

Strategy	Description	Pros	Cons
`truncate`	Remove oldest messages first	Fast, simple; keeps tool pairs intact	Loses early context
`sliding_window`	Keep N most recent messages	Preserves recent; keeps tool pairs intact	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
`conversation`	Structured summaries with topic/goal tracking	Preserves narrative	Requires analysis
`smart`	Combine strategies intelligently	Best balance	More complex

Tool-call/tool-result pairs stay intact. Every strategy — including the default truncate — snaps its compaction boundary so an assistant tool_calls message and its matching tool result are never separated. Long-running sessions on OpenAI, Anthropic, and Azure OpenAI keep working after compaction; you do not need a workaround for the messages with role 'tool' must be a response to a preceding message with 'tool_calls' 400.

When to Use Each

truncate: Simple chatbots, Q&A agents
sliding_window: Long conversations where recent context matters most
prune_tools: Tool-heavy agents with large outputs
summarize: When historical context is critical
conversation: Multi-hour planning sessions, iterative development — automatically falls back to smart when compaction ratio isn’t meaningful, making it safe as a default for long-running agents
smart (recommended): Production use, balances all concerns

Tool-call safety

Every strategy keeps assistant tool_calls messages and their matching tool results on the same side of the compaction boundary. If the raw token/message cut lands between a pair, the boundary is snapped outward so the pair is preserved together. For truncate, the token-budget loop additionally drops a leading assistant tool_calls message together with all of its tool results in a single step. No configuration required — this behaviour is on by default for every strategy.

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

Compaction never emits an orphaned tool message. The recent-window boundary and any per-message drop pass keep the assistant tool_calls message and its matching tool result together — so strict providers (OpenAI, Anthropic, Azure OpenAI) never receive a partial pair.

# 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 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 AgentTeam

agents = AgentTeam(
    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
`conversation_compaction`	bool	`False`	Enable intelligent conversation compaction
`conversation_analyzer_strategy`	str	`"hybrid"`	Strategy: hybrid, rule_based, llm_only
`conversation_min_compaction_ratio`	float	`0.3`	Minimum compression ratio for conversation compaction
`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

How It Works

Best Practices

Pick strategy by session length

Short chats can use truncate; long support threads benefit from smart or LLM summarisation.

Isolate multi-agent context

Use policy="isolated" unless agents explicitly share a workspace.

Leave redaction on

redact_sensitive=True protects API keys in tool results from appearing in logs.

Revisit strategy after model changes

A larger context window may let you switch to lighter strategies and save latency.

Tool-using bots stay valid across compaction

When your agent calls tools inside a long conversation, compaction never separates an assistant tool_calls message from its tool result. This holds for every strategy — truncate, sliding_window, prune_tools, summarize, conversation, and smart. Long-lived Telegram/Slack/gateway bots on strict providers keep working across weeks of history without provider 400s.

Context Budgeter

Token budget allocation

Context Monitor

Real-time context snapshots

Context Optimizer

Reduce context when over budget

Fast Context

High-performance context handling

​Quick Start

​Default Behavior

​Interactive Mode (praisonai chat)

​Auto-Agents Mode (Agents)

​Optimization Strategies

​Strategy Overview

​When to Use Each

​Tool-call safety

​Overflow Handling

​Threshold Playbook

​Automatic Handling

​Budgeting

​Token Allocation

​Custom Budgets

​Monitoring

​Enable Context Monitoring

​Snapshot Output Example

​Percentage Display

​Multi-Agent Policies

​Isolated (Default)

​Shared

​Redaction & Security

​Configuration Reference

​ManagerConfig Options

​How It Works

​Best Practices

​Related

Context Budgeter

Context Monitor

Context Optimizer

Fast Context

Quick Start

Default Behavior

Interactive Mode (`praisonai chat`)

Auto-Agents Mode (`Agents`)

Optimization Strategies

Strategy Overview

When to Use Each

Tool-call safety

Overflow Handling

Threshold Playbook

Automatic Handling

Budgeting

Token Allocation

Custom Budgets

Monitoring

Enable Context Monitoring

Snapshot Output Example

Percentage Display

Multi-Agent Policies

Isolated (Default)

Shared

Redaction & Security

Configuration Reference

ManagerConfig Options

How It Works

Best Practices

Related