Skip to main content
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

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

CommandDescription
/contextShow context stats summary
/context showShow detailed summary + budgets
/context statsToken ledger table
/context budgetBudget allocation details
/context dumpWrite snapshot to disk now
/context onEnable monitoring
/context offDisable monitoring
/context path <path>Set snapshot output path
/context format <fmt>Set format (human/json)
/context frequency <f>Set update frequency
/context compactTrigger 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

Call ledger.track_history after each assistant message so budgets and snapshots stay accurate.
Write monitor snapshots on turn boundaries or overflow — not on every token delta.
Allocate budgets before the run and attach a monitor when debugging context growth.
Use the high-level Agent context= config in production; drop to the raw API only for custom integrations.

Context Management

Overview of context management features

Context Monitor

Real-time context snapshots for debugging