Skip to main content

​
Context Monitor

The Context Monitor writes runtime context snapshots to disk, providing visibility into exactly what’s being sent to the model.

​
Agent-Centric Quick Start

from praisonaiagents import Agent
from praisonaiagents.context import ManagerConfig

# Enable monitoring via context param
agent = Agent(
    instructions="You are helpful.",
    context=ManagerConfig(
        monitor_enabled=True,
        monitor_path="./context.txt",
        monitor_format="human",  # or "json"
        redact_sensitive=True,
    ),
)

# Monitoring happens automatically during chat
response = agent.chat("Hello!")
# Check ./context.txt for snapshot

​
Low-Level API

from praisonaiagents.context import (
    ContextMonitor,
    ContextLedger,
    BudgetAllocation,
)

# Create monitor
monitor = ContextMonitor(
    enabled=True,
    path="./context.txt",
    format="human",
    frequency="turn",
)

# Write snapshot
monitor.snapshot(
    ledger=ledger_data,
    budget=budget_data,
    messages=messages,
    trigger="turn",
)

​
CLI Usage

# Enable monitoring when starting chat
praisonai chat --context-monitor

# Custom path and format
praisonai chat --context-monitor --context-monitor-path ./debug/context.json --context-monitor-format json

# In-session commands
/context on          # Enable monitoring
/context off         # Disable monitoring
/context dump        # Write snapshot now
/context path ./ctx  # Change output path
/context format json # Change format

​
Output Formats

​
Human-Readable (context.txt)

================================================================================
PRAISONAI CONTEXT SNAPSHOT
================================================================================
Timestamp: 2025-01-07T19:30:45Z
Session ID: abc123
Agent: CodeAssistant
Model: gpt-4o-mini
Model Limit: 128,000 tokens
Output Reserve: 8,000 tokens
Usable Budget: 120,000 tokens

--------------------------------------------------------------------------------
TOKEN LEDGER
--------------------------------------------------------------------------------
Component          | Tokens  | Budget  | % Used
-------------------|---------|---------|--------
System Prompt      |    1250 |    2000 |  62.5%
History            |   45000 |   72000 |  62.5%
Tool Outputs       |   18000 |   20000 |  90.0%
-------------------|---------|---------|--------
TOTAL              |   66820 |  120000 |  55.7%

--------------------------------------------------------------------------------
CONVERSATION HISTORY (12 turns)
--------------------------------------------------------------------------------
[Turn 1] USER: Help me refactor the authentication module
[Turn 2] ASSISTANT: I'll help you refactor...
...
================================================================================

​
JSON (context.json)

{
  "timestamp": "2025-01-07T19:30:45Z",
  "session_id": "abc123",
  "agent_name": "CodeAssistant",
  "model_name": "gpt-4o-mini",
  "budget": {
    "model_limit": 128000,
    "output_reserve": 8000,
    "usable": 120000
  },
  "ledger": {
    "system_prompt": 1250,
    "history": 45000,
    "tool_outputs": 18000,
    "total": 66820
  },
  "utilization": 0.557,
  "messages": [...],
  "warnings": []
}

​
Update Frequency

FrequencyTriggerUse Case
turnAfter each user/assistant turnGeneral monitoring
tool_callBefore/after each tool callDebug tool output growth
manualOnly via /context dumpOn-demand inspection
overflowWhen budget exceededAlert-based
monitor = ContextMonitor(
    enabled=True,
    frequency="tool_call",  # Write on every tool call
)

​
Sensitive Data Redaction

By default, sensitive data is redacted in snapshots: 
from praisonaiagents.context import redact_sensitive

text = "API key: sk-proj-abc123..."
redacted = redact_sensitive(text)
# Output: "API key: [REDACTED]"
Patterns redacted:
  • API keys (sk-, api_key, etc.)
  • Passwords
  • Tokens
  • Connection strings
# Disable redaction (not recommended)
praisonai chat --context-monitor --no-context-redact

​
Multi-Agent Monitoring

from praisonaiagents.context import MultiAgentMonitor

# Create per-agent monitors
multi_monitor = MultiAgentMonitor(base_path="./context/")

# Get monitor for each agent
researcher_monitor = multi_monitor.get_agent_monitor("researcher")
writer_monitor = multi_monitor.get_agent_monitor("writer")

# Enable all
multi_monitor.enable_all()
Output files: 
context/
├── context_researcher.txt
├── context_writer.txt
└── context_combined.txt

​
Safety Features

  1. Opt-in by default: Monitoring is disabled unless explicitly enabled
  2. Redaction: Sensitive data redacted by default
  3. Atomic writes: Uses temp file + rename to prevent corruption
  4. Respects ignore rules: Honors .praisonignore for file content

​
Configuration

# config.yaml
context:
  monitor:
    enabled: false
    path: ./context.txt
    format: human
    frequency: turn
    redact_sensitive: true

​
Environment Variables

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

​
Next Steps