Context Management API

CLI commands, flags, and configuration for context management

Diagram

python

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?")

Scope: process-local, in-memory, opt-in

get_global_store() returns the low-level ContextStoreImpl singleton. Before you use it, know exactly what it is:

In-memory, scoped to the current process. It is not persisted automatically and is never shared with another process. A separate praisonai CLI process can therefore never see a store an agent run populated. Cross-process sharing requires explicit snapshot() / restore().
Nothing in the agent runtime writes to it. Agent.chat_history and the session/memory subsystems keep their own state. This store is an opt-in structure a caller must populate — via store.get_mutator(agent_id).append(...).commit() or store.add_shared_context(...).
Empty on first creation. It only holds what a caller put in it during this process. The same singleton is returned on later calls, so it may already contain data from earlier in the process.

Populate the store

python

from praisonaiagents.context import get_global_store

store = get_global_store()
mutator = store.get_mutator("agent-1")
mutator.append({"role": "user", "content": "hi"})
mutator.commit()   # nothing is stored until you commit

Cross-process sharing

The store lives in one process only. To move it to another process, serialise it with snapshot() and rebuild it with restore():

python

from praisonaiagents.context import get_global_store

# Process A — dump the store to bytes
data = get_global_store().snapshot()
open("store.bin", "wb").write(data)

# Process B — rebuild the store from those bytes
store = get_global_store()
store.restore(open("store.bin", "rb").read())

Context Management API

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

Scope: process-local, in-memory, opt-in

get_global_store() returns a singleton that is easy to misread. Three facts govern its behaviour:

In-memory, process-local. The store lives only in the current process. It is not persisted and not shared, so a separate praisonai CLI process can never see a store an agent run populated. Cross-process sharing requires explicit snapshot() / restore().
Nothing in the agent runtime writes to it. Agent.chat_history and the session/memory subsystems keep their own state. This store is opt-in — a caller must populate it via get_mutator(...) or add_shared_context(...).
Empty until you fill it. A freshly created store holds nothing; the same singleton is returned on later calls, so it may already contain data you added earlier in this process.

Populate the store:

python

from praisonaiagents.context import get_global_store

store = get_global_store()
mutator = store.get_mutator("agent-1")
mutator.append({"role": "user", "content": "hi"})
mutator.commit()  # nothing is stored until commit()

Cross-process sharing with snapshot() / restore():

python

from praisonaiagents.context import get_global_store, ContextStoreImpl

# Process A — serialise the store
blob = get_global_store().snapshot()  # bytes: agent history + shared context

# Process B — rebuild it
store_b = ContextStoreImpl()
store_b.restore(blob)

The user inspects or trims context via CLI and config; the agent stays within the configured window.

Diagram

How It Works

Diagram

Quick Start

Enable context flags in chat

bash

praisonai chat --context-auto-compact --context-strategy smart --context-threshold 0.8

Inspect usage in session

bash

/context stats
/context budget
/context dump

CLI Flags

Auto-Compaction

bash

# Enable automatic compaction (default in interactive mode)
praisonai chat --context-auto-compact

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

Optimization Strategy

bash

# Available strategies: truncate, sliding_window, prune_tools, summarize, smart
praisonai chat --context-strategy smart

Trigger Threshold

bash

# Trigger compaction at 80% utilization (0.0-1.0)
praisonai chat --context-threshold 0.8

Monitoring

bash

# 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

bash

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

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

Output Reserve

bash

# Reserve tokens for model output
praisonai chat --context-output-reserve 8000

Interactive Commands

Command	Description
`/context`	Show context stats summary
`/context show`	Show detailed summary + budgets
`/context stats`	Token ledger table
`/context budget`	Budget allocation details
`/context dump`	Write snapshot to disk now
`/context on`	Enable monitoring
`/context off`	Disable monitoring
`/context path <path>`	Set snapshot output path
`/context format <fmt>`	Set format (human/json)
`/context frequency <f>`	Set update frequency
`/context compact`	Trigger optimization now

Examples

bash

# 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

bash

# 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

yaml

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

CLI flags (--context-strategy smart)
Environment variables (PRAISONAI_CONTEXT_STRATEGY=smart)
Config file (config.yaml)
Defaults

Python SDK

python

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

python

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

Track every turn in the ledger

Call ledger.track_history after each assistant message so budgets and snapshots stay accurate.

Snapshot at meaningful triggers

Write monitor snapshots on turn boundaries or overflow — not on every token delta.

Compose budget + monitor together

Allocate budgets before the run and attach a monitor when debugging context growth.

Keep the API surface minimal

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

Context Management API

Scope: process-local, in-memory, opt-in

Populate the store

Cross-process sharing

Context Management API

Scope: process-local, in-memory, opt-in

How It Works

Quick Start

CLI Flags

Auto-Compaction

Optimization Strategy

Trigger Threshold

Monitoring

Redaction

Output Reserve

Interactive Commands

Examples

Environment Variables

Configuration File

Precedence Order

Python SDK

Complete Example

Best Practices

Related