from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
    context_window=8000,
)
agent.start("Summarise the last 10 messages without losing context.")

Context Management Overview

This page provides a comprehensive visual guide to how context management works in PraisonAI Agents. The user opens this overview to see how budgeting, compaction, and monitoring fit together before tuning an agent.

What Makes PraisonAI Context Management Best-in-Class

Smart Defaults

Auto-enables when agents have tools. Zero overhead when not needed.

Lazy Loading

No performance impact until actually used. 0ms creation overhead.

Session Deduplication

Cross-agent duplicate detection in multi-agent workflows.

LLM Summarization

Intelligent compression using agent’s own LLM for quality preservation.

Per-Tool Limits

Fine-grained control over individual tool output sizes.

6 Strategies

Truncate, Sliding Window, Prune Tools, Summarize, Smart, Non-Destructive.

Comprehensive Monitoring

Snapshots, analytics dashboard, and replay capabilities.

Zero Performance Impact: Context management uses lazy loading throughout. Setting context=True adds only 1 boolean assignment at creation time (0ms). The ContextManager is only instantiated when .context_manager is first accessed.

Uniform across entry points. Context management runs on every entry point — chat(), start(), start(stream=True), iter_stream(), and their async variants. There is no “streaming bypass”: if a ContextManager is configured, the outbound messages are optimized before the request is sent, regardless of whether the response is streamed. See Streaming → long histories.This statement is only fully true after PR #4753. Before #4753 the OpenAI-client streaming branch ran compaction (since #4729), but the custom-LLM branch — used by llm="openai/gpt-4o-mini", llm="ollama/…", and every routed provider — still bypassed it.PraisonAI 2026-09-03 (PR #4729): the OpenAI-client streaming branch now runs the same _apply_context_management step as the non-streaming path.PraisonAI 2026-09-03 (PR #4753): the custom-LLM streaming branch also compacts. The trigger is the routing flag _using_custom_llm, not the vendor — llm="openai/gpt-4o-mini", llm="ollama/…", and every routed provider take this branch. Together with #4729, long-running streamed chats no longer blow past the context window on any provider. Fixes #4714.

Feature Comparison

Feature	PraisonAI	LangChain	CrewAI	Agno
Smart Defaults	✅	❌	❌	❌
Lazy Loading (0ms overhead)	✅	❌	❌	❌
Session Deduplication	✅	❌	❌	⚠️
LLM Summarization	✅	⚠️	❌	❌
Per-Tool Limits	✅	❌	❌	❌
6 Compaction Strategies	✅	❌	❌	❌
Benefit Checking	✅	❌	❌	❌
Auto-Compaction	✅	❌	❌	❌
Snapshot Replay	✅	❌	❌	❌
Multi-Memory Aggregation	✅	❌	✅	❌

Architecture

Multi-Agent Context Flow

Terminology Reference

Core Concepts

Term	Definition	Default
Context Window	Maximum tokens an LLM can process in one request	Model-specific (128K for GPT-4o)
Token Budget	Allocated tokens for each context segment	Auto-calculated
Compact Threshold	Usage % that triggers optimization	80%
Output Reserve	Tokens reserved for LLM response	8000-16000

Optimization Strategies

Strategy	How It Works	Best For
Truncate	Removes oldest messages first	Simple chatbots
Sliding Window	Keeps N most recent messages	Long conversations
Prune Tools	Truncates old tool outputs	Tool-heavy agents
Summarize	Replaces old messages with summary	Critical context
Smart	Combines all strategies intelligently	Production use

Token Segments

Defaults Reference

ContextConfig Defaults

ContextConfig(
    auto_compact=True,           # Auto-optimize when threshold reached
    compact_threshold=0.8,       # Trigger at 80% usage
    strategy="smart",            # Use smart optimization
    output_reserve=8000,         # Reserve for LLM response
    history_ratio=0.6,           # 60% of usable for history
    tool_output_max=10000,       # Max tokens per tool output
    prune_after_tokens=40000,    # Start pruning after 40K
    keep_recent_turns=5,         # Keep last 5 turns intact
    tool_limits={},              # Per-tool output limits
)

Per-Tool Limits

Configure different limits for different tools:

context:
  auto_compact: true
  tool_limits:
    tavily_search: 2000      # Search results: 2000 chars
    tavily_extract: 5000     # Full page: 5000 chars
    code_executor: 10000     # Code output: 10000 chars

Overflow Handling

Level	Usage	Action
Normal	< 70%	No action
Warning	70-80%	Monitor
Critical	80-90%	Auto-compact triggers
Emergency	90-95%	Aggressive optimization
Overflow	> 95%	Emergency truncation

Session Deduplication

Prevents duplicate content across agents in multi-agent workflows:

CLI Commands

Analytics Dashboard

# View analytics for recent sessions
praisonai replay dashboard

# Analyze specific session
praisonai replay dashboard <session_id>

# JSON output
praisonai replay dashboard --json

Session Statistics

# View session stats
praisonai replay context <session_id> --stats

Output:

TOKEN USAGE BY AGENT:
  deep_researcher      ██████████████████████████████    956,146 (75.5%)
  content_writer       ███                               113,023 (8.9%)

CONTEXT EFFICIENCY:
  ⚠️  Duplicates Found:  236
  ⚠️  Wasted Tokens:     135,279 (10.7%)

Smart Default Context

New in v1.0: Context management is now automatically enabled when your agent has tools:

from praisonaiagents import Agent

# Context auto-enabled because tools are present
agent = Agent(
    instructions="You are helpful",
    tools=[my_search_tool]  # context=True automatically
)

# No tools = no context overhead
simple_agent = Agent(
    instructions="You are helpful"
    # context=None (disabled, zero overhead)
)

# Explicitly disable even with tools
agent = Agent(
    instructions="You are helpful",
    tools=[my_search_tool],
    context=False  # Override smart default
)

Quick Start Examples

Enable or Customise

from praisonaiagents import Agent

agent = Agent(
    instructions="You are helpful",
    context=True  # Enable with defaults (or auto-enabled with tools)
)

from praisonaiagents import Agent, ManagerConfig

agent = Agent(
    instructions="You are helpful",
    context=ManagerConfig(
        auto_compact=True,
        compact_threshold=0.7,
        strategy="smart",
        llm_summarize=True,  # Enable LLM-powered summarization
        smart_tool_summarize=True,  # Summarize tool outputs before truncating (default)
        tool_summarize_limits={"tavily_search": 1000, "web_scraper": 5000},  # Per-tool thresholds
        tool_limits={"tavily_search": 2000}
    )
)

context:
  auto_compact: true
  compact_threshold: 0.7
  strategy: smart
  llm_summarize: true
  smart_tool_summarize: true
  tool_summarize_limits:
    tavily_search: 1000
    web_scraper: 5000
  tool_limits:
    tavily_search: 2000
    tavily_extract: 5000

Process Flow Diagrams

Sequential Process Flow

How context flows through agents in sequential execution:

Hierarchical Process Flow

How context flows in manager-worker hierarchies:

Workflow Process Flow

How context flows through workflow steps:

Optimization Strategy Diagrams

Truncate Strategy

Sliding Window Strategy

Prune Tools Strategy

Summarize Strategy

Smart Strategy (Combined)

Context Overflow Handling

What Happens When Context Exceeds Limits

Tool Output Overflow Handling

LLM Summarization

Enable intelligent summarization using the agent’s LLM:

from praisonaiagents import Agent, ContextConfig

agent = Agent(
    instructions="You are helpful",
    context=ContextConfig(
        auto_compact=True,
        llm_summarize=True,  # Enable LLM-powered summarization
        strategy="smart"
    )
)

When llm_summarize=True:

Old messages are summarized by the LLM instead of truncated
Key facts, decisions, and context are preserved
More intelligent compression than simple truncation

Best Practices

Start with ContextConfig defaults

Enable auto_compact and a sensible strategy before tuning low-level APIs.

Enable LLM summarisation for quality

llm_summarize=True keeps key facts when history must shrink.

Layer budget, ledger, and monitor

Budget allocation, usage tracking, and snapshots solve different problems — use all three when debugging.

Read strategy docs before custom hooks

Built-in strategies cover most cases; custom hooks add complexity only when required.

Context Strategies

Detailed strategy reference

Context Budgeter

Token budgeting

Context Optimizer

Optimisation details

Context Replay

Debugging and analysis

​Context Management Overview

​What Makes PraisonAI Context Management Best-in-Class

Smart Defaults

Lazy Loading

Session Deduplication

LLM Summarization

Per-Tool Limits

6 Strategies

Comprehensive Monitoring

​Feature Comparison

​Architecture

​Multi-Agent Context Flow

​Terminology Reference

​Core Concepts

​Optimization Strategies

​Token Segments

​Defaults Reference

​ContextConfig Defaults

​Per-Tool Limits

​Overflow Handling

​Session Deduplication

​CLI Commands

​Analytics Dashboard

​Session Statistics

​Smart Default Context

​Quick Start Examples

​Process Flow Diagrams

​Sequential Process Flow

​Hierarchical Process Flow

​Workflow Process Flow

​Optimization Strategy Diagrams

​Truncate Strategy

​Sliding Window Strategy

​Prune Tools Strategy

​Summarize Strategy

​Smart Strategy (Combined)

​Context Overflow Handling

​What Happens When Context Exceeds Limits

​Tool Output Overflow Handling

​LLM Summarization

​Best Practices

​Related Pages

Context Strategies

Context Budgeter

Context Optimizer

Context Replay

Context Management Overview

What Makes PraisonAI Context Management Best-in-Class

Feature Comparison

Architecture

Multi-Agent Context Flow

Terminology Reference

Core Concepts

Optimization Strategies

Token Segments

Defaults Reference

ContextConfig Defaults

Per-Tool Limits

Overflow Handling

Session Deduplication

CLI Commands

Analytics Dashboard

Session Statistics

Smart Default Context

Quick Start Examples

Process Flow Diagrams

Sequential Process Flow

Hierarchical Process Flow

Workflow Process Flow

Optimization Strategy Diagrams

Truncate Strategy

Sliding Window Strategy

Prune Tools Strategy

Summarize Strategy

Smart Strategy (Combined)

Context Overflow Handling

What Happens When Context Exceeds Limits

Tool Output Overflow Handling

LLM Summarization

Best Practices

Related Pages