> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Management

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Tip>
  **Looking for codebase analysis and PRP generation?** See [ContextAgent](/agents/context-agent) for Context Engineering.
  This page covers **Context Window Management** - token budgeting, compaction, and overflow prevention.
</Tip>

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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Sources[💬 Context Sources] --> Manager[⚙️ Context Manager]
    Manager --> LLM[✅ LLM Call]

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    class Sources input
    class Manager process
    class LLM output
```

| 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    |     ✅     |     ❌     |    ✅   |   ❌  |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Steps>
  <Step title="Enable Context Management">
    <CodeGroup>
      ```python Basic theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
      from praisonaiagents import Agent

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

      ```python Custom Config theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
      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
          )
      )
      ```
    </CodeGroup>

    ### With Workflows (Python)

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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}}"
    ```

    <Tip>
      **For tool-heavy workflows**: Always enable `context: true` to prevent token overflow from large search results.
    </Tip>
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant ContextManager
    participant LLM

    User->>Agent: Send a long message
    Agent->>ContextManager: Check token utilisation
    ContextManager-->>Agent: Compact history if over budget
    Agent->>LLM: Send trimmed context
    LLM-->>Agent: Response
    Agent-->>User: Answer within the window
```

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart TB
    START[📥 Incoming Message] --> CHECK{Utilization<br/>≥ 80%?}
    
    CHECK -->|No| PASS[✅ Pass Through]
    CHECK -->|Yes| STRATEGY{Which<br/>Strategy?}
    
    STRATEGY --> TRUNCATE[🔪 TRUNCATE<br/>Remove oldest]
    STRATEGY --> SLIDING[📜 SLIDING_WINDOW<br/>Keep recent N turns]
    STRATEGY --> SUMMARIZE[📝 SUMMARIZE<br/>LLM summarization]
    STRATEGY --> SMART[🧠 SMART<br/>Importance-based]
    STRATEGY --> PRUNE[🗑️ PRUNE_TOOLS<br/>Truncate tool outputs]
    STRATEGY --> NONDEST[🛡️ NON_DESTRUCTIVE<br/>Only prune tools]
    
    TRUNCATE --> BENEFIT{Benefit<br/>≥ 5%?}
    SLIDING --> BENEFIT
    SUMMARIZE --> BENEFIT
    SMART --> BENEFIT
    PRUNE --> BENEFIT
    NONDEST --> BENEFIT
    
    BENEFIT -->|Yes| APPLY[✅ Apply Optimization]
    BENEFIT -->|No| REVERT[↩️ Revert<br/>Keep Original]
    
    PASS --> LLM[🤖 Send to LLM]
    APPLY --> LLM
    REVERT --> LLM

    style START fill:#8B0000,color:#fff
    style CHECK fill:#F59E0B,color:#fff
    style STRATEGY fill:#F59E0B,color:#fff
    style BENEFIT fill:#F59E0B,color:#fff
    style LLM fill:#189AB4,color:#fff
```

***

## Compaction Strategies

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    subgraph "Choose Strategy Based On..."
        direction TB
        SPEED[⚡ Speed Priority] --> TRUNCATE[TRUNCATE]
        RECENT[📜 Recency Priority] --> SLIDING[SLIDING_WINDOW]
        QUALITY[🎯 Quality Priority] --> SUMMARIZE[SUMMARIZE]
        BALANCE[⚖️ Balance] --> SMART[SMART]
        TOOLS[🔧 Large Tool Outputs] --> PRUNE[PRUNE_TOOLS]
        SAFE[🛡️ Safety First] --> NONDEST[NON_DESTRUCTIVE]
    end

    style SPEED fill:#8B0000,color:#fff
    style RECENT fill:#8B0000,color:#fff
    style QUALITY fill:#8B0000,color:#fff
    style BALANCE fill:#8B0000,color:#fff
    style TOOLS fill:#8B0000,color:#fff
    style SAFE fill:#8B0000,color:#fff
```

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart TB
    subgraph "Session Lifecycle"
        direction TB
        INIT[🚀 Initialize Session] --> GOAL[🎯 Set Goal]
        GOAL --> PLAN[📋 Define Plan]
        PLAN --> EXEC[⚡ Execute Steps]
        EXEC --> PROGRESS[✅ Track Progress]
        PROGRESS --> EXEC
        PROGRESS --> DONE[🏁 Complete]
    end

    subgraph "Session State"
        direction TB
        S_SUMMARY[📝 Summary]
        S_GOAL[🎯 Goal]
        S_PLAN[📋 Plan Steps]
        S_PROGRESS[✅ Completed]
    end

    INIT --> S_SUMMARY
    GOAL --> S_GOAL
    PLAN --> S_PLAN
    EXEC --> S_PROGRESS

    style INIT fill:#8B0000,color:#fff
    style GOAL fill:#8B0000,color:#fff
    style PLAN fill:#8B0000,color:#fff
    style EXEC fill:#10B981,color:#fff
    style PROGRESS fill:#10B981,color:#fff
    style DONE fill:#189AB4,color:#fff
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:**

```xml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
<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:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart TB
    QUERY[🔍 Query] --> AGG[📦 Context Aggregator]
    
    AGG --> |concurrent| MEM[🧠 Short-term Memory]
    AGG --> |concurrent| KNOW[📚 Knowledge Base]
    AGG --> |concurrent| RAG[🔍 RAG Retrieval]
    
    MEM --> MERGE[🔀 Merge & Truncate]
    KNOW --> MERGE
    RAG --> MERGE
    
    MERGE --> TOKEN{Tokens<br/>≤ Budget?}
    TOKEN -->|Yes| OUT[✅ Aggregated Context]
    TOKEN -->|No| TRUNC[✂️ Truncate by Priority]
    TRUNC --> OUT

    style QUERY fill:#8B0000,color:#fff
    style AGG fill:#189AB4,color:#fff
    style MEM fill:#189AB4,color:#fff
    style KNOW fill:#189AB4,color:#fff
    style RAG fill:#189AB4,color:#fff
    style MERGE fill:#189AB4,color:#fff
    style OUT fill:#189AB4,color:#fff
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Warning>
  `ContextAgent` has been removed. Use the `context=` parameter instead.
</Warning>

**Before (removed):**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# DON'T DO THIS - ContextAgent is removed
from praisonaiagents import ContextAgent
agent = ContextAgent(...)  # ❌ ImportError
```

**After (correct):**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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`:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<AccordionGroup>
  <Accordion title="Enable auto-compact for long sessions">
    Turn on `auto_compact` so agents stay within model limits without manual intervention.
  </Accordion>

  <Accordion title="Combine memory and knowledge deliberately">
    Use memory for conversational recall and knowledge for document RAG — do not duplicate the same content in both.
  </Accordion>

  <Accordion title="Set strategy per workload">
    Chatbots favour `smart` compression; batch pipelines may prefer `truncate` for speed.
  </Accordion>

  <Accordion title="Monitor context in staging">
    Enable the context monitor while tuning prompts before disabling it in production.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Memory" icon="brain" href="/docs/features/advanced-memory">
    Learn about memory types and storage options
  </Card>

  <Card title="Knowledge" icon="book" href="/docs/features/knowledge">
    Add knowledge bases to your agents
  </Card>

  <Card title="RAG" icon="search" href="/rag/rag">
    Retrieval-Augmented Generation
  </Card>

  <Card title="Agents" icon="robot" href="/docs/features/agent-profiles">
    Core agent concepts
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card icon="ruler" href="/features/context-window-management">
    Keep conversations within the model's token limit automatically.
  </Card>

  <Card icon="brain" href="/features/memory">
    Persist and recall information across agent turns and sessions.
  </Card>
</CardGroup>