Context Management API

CLI commands, flags, and configuration for context management

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.

How It Works

Quick Start

1. Enable context flags in chat

   praisonai chat --context-auto-compact --context-strategy smart --context-threshold 0.8
   
2. Inspect usage in session

   /context stats
   /context budget
   /context dump
   

CLI Flags

Auto-Compaction

# Enable automatic compaction (default in interactive mode)
praisonai chat --context-auto-compact

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

Interactive mode (praisonai chat, praisonai code) actually enforces the flag inside the worker loop — proactive check every turn plus a reactive retry on provider context-length errors. In non-interactive workflow runs the same flag is applied via the standard ContextManager config.

Optimization Strategy

# Available strategies: truncate, sliding_window, prune_tools, summarize, smart
praisonai chat --context-strategy smart

Trigger Threshold

# Trigger compaction at 80% utilization (0.0-1.0)
praisonai chat --context-threshold 0.8

Monitoring

# 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

# Enable sensitive data redaction (default)
praisonai chat --context-redact

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

Output Reserve

# 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

# 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

# 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

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

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

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

Track every turn in the ledger

Call ledger.track_history after each assistant message so budgets and snapshots stay accurate.

Snapshot at meaningful triggers

Write monitor snapshots on turn boundaries or overflow — not on every token delta.

Compose budget + monitor together

Allocate budgets before the run and attach a monitor when debugging context growth.

Keep the API surface minimal

Use the high-level Agent context= config in production; drop to the raw API only for custom integrations.

Related

Context Management

Overview of context management features

Context Monitor

Real-time context snapshots for debugging