from praisonaiagents import Agent

agent = Agent(
    name="context-agent",
    instructions="Manage long conversations without overflowing the context window.",
)
agent.start("Summarise our thread so far and continue the task.")

AI Agents with Context Management

Looking for codebase analysis and PRP generation? See ContextAgent for Context Engineering. This page covers Context Window Management - token budgeting, compaction, and overflow prevention.

PraisonAI provides industry-leading context management with features no other framework offers: LLM-driven compression with session lineage and intelligent conversation compaction. The user runs a long chat; context management keeps token use within budget and compacts history before the model overflows.

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

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="Stay within the context window",
)

agent.start("Continue this long analysis")

The user keeps chatting; context management trims or compacts history as needed.

Quick Start

Enable Context Management

from praisonaiagents import Agent

# Enable context management with defaults
agent = Agent(
    instructions="You are a helpful assistant",
    context=True  # Auto-compact at 80% utilization
)

from praisonaiagents import Agent, ContextConfig

# Custom configuration
agent = Agent(
    instructions="You are a helpful assistant",
    context=ContextConfig(
        auto_compact=True,
        compact_threshold=0.8,
        keep_recent_turns=5,
        session_tracking=True,      # Track goal/plan/progress
        aggregate_memory=True,      # Concurrent multi-memory fetch
    )
)

With Workflows (Python)

from praisonaiagents import AgentFlow, Task, ContextConfig

# Workflow with context management
workflow = AgentFlow(
    steps=[...],
    context=True,  # Enable with defaults
)

# Or with custom config
workflow = AgentFlow(
    steps=[...],
    context=ContextConfig(
        auto_compact=True,
        compact_threshold=0.8,
        strategy="smart",
        tool_output_max=10000,  # Limit tool outputs (e.g., search results)
    ),
)

With YAML Workflows

name: Research Workflow
context: true  # Enable auto-compaction

# Or detailed config
context:
  auto_compact: true
  compact_threshold: 0.8
  strategy: smart
  tool_output_max: 10000

agents:
  researcher:
    role: Researcher
    tools:
      - tavily_search

steps:
  - agent: researcher
    action: "Research {{topic}}"

For tool-heavy workflows: Always enable context: true to prevent token overflow from large search results.

How It Works

Phase	What happens
1. Estimate	The manager counts tokens across messages, tools, memory, and knowledge
2. Decide	If utilisation crosses `compact_threshold`, a strategy runs
3. Compact	History is trimmed or summarised to fit the budget
4. Send	The trimmed context goes to the LLM and the reply returns to the user

How Context Decisions Are Made

The Context Manager automatically decides how to handle context based on utilization and strategy:

Compaction Strategies

Strategy	Description	Best For
`TRUNCATE`	Remove oldest messages	Speed, simple conversations
`SLIDING_WINDOW`	Keep last N turns	Recency-focused tasks
`SUMMARIZE`	LLM summarizes old context	Quality preservation
`SMART`	Importance-based (combines strategies)	General use (default)
`PRUNE_TOOLS`	Truncate old tool outputs	Tool-heavy agents
`NON_DESTRUCTIVE`	Only prune tools, keep history	Safety-critical

from praisonaiagents import Agent, ContextConfig, OptimizerStrategy

agent = Agent(
    instructions="You are a helpful assistant",
    context=ContextConfig(
        strategy=OptimizerStrategy.SLIDING_WINDOW,
        keep_recent_turns=10,
    )
)

Session Tracking

Track conversation state (goal, plan, progress) across turns - inspired by Agno’s SessionContextStore:

from praisonaiagents.context import SessionContextTracker

# Create tracker
tracker = SessionContextTracker(
    session_id="user123",
    track_summary=True,
    track_goal=True,
    track_plan=True,
    track_progress=True,
)

# Update state
tracker.update_goal("Build a Python web app")
tracker.update_plan([
    "1. Create Flask project",
    "2. Add routes",
    "3. Add database",
    "4. Deploy"
])

# Mark progress
tracker.add_progress("Created Flask project")
tracker.add_progress("Added routes")

# Get context for prompt
context = tracker.to_system_prompt_section()
print(context)

Output:

<session_context>
This is a continuation of an ongoing session. Here's where things stand:

**User's Goal**: Build a Python web app

**Plan**:
  1. Create Flask project
  2. Add routes
  3. Add database
  4. Deploy

**Progress**:
  ✓ Created Flask project
  ✓ Added routes

<session_context_guidelines>
Use this context to maintain continuity:
- Reference earlier decisions and conclusions naturally
- Don't re-ask questions that have already been answered
- Build on established understanding rather than starting fresh
</session_context_guidelines>
</session_context>

Multi-Memory Aggregation

Fetch context from multiple sources concurrently - inspired by CrewAI’s ContextualMemory:

from praisonaiagents.context import ContextAggregator
import asyncio

# Create aggregator
aggregator = ContextAggregator(max_tokens=4000)

# Register sources with priorities (lower = higher priority)
aggregator.register_source("memory", memory.search_short_term, priority=10)
aggregator.register_source("knowledge", knowledge.search, priority=20)
aggregator.register_source("rag", rag.retrieve, priority=30)

# Aggregate (async)
async def get_context(query):
    result = await aggregator.aggregate(query)
    print(f"Sources: {result.sources_used}")
    print(f"Tokens: {result.tokens_used}")
    return result.context

# Or sync
result = aggregator.aggregate_sync("user question")
print(result.context)

ContextConfig Options

Parameter	Type	Default	Description
`auto_compact`	bool	`True`	Enable automatic compaction
`compact_threshold`	float	`0.8`	Trigger at 80% utilization
`strategy`	OptimizerStrategy	`SMART`	Compaction strategy
`output_reserve`	int	`8000`	Tokens reserved for output
`history_ratio`	float	`0.6`	History budget ratio
`tool_output_max`	int	`10000`	Max tokens per tool output
`keep_recent_turns`	int	`5`	Recent turns to always keep
`session_tracking`	bool	`False`	Enable goal/plan/progress
`aggregate_memory`	bool	`False`	Enable multi-memory fetch

Monitoring Context Usage

from praisonaiagents import Agent
from praisonaiagents import ContextConfig, MonitorConfig

# Enable context monitoring
agent = Agent(
    instructions="You are a helpful assistant",
    context=ContextConfig(
        monitor=MonitorConfig(
            enabled=True,
            path="./context_logs/",
            format="human",  # or "json"
            frequency="turn",  # or "tool_call", "overflow"
            redact_sensitive=True,
        )
    )
)

Migration from ContextAgent

ContextAgent has been removed. Use the context= parameter instead.

Before (removed):

# DON'T DO THIS - ContextAgent is removed
from praisonaiagents import ContextAgent
agent = ContextAgent(...)  # ❌ ImportError

After (correct):

from praisonaiagents import Agent
from praisonaiagents import ContextConfig

agent = Agent(
    instructions="You are helpful",
    context=ContextConfig(
        session_tracking=True,
        aggregate_memory=True,
    )
)

Code Search (FastContextAgent)

For fast code search with parallel execution, use FastContextAgent:

from praisonaiagents.context.fast import FastContextAgent

# Create agent for code search
with FastContextAgent(
    workspace_path="/path/to/project",
    max_parallel=8,
    model="gpt-4o-mini"
) as agent:
    # Simple pattern search
    result = agent.search_simple("def main")
    
    # Intelligent LLM-powered search
    result = agent.search("Find all database connection handling")
    
    for match in result.matches[:5]:
        print(f"{match.file}:{match.line_number}")

API Reference

ContextConfig

Complete configuration for context management.

SessionContextTracker

Tracks session state across turns:

Method	Description
`update_summary(str)`	Update conversation summary
`update_goal(str)`	Update user’s objective
`update_plan(List[str])`	Update plan steps
`add_progress(str)`	Add completed step
`to_context_string()`	Get context as string
`to_system_prompt_section()`	Get formatted prompt section

ContextAggregator

Aggregates context from multiple sources:

Method	Description
`register_source(name, fn, priority)`	Register a context source
`aggregate(query, sources, max_tokens)`	Async aggregate
`aggregate_sync(query, sources, max_tokens)`	Sync aggregate

FastContextAgent

Fast parallel code search:

Method	Description
`search(query)`	LLM-powered intelligent search
`search_simple(query)`	Direct pattern search
`search_async(query)`	Async version

Best Practices

Enable auto-compact for long sessions

Turn on auto_compact so agents stay within model limits without manual intervention.

Combine memory and knowledge deliberately

Use memory for conversational recall and knowledge for document RAG — do not duplicate the same content in both.

Set strategy per workload

Chatbots favour smart compression; batch pipelines may prefer truncate for speed.

Monitor context in staging

Enable the context monitor while tuning prompts before disabling it in production.

Next Steps

Memory

Learn about memory types and storage options

Knowledge

Add knowledge bases to your agents

RAG

Retrieval-Augmented Generation

Agents

Core agent concepts

Keep conversations within the model’s token limit automatically.

Persist and recall information across agent turns and sessions.

​AI Agents with Context Management

​Quick Start

​With Workflows (Python)

​With YAML Workflows

​How It Works

​How Context Decisions Are Made

​Compaction Strategies

​Session Tracking

​Multi-Memory Aggregation

​ContextConfig Options

​Monitoring Context Usage

​Migration from ContextAgent

​Code Search (FastContextAgent)

​API Reference

​ContextConfig

​SessionContextTracker

​ContextAggregator

​FastContextAgent

​Best Practices

​Next Steps

Memory

Knowledge

RAG

Agents

​Related

AI Agents with Context Management

Quick Start

With Workflows (Python)

With YAML Workflows

How It Works

How Context Decisions Are Made

Compaction Strategies

Session Tracking

Multi-Memory Aggregation

ContextConfig Options

Monitoring Context Usage

Migration from ContextAgent

Code Search (FastContextAgent)

API Reference

ContextConfig

SessionContextTracker

ContextAggregator

FastContextAgent

Best Practices

Next Steps

Related