Context Strategies & Defaults

Complete guide to context management strategies, defaults, and customization

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

from praisonaiagents import Agent

# All four spellings enable the sliding_window strategy:
Agent(instructions="t", context="sliding_window")
Agent(instructions="t", context="sliding-window")
Agent(instructions="t", context="SLIDING_WINDOW")
Agent(instructions="t", context=" sliding_window ")

# The context_manager is actually built — previously the last three silently returned None:
assert Agent(instructions="t", context="sliding-window").context_manager is not None

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.")

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

Quick Start

1. Enable with defaults

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

2. 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)

To enable in CLI:

praisonai chat --context  # Enable with defaults

Auto-Agents Mode (Agents)

To enable:

from praisonaiagents import AgentTeam

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

Optimization Strategies

Strategy Overview

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
• non_destructive: Heavy tool outputs you must keep — tags old messages out of the effective window instead of deleting them
• 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

“Immediate truncation” at 100% now counts the system prompt and tool schemas in the overhead, not just history tokens. An agent whose system prompt or tool block grew large will trip emergency truncation earlier than before — this is intentional and keeps the request inside the model window.

Automatic Handling

When auto_compact=True, the system automatically:

1. Monitors token usage before each API call
2. Triggers optimization when threshold is reached
3. Applies the configured strategy
4. Logs the optimization event
5. If the configured strategy fails, falls back to emergency truncation targeting ~80% of the model window (result payload includes emergency_truncated: True)

Failure Fallback

If the configured strategy raises, _apply_context_management no longer returns the history unchanged. It:

1. Logs the failure at error level (was warning).
2. Recomputes the model limit via get_model_limit.
3. Adds the system prompt and tool-schema token cost as overhead.
4. If history + overhead > 95% of the window, calls emergency_truncate targeting max(1, int(model_limit * 0.8) - overhead).
5. Returns {"emergency_truncated": True} so observability sinks can see the fallback fired.

A misconfigured strategy therefore never sends an over-budget request — the hard limit stays in place.

from praisonaiagents import Agent, ManagerConfig

agent = Agent(
    instructions="You are a support assistant.",
    context=ManagerConfig(
        strategy="truncate",  # Any of the seven strategies is now reliable
        auto_compact=True,
        compact_threshold=0.8,
    ),
)

# When the configured strategy fails, the fallback still keeps the request
# inside the model window and marks the result.
result = agent.chat("Long conversation continues here...")
# result.metadata may include:
#   {"emergency_truncated": True}

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

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

How It Works

Best Practices

Related