Context Management

Best-in-class context management with auto-compaction, session tracking, and multi-memory aggregation

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

1. Enable Context Management

   Basic

   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

Related

Keep conversations within the model’s token limit automatically.

Persist and recall information across agent turns and sessions.