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

> CLI commands, flags, and configuration for context management

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Context Management API"
        Request[📋 User Request] --> Process[⚙️ Context Management API]
        Process --> Result[✅ Result]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Request input
    class Process process
    class Result output
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Context Management API

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

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

agent = Agent(
    name="context-agent",
    instructions="Manage conversation context efficiently.",
    context_window=8000,
)
agent.start("What did we discuss in the previous session?")
```

# Context Management API

Complete reference for CLI commands, flags, environment variables, and configuration options.

The user inspects or trims context via CLI and config; the agent stays within the configured window.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Context Management API"
        In[📝 CLI Input] --> Ctx[🧠 Context Manager]
        Ctx --> Trim[✂️ Trim / Compress]
        Trim --> Agent[🤖 Agent]
        Agent --> Out[✅ Response]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class In input
    class Ctx,Trim process
    class Agent agent
    class Out output
```

## How It Works

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

    User->>CLI: praisonai context inspect
    CLI->>ContextAPI: Load current window
    ContextAPI-->>Agent: Trimmed context
    Agent-->>User: Response within budget
```

## Quick Start

<Steps>
  <Step title="Enable context flags in chat">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai chat --context-auto-compact --context-strategy smart --context-threshold 0.8
    ```
  </Step>

  <Step title="Inspect usage in session">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    /context stats
    /context budget
    /context dump
    ```
  </Step>
</Steps>

## CLI Flags

### Auto-Compaction

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable automatic compaction (default in interactive mode)
praisonai chat --context-auto-compact

# Disable automatic compaction
praisonai chat --no-context-auto-compact
```

### Optimization Strategy

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Available strategies: truncate, sliding_window, prune_tools, summarize, smart
praisonai chat --context-strategy smart
```

### Trigger Threshold

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Trigger compaction at 80% utilization (0.0-1.0)
praisonai chat --context-threshold 0.8
```

### Monitoring

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

# Set output path
praisonai chat --context-monitor-path ./debug/context.txt

# Set output format (human or json)
praisonai chat --context-monitor-format json

# Set update frequency (turn, tool_call, manual, overflow)
praisonai chat --context-monitor-frequency turn
```

### Redaction

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable sensitive data redaction (default)
praisonai chat --context-redact

# Disable redaction
praisonai chat --no-context-redact
```

### Output Reserve

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Reserve tokens for model output
praisonai chat --context-output-reserve 8000
```

## Interactive Commands

| Command                  | Description                     |
| ------------------------ | ------------------------------- |
| `/context`               | Show context stats summary      |
| `/context show`          | Show detailed summary + budgets |
| `/context stats`         | Token ledger table              |
| `/context budget`        | Budget allocation details       |
| `/context dump`          | Write snapshot to disk now      |
| `/context on`            | Enable monitoring               |
| `/context off`           | Disable monitoring              |
| `/context path <path>`   | Set snapshot output path        |
| `/context format <fmt>`  | Set format (human/json)         |
| `/context frequency <f>` | Set update frequency            |
| `/context compact`       | Trigger optimization now        |

### Examples

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start chat with monitoring
praisonai chat --context-monitor

# In session:
❯ /context stats
Token Ledger
────────────────────────────────
System Prompt:     1,250 tokens
History:          45,000 tokens
Tool Outputs:     18,000 tokens
────────────────────────────────
TOTAL:            66,820 tokens

❯ /context budget
Budget Allocation (gpt-4o-mini)
────────────────────────────────
Model Limit:     128,000 tokens
Output Reserve:   16,384 tokens
Usable:          111,616 tokens
Utilization:         59.8%

❯ /context dump
✓ Context snapshot written to ./context.txt

❯ /context compact
✓ Optimized: 45,000 → 12,000 tokens (saved 33,000)
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Auto-compaction
PRAISONAI_CONTEXT_AUTO_COMPACT=true

# Strategy
PRAISONAI_CONTEXT_STRATEGY=smart

# Threshold
PRAISONAI_CONTEXT_THRESHOLD=0.8

# Output reserve
PRAISONAI_CONTEXT_OUTPUT_RESERVE=8000

# Monitoring
PRAISONAI_CONTEXT_MONITOR=true
PRAISONAI_CONTEXT_MONITOR_PATH=./context.txt
PRAISONAI_CONTEXT_MONITOR_FORMAT=human
PRAISONAI_CONTEXT_MONITOR_FREQUENCY=turn

# Redaction
PRAISONAI_CONTEXT_REDACT=true
```

## Configuration File

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# .praison/config.yaml or config.yaml
context:
  auto_compact: true
  compact_threshold: 0.8
  strategy: smart
  output_reserve: 8000
  
  budgets:
    system_prompt: 2000
    rules: 500
    skills: 500
    memory: 1000
    tools_schema: 2000
    tool_outputs: 20000
    buffer: 1000
  
  monitor:
    enabled: false
    path: ./context.txt
    format: human
    frequency: turn
    redact_sensitive: true
```

## Precedence Order

Configuration is resolved in this order (highest to lowest):

1. **CLI flags** (`--context-strategy smart`)
2. **Environment variables** (`PRAISONAI_CONTEXT_STRATEGY=smart`)
3. **Config file** (`config.yaml`)
4. **Defaults**

## Python SDK

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import (
    # Token estimation
    estimate_tokens_heuristic,
    estimate_messages_tokens,
    estimate_tool_schema_tokens,
    
    # Budgeting
    ContextBudgeter,
    BudgetAllocation,
    get_model_limit,
    get_output_reserve,
    
    # Ledger
    ContextLedger,
    ContextLedgerManager,
    MultiAgentLedger,
    
    # Optimization
    get_optimizer,
    OptimizerStrategy,
    TruncateOptimizer,
    SlidingWindowOptimizer,
    PruneToolsOptimizer,
    SummarizeOptimizer,
    NonDestructiveOptimizer,
    SmartOptimizer,
    
    # Monitoring
    ContextMonitor,
    MultiAgentMonitor,
    ContextSnapshot,
    format_human_snapshot,
    format_json_snapshot,
    redact_sensitive,
)
```

## Complete Example

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import (
    ContextBudgeter,
    ContextLedgerManager,
    ContextMonitor,
    get_optimizer,
    OptimizerStrategy,
)

# Set up context management
budgeter = ContextBudgeter(model="gpt-4o-mini")
ledger = ContextLedgerManager()
optimizer = get_optimizer(OptimizerStrategy.SMART)
monitor = ContextMonitor(enabled=True, path="./context.txt")

# Create agent
agent = Agent(
    instructions="You are a helpful assistant.",
    llm="gpt-4o-mini",
)

# Track system prompt
ledger.track_system_prompt(agent.instructions)

# Conversation loop
messages = []
while True:
    user_input = input("You: ")
    messages.append({"role": "user", "content": user_input})
    ledger.track_history(messages[-1:])
    
    # Check if optimization needed
    current = ledger.get_total()
    budget = budgeter.allocate()
    if budgeter.get_utilization(current) > 0.8:
        messages, stats = optimizer.optimize(messages, target_tokens=int(budget.usable * 0.7))
        print(f"[Optimized: saved {stats.tokens_saved} tokens]")
    
    # Get response
    response = agent.chat(user_input)
    messages.append({"role": "assistant", "content": response})
    ledger.track_history(messages[-1:])
    
    # Write snapshot
    monitor.snapshot(ledger=ledger.get_ledger(), budget=budget, messages=messages, trigger="turn")
    
    print(f"Assistant: {response}")
```

## Best Practices

<AccordionGroup>
  <Accordion title="Track every turn in the ledger">
    Call `ledger.track_history` after each assistant message so budgets and snapshots stay accurate.
  </Accordion>

  <Accordion title="Snapshot at meaningful triggers">
    Write monitor snapshots on turn boundaries or overflow — not on every token delta.
  </Accordion>

  <Accordion title="Compose budget + monitor together">
    Allocate budgets before the run and attach a monitor when debugging context growth.
  </Accordion>

  <Accordion title="Keep the API surface minimal">
    Use the high-level Agent `context=` config in production; drop to the raw API only for custom integrations.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Context Management" icon="layer-group" href="/docs/features/context-management">
    Overview of context management features
  </Card>

  <Card title="Context Monitor" icon="eye" href="/docs/features/context-monitor">
    Real-time context snapshots for debugging
  </Card>
</CardGroup>