Skip to main content

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

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

​
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}")

​
Next Steps