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

# Context Strategies & Defaults

> Complete guide to context management strategies, defaults, and customization

# Context Strategies & Defaults

This is the master reference for context management in PraisonAI Agents. It covers all strategies, default behaviors, and how to customize them.

<Note>
  Context management is **opt-in** via the `context=` parameter. When disabled (default), there is zero performance overhead.
</Note>

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import ManagerConfig

# Simple: Enable with defaults
agent = Agent(
    instructions="You are helpful.",
    context=True,  # Enable context management
)

# Custom: Fine-tune behavior
agent = Agent(
    instructions="You are a code assistant.",
    context=ManagerConfig(
        auto_compact=True,
        compact_threshold=0.8,
        strategy="smart",
        output_reserve=16384,
    ),
)
```

## Default Behavior

### Interactive Mode (`praisonai chat`)

| Setting               | Default        | Reason                         |
| --------------------- | -------------- | ------------------------------ |
| `context=`            | `False`        | Zero overhead for simple chats |
| When enabled:         |                |                                |
| - `auto_compact`      | `True`         | Prevent overflow automatically |
| - `compact_threshold` | `0.8`          | Trigger at 80% usage           |
| - `strategy`          | `smart`        | Best balance of preservation   |
| - `output_reserve`    | Model-specific | 8K-16K tokens                  |

**To enable in CLI:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai chat --context  # Enable with defaults
```

### Auto-Agents Mode (`Agents`)

| Setting               | Default | Reason                         |
| --------------------- | ------- | ------------------------------ |
| `context=`            | `False` | Zero overhead for simple tasks |
| When enabled:         |         |                                |
| - `auto_compact`      | `True`  | Handle long multi-agent tasks  |
| - `compact_threshold` | `0.8`   | Trigger at 80% usage           |
| - `strategy`          | `smart` | Preserve important context     |

**To enable:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import AgentTeam

agents = AgentTeam(
    agents=[...],
    context=True,  # Enable for all agents
)
```

## Optimization Strategies

### Strategy Overview

| Strategy         | Description                       | Pros              | Cons                  |
| ---------------- | --------------------------------- | ----------------- | --------------------- |
| `truncate`       | Remove oldest messages first      | Fast, simple      | Loses early context   |
| `sliding_window` | Keep N most recent messages       | Preserves recent  | Loses early context   |
| `prune_tools`    | Truncate old tool outputs         | Keeps messages    | May lose tool details |
| `summarize`      | Replace old messages with summary | Preserves meaning | Slower, uses API      |
| `smart`          | Combine strategies intelligently  | Best balance      | More complex          |

### When to Use Each

* **`truncate`**: Simple chatbots, Q\&A agents
* **`sliding_window`**: Long conversations where recent context matters most
* **`prune_tools`**: Tool-heavy agents with large outputs
* **`summarize`**: When historical context is critical
* **`smart`** (recommended): Production use, balances all concerns

## Overflow Handling

### Threshold Playbook

| Usage | Level    | Action                                    |
| ----- | -------- | ----------------------------------------- |
| 70%   | INFO     | Monitor usage, no action needed           |
| 80%   | NOTICE   | Consider optimization soon                |
| 90%   | WARNING  | Trigger auto-compact if enabled           |
| 95%   | CRITICAL | Aggressive optimization required          |
| 100%  | OVERFLOW | Immediate truncation to prevent API error |

### Automatic Handling

When `auto_compact=True`, the system automatically:

1. Monitors token usage before each API call
2. Triggers optimization when threshold is reached
3. Applies the configured strategy
4. Logs the optimization event

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Example: Custom threshold
agent = Agent(
    instructions="...",
    context=ManagerConfig(
        auto_compact=True,
        compact_threshold=0.7,  # Earlier trigger
        strategy="smart",
    ),
)
```

## Budgeting

### Token Allocation

The context budget is divided into segments:

| Segment       | Default   | Description          |
| ------------- | --------- | -------------------- |
| System Prompt | 2,000     | Agent instructions   |
| Rules         | 500       | Behavioral rules     |
| Skills        | 500       | Skill definitions    |
| Memory        | 1,000     | Long-term memory     |
| Tools Schema  | 2,000     | Tool definitions     |
| Tool Outputs  | 20,000    | Tool call results    |
| History       | Remaining | Conversation history |
| Buffer        | 1,000     | Safety margin        |

### Custom Budgets

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ContextBudgeter

budgeter = ContextBudgeter(
    model="gpt-4o",
    system_prompt_budget=3000,
    tools_schema_budget=5000,
    memory_budget=2000,
)
budget = budgeter.allocate()
print(f"Usable: {budget.usable:,} tokens")
```

## Monitoring

### Enable Context Monitoring

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
    instructions="...",
    context=ManagerConfig(
        monitor_enabled=True,
        monitor_path="./context_debug.txt",
        monitor_format="human",  # or "json"
    ),
)
```

### Snapshot Output Example

```
================================================================================
PRAISONAI CONTEXT SNAPSHOT
================================================================================
Timestamp: 2026-01-08T12:00:00Z
Model: gpt-4o-mini
Model Limit: 128,000 tokens
Output Reserve: 16,384 tokens
Usable Budget: 111,616 tokens

--------------------------------------------------------------------------------
TOKEN LEDGER
--------------------------------------------------------------------------------
Segment              |     Tokens |     Budget |    Usage
--------------------------------------------------------------------------------
System Prompt        |        150 |      2,000 |    7.5%
History              |      5,230 |     84,616 |    6.2%
Tool Outputs         |      1,200 |     20,000 |    6.0%
--------------------------------------------------------------------------------
TOTAL                |      6,580 |    111,616 |    5.9%
```

### Percentage Display

Context utilization is displayed with smart formatting:

* Values `< 0.1%`: Shows `<0.1%`
* Values `< 1%`: Shows 2 decimal places (e.g., `0.02%`)
* Values `>= 1%`: Shows 1 decimal place (e.g., `5.3%`)

## Multi-Agent Policies

### Isolated (Default)

Each agent has its own context ledger:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ManagerConfig

agent1 = Agent(
    instructions="Researcher",
    context=ManagerConfig(policy="isolated"),
)
agent2 = Agent(
    instructions="Writer", 
    context=ManagerConfig(policy="isolated"),
)
```

### Shared

Agents share a common context ledger:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import AgentTeam

agents = AgentTeam(
    agents=[agent1, agent2],
    context=ManagerConfig(policy="shared"),
)
```

## Redaction & Security

Sensitive data is automatically redacted in snapshots:

* API keys (OpenAI, Anthropic, Google, AWS, etc.)
* Passwords and secrets
* Email addresses (optional)
* Custom patterns

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
    instructions="...",
    context=ManagerConfig(
        monitor_enabled=True,
        redact_sensitive=True,
    ),
)
```

## Configuration Reference

### ManagerConfig Options

| Option              | Type  | Default        | Description                |
| ------------------- | ----- | -------------- | -------------------------- |
| `auto_compact`      | bool  | `True`         | Auto-optimize on threshold |
| `compact_threshold` | float | `0.8`          | Trigger at this usage %    |
| `strategy`          | str   | `"smart"`      | Optimization strategy      |
| `output_reserve`    | int   | Model-specific | Reserved for output        |
| `monitor_enabled`   | bool  | `False`        | Enable snapshots           |
| `monitor_path`      | str   | `None`         | Snapshot file path         |
| `monitor_format`    | str   | `"human"`      | `"human"` or `"json"`      |
| `redact_sensitive`  | bool  | `True`         | Redact secrets             |
| `policy`            | str   | `"isolated"`   | Multi-agent policy         |

## See Also

* [Context Budgeting](/features/context-budgeter)
* [Context Monitoring](/features/context-monitor)
* [Context Optimization](/features/context-optimizer)
* [Context Compaction](/features/context-compaction)
* [Fast Context](/features/fast-context)