Context Management CLI Reference

from praisonaiagents import Agent

agent = Agent(name="context-cli", instructions="Use context management CLI commands.")
agent.start("Show the current context window usage and compression stats.")

Complete reference for all context management CLI commands and flags. The user runs /context commands in the terminal to show, compact, or budget the active session.

How It Works

Quick Start

Interactive CLI

Launch chat or code mode, then inspect context:

praisonai chat
> /context
> /context stats

Compact When Full

Reduce token usage without losing key history:

> /context compact
> /context compact --strategy smart

Interactive Commands

Use these commands in praisonai chat or praisonai code interactive mode.

/context

Show context summary and statistics.

> /context

Output:

Context Summary
  Model:          gpt-4o-mini
  Model Limit:    128,000 tokens
  Output Reserve: 8,000 tokens
  Usable Budget:  120,000 tokens
  Current Usage:  15,234 tokens (12.7%)
  Turns:          8
  Messages:       16
  Auto-Compact:   enabled
  Monitoring:     disabled

/context show

Alias for /context. Shows summary view.

> /context show

/context stats

Show detailed token ledger by segment.

> /context stats

Output:

Token Ledger
Segment              Tokens     Budget     Used
--------------------------------------------------
system_prompt         1,200      2,000    60.0%
history              12,500     84,616    14.8%
tools_schema          1,534      2,000    76.7%
--------------------------------------------------
TOTAL                15,234    120,000    12.7%

/context budget

Show budget allocation details.

> /context budget

Output:

Budget Allocation
  Model Limit:     128,000
  Output Reserve:  8,000
  Usable:          120,000

  Segment Budgets:
    System Prompt: 2,000
    Rules:         500
    Skills:        500
    Memory:        1,000
    Tool Schemas:  2,000
    Tool Outputs:  20,000
    History:       84,616
    Buffer:        1,000

/context dump

Write context snapshot to disk immediately.

> /context dump

Output:

✓ Context snapshot written to: ./context.txt

/context on

Enable context monitoring.

> /context on

Output:

✓ Context monitoring enabled
Output: ./context.txt

/context off

Disable context monitoring.

> /context off

/context path <path>

Set monitor output path.

> /context path ./debug/context.json

/context format <human|json>

Set monitor output format.

> /context format json

/context frequency <turn|tool_call|manual|overflow>

Set monitor update frequency.

> /context frequency overflow

Frequency	Description
`turn`	Write after each turn (default)
`tool_call`	Write after each tool call
`manual`	Only write on `/context dump`
`overflow`	Write when approaching limit

/context compact

Trigger manual context optimization.

> /context compact

Output:

Optimizing context...
✓ Optimized: 45,000 → 30,000 tokens
Saved 15,000 tokens (33.3%)
Strategy: smart

/context history

Show optimization event history.

> /context history

Output:

Optimization History
Time                     Event                Tokens       Saved
----------------------------------------------------------------------
2024-01-07T12:00:00      overflow_detected       45,000          -
2024-01-07T12:00:01      auto_compact           45,000     -15,000
2024-01-07T12:05:00      snapshot               30,000          -

Showing last 3 of 3 events

/context config

Show resolved configuration with precedence info.

> /context config

Output:

Resolved Configuration
Precedence: CLI > ENV > config.yaml > defaults
Source: env

Auto-Compaction:
  auto_compact:           True
  compact_threshold:      0.8
  strategy:               smart
  compression_min_gain:   5.0%

Budget:
  output_reserve:         8,000
  default_tool_max:       10,000

Estimation:
  estimation_mode:        heuristic
  log_mismatch:           False

Monitoring:
  monitor_enabled:        False
  monitor_path:           ./context.txt
  monitor_format:         human
  monitor_frequency:      turn
  monitor_write_mode:     sync
  redact_sensitive:       True

Effective Budget:
  model_limit:            128,000
  usable:                 120,000
  history_budget:         84,616

On unknown models the CLI falls back to a coarse per-model table (see Per-model context windows); output_reserve is capped at window // 4 so small-window models still have a usable budget.

Automatic Compaction (Interactive)

In praisonai chat and praisonai code, the worker loop watches the running conversation and compacts it for you when it nears the model’s usable budget.

Proactive check every turn

The loop skips compaction unless all of these are true:

auto_compact is enabled (default True).
The conversation has at least 4 messages — very short sessions are never compacted.
Estimated tokens ≥ threshold × usable_budget (default threshold = 0.8).

When it fires you’ll see:

Auto-compacting: ~15234 tokens ≈ 82% of usable budget (18432).

Reactive retry on provider errors

If the model still returns a context-length error, the loop forces one compaction and retries the turn once:

Context limit hit; compacting and retrying...

The reactive retry honours auto_compact — if you disable it with --no-context-auto-compact, the raw provider error surfaces so nothing is rewritten without your consent.

Both paths reuse the same summariser as the manual /context compact command. Manual /context compact is unchanged.

Per-model context windows

The loop looks up the model’s context window in this order:

litellm.get_model_info(model) — used when available.
Built-in fallback table (below).
Default: 128,000 tokens.

Provider prefixes like openai/… are stripped before lookup. The output_reserve (default 8000) is subtracted to give the usable budget, but is capped at window // 4 on small-window models so compaction doesn’t fire on every turn.

Model prefix	Window (tokens)
`gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`	128,000
`gpt-4`	8,192
`gpt-3.5-turbo`	16,385
`o1`	200,000
`o1-mini`	128,000
`claude-3-5-sonnet`, `claude-3-5-haiku`, `claude-3-opus`, `claude-3-sonnet`, `claude-3-haiku`	200,000
`gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`	1,000,000
anything else	128,000

CLI Flags

Use these flags when starting praisonai chat or praisonai code.

Auto-Compaction

# Enable auto-compaction (default)
praisonai chat --context-auto-compact

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

Strategy

praisonai chat --context-strategy smart

Options: smart, truncate, sliding_window, summarize, prune_tools

Threshold

praisonai chat --context-threshold 0.8

Value: 0.0 to 1.0 (default: 0.8)

Monitoring

# Enable monitoring
praisonai chat --context-monitor

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

# Set format
praisonai chat --context-monitor-format json

# Set frequency
praisonai chat --context-monitor-frequency overflow

Redaction

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

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

Output Reserve

praisonai chat --context-output-reserve 16000

Estimation Mode

praisonai chat --context-estimation-mode validated

Options: heuristic, accurate, validated

Mismatch Logging

praisonai chat --context-log-mismatch

Snapshot Timing

praisonai chat --context-snapshot-timing both

Options: pre_optimization, post_optimization, both

Write Mode

praisonai chat --context-write-mode async

Options: sync, async

Show Config

praisonai chat --context-show-config

Shows resolved configuration and exits.

Environment Variables

# Auto-compaction
export PRAISONAI_CONTEXT_AUTO_COMPACT=true
export PRAISONAI_CONTEXT_THRESHOLD=0.8
export PRAISONAI_CONTEXT_STRATEGY=smart

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

# Redaction
export PRAISONAI_CONTEXT_REDACT=true

# Budget
export PRAISONAI_CONTEXT_OUTPUT_RESERVE=8000

# Estimation
export PRAISONAI_CONTEXT_ESTIMATION_MODE=heuristic

config.yaml

context:
  auto_compact: true
  compact_threshold: 0.8
  strategy: smart
  output_reserve: 8000
  
  monitor:
    enabled: false
    path: ./context.txt
    format: human
    frequency: turn
    write_mode: sync
  
  redact_sensitive: true
  
  estimation:
    mode: heuristic
    log_mismatch: false

Precedence

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

CLI flags - --context-* flags
Environment variables - PRAISONAI_CONTEXT_*
config.yaml - context: section
Defaults - Built-in defaults

Troubleshooting

Context overflow errors

The interactive loop already retries once after a provider context-length error (see Automatic Compaction (Interactive)). If overflows persist:

# Compact earlier (lower % of usable budget)
praisonai chat --context-threshold 0.7

# Or use a more aggressive strategy
praisonai chat --context-strategy truncate

If you’d rather see the raw provider error than let the loop rewrite history, disable auto-compaction:

praisonai chat --no-context-auto-compact

Monitor not updating

# Check if enabled
> /context config

# Enable and set frequency
> /context on
> /context frequency turn

Sensitive data in snapshots

# Ensure redaction is enabled
praisonai chat --context-redact

# Check patterns in snapshot
> /context dump

Best Practices

Monitor Context Usage Regularly

Run /context stats at the start of long sessions to understand your token budget before it fills up. Proactive monitoring prevents unexpected compaction mid-task.

Set Threshold Below 90%

Use --context-threshold 0.8 (80%) rather than the default. This leaves enough headroom for the compaction response itself without triggering at the very last moment. On very small models (e.g. gpt-4 at 8,192 tokens) leave the default threshold and output_reserve: the reserve is auto-capped at a quarter of the window so compaction still leaves you plenty of room to answer.

Use Compact Strategy for Long Sessions

The compact strategy summarizes old turns intelligently. Use truncate only when you need to preserve exact recent messages and can afford to lose early conversation history.

Enable Redaction for Sensitive Data

Always pass --context-redact when your conversations may contain API keys, passwords, or PII. Redaction patterns are applied before any snapshot is written to disk.

Context Compression

Automatic context window management and compaction

Context Budgeter

Configure token budget allocation per segment

​How It Works

​Quick Start

​Interactive Commands

​/context

​/context show

​/context stats

​/context budget

​/context dump

​/context on

​/context off

​/context path <path>

​/context format <human|json>

​/context frequency <turn|tool_call|manual|overflow>

​/context compact

​/context history

​/context config

​Automatic Compaction (Interactive)

​Per-model context windows

​CLI Flags

​Auto-Compaction

​Strategy

​Threshold

​Monitoring

​Redaction

​Output Reserve

​Estimation Mode

​Mismatch Logging

​Snapshot Timing

​Write Mode

​Show Config

​Environment Variables

​config.yaml

​Precedence

​Troubleshooting

​Context overflow errors

​Monitor not updating

​Sensitive data in snapshots

​Best Practices

​Related

Context Compression

Context Budgeter

How It Works

Quick Start

Interactive Commands

/context

/context show

/context stats

/context budget

/context dump

/context on

/context off

/context path <path>

/context format <human|json>

/context frequency <turn|tool_call|manual|overflow>

/context compact

/context history

/context config

Automatic Compaction (Interactive)

Per-model context windows

CLI Flags

Auto-Compaction

Strategy

Threshold

Monitoring

Redaction

Output Reserve

Estimation Mode

Mismatch Logging

Snapshot Timing

Write Mode

Show Config

Environment Variables

config.yaml

Precedence

Troubleshooting

Context overflow errors

Monitor not updating

Sensitive data in snapshots

Best Practices

Related