Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
FeaturePraisonAILangChainCrewAIAgno
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

Quick Start

from praisonaiagents import Agent

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

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 Context Decisions Are Made

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

Compaction Strategies

StrategyDescriptionBest For
TRUNCATERemove oldest messagesSpeed, simple conversations
SLIDING_WINDOWKeep last N turnsRecency-focused tasks
SUMMARIZELLM summarizes old contextQuality preservation
SMARTImportance-based (combines strategies)General use (default)
PRUNE_TOOLSTruncate old tool outputsTool-heavy agents
NON_DESTRUCTIVEOnly prune tools, keep historySafety-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

ParameterTypeDefaultDescription
auto_compactboolTrueEnable automatic compaction
compact_thresholdfloat0.8Trigger at 80% utilization
strategyOptimizerStrategySMARTCompaction strategy
output_reserveint8000Tokens reserved for output
history_ratiofloat0.6History budget ratio
tool_output_maxint10000Max tokens per tool output
keep_recent_turnsint5Recent turns to always keep
session_trackingboolFalseEnable goal/plan/progress
aggregate_memoryboolFalseEnable multi-memory fetch

Monitoring Context Usage

from praisonaiagents import Agent
from praisonaiagents.context 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.context 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:
MethodDescription
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:
MethodDescription
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:
MethodDescription
search(query)LLM-powered intelligent search
search_simple(query)Direct pattern search
search_async(query)Async version

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