Praison AI

Context Management CLI Reference

Complete CLI reference for context management commands and flags

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

Diagram

Context Management CLI Reference

💻 CLI

👁️ /context show

📊 /context stats

💰 /context budget

🗜️ /context compact

📋 Context Summary

📈 Token Ledger

⚖️ Budget Allocation

⬇️ Reduce Tokens

How It Works

Diagram
Context Management CLI ReferenceAgentUserContext Management CLI ReferenceAgentUserRequestProcess requestResult Agent–>>User: Response

Quick Start

  1. Interactive CLI

    Launch chat or code mode, then inspect context:

    bash
    praisonai chat
> /context
> /context stats
  2. Compact When Full

    Reduce token usage without losing key history:

    bash
    > /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.

bash
> /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.

bash
> /context show

/context stats

Show detailed token ledger by segment.

bash
> /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.

bash
> /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.

bash
> /context dump

Output:

✓ Context snapshot written to: ./context.txt

/context on

Enable context monitoring.

bash
> /context on

Output:

✓ Context monitoring enabled
Output: ./context.txt

/context off

Disable context monitoring.

bash
> /context off

/context path \<path\>

Set monitor output path.

bash
> /context path ./debug/context.json

/context format \<human|json\>

Set monitor output format.

bash
> /context format json

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

Set monitor update frequency.

bash
> /context frequency overflow
FrequencyDescription
turnWrite after each turn (default)
tool_callWrite after each tool call
manualOnly write on /context dump
overflowWrite when approaching limit

/context compact

Trigger manual context optimization.

bash
> /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.

bash
> /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.

bash
> /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

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.

  1. 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).
  2. 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.

Per-model context windows

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

  1. litellm.get_model_info(model) — used when available.
  2. Built-in fallback table (below).
  3. 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 prefixWindow (tokens)
gpt-4o, gpt-4o-mini, gpt-4-turbo128,000
gpt-48,192
gpt-3.5-turbo16,385
o1200,000
o1-mini128,000
claude-3-5-sonnet, claude-3-5-haiku, claude-3-opus, claude-3-sonnet, claude-3-haiku200,000
gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash1,000,000
anything else128,000

CLI Flags

Use these flags when starting praisonai chat or praisonai code.

Auto-Compaction

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

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

Strategy

bash
praisonai chat --context-strategy smart

Options: smart, truncate, sliding_window, summarize, prune_tools

Threshold

bash
praisonai chat --context-threshold 0.8

Value: 0.0 to 1.0 (default: 0.8)

Monitoring

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

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

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

Output Reserve

bash
praisonai chat --context-output-reserve 16000

Estimation Mode

bash
praisonai chat --context-estimation-mode validated

Options: heuristic, accurate, validated

Mismatch Logging

bash
praisonai chat --context-log-mismatch

Snapshot Timing

bash
praisonai chat --context-snapshot-timing both

Options: pre_optimization, post_optimization, both

Write Mode

bash
praisonai chat --context-write-mode async

Options: sync, async

Show Config

bash
praisonai chat --context-show-config

Shows resolved configuration and exits.

Environment Variables

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

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):

  1. CLI flags – --context-* flags
  2. Environment variables – PRAISONAI_CONTEXT_*
  3. config.yaml – context: section
  4. 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:

bash
# 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:

bash
praisonai chat --no-context-auto-compact

Monitor not updating

bash
# Check if enabled
> /context config

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

Sensitive data in snapshots

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

Related

Context Compression

Automatic context window management and compaction

 Context Budgeter

Configure token budget allocation per segment