Skip to main content
from praisonaiagents import Agent

agent = Agent(name="ledger-agent", instructions="Track token usage across conversations.")
agent.start("Show me the token usage ledger for today.")

​
Context Ledger

The Context Ledger tracks token usage across different context segments, enabling precise budget monitoring and optimization decisions. The user tracks token spend; the ledger records per-segment usage for budget decisions.

​
How It Works

​
Quick Start

1

Create a ledger

from praisonaiagents.context import ContextLedgerManager

ledger = ContextLedgerManager()
ledger.track_system_prompt("You are a helpful AI assistant.")
ledger.track_history([
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"},
])
print(f"Total tokens: {ledger.get_total()}")
2

View stats in chat

/context stats

​
Tracked Segments

SegmentDescription
system_promptAgent instructions
rulesWorkspace rules (.praisonrules)
skillsSkill definitions
memoryPersistent memory context
tools_schemaTool/function definitions
historyConversation messages
tool_outputsTool call results
bufferSafety margin

​
API Reference

​
Track Segments

ledger = ContextLedgerManager()

# Track system prompt
ledger.track_system_prompt("You are helpful.")

# Track rules
ledger.track_rules("Always be concise.")

# Track skills
ledger.track_skills("Skill: code-review...")

# Track memory
ledger.track_memory("User prefers Python.")

# Track tools
ledger.track_tools([{"name": "read_file", ...}])

# Track history
ledger.track_history(messages)

# Track tool outputs
ledger.track_tool_output("File contents here...")

​
Get Totals

# Total tokens
total = ledger.get_total()

# Get underlying ledger data
ledger_data = ledger.get_ledger()
print(f"System: {ledger_data.system_prompt}")
print(f"History: {ledger_data.history}")
print(f"Tools: {ledger_data.tools_schema}")

​
Reset

# Reset all counts
ledger.reset()

# Reset specific segment
ledger.reset_history()

​
ContextLedger Data Class

from praisonaiagents.context import ContextLedger

ledger = ContextLedger(
    system_prompt=500,
    rules=100,
    skills=200,
    memory=300,
    tools_schema=1000,
    history=5000,
    tool_outputs=2000,
    buffer=500,
)

# Get total
total = ledger.total  # 9600

# Convert to dict
data = ledger.to_dict()

​
Multi-Agent Ledger

For multi-agent scenarios, use MultiAgentLedger for per-agent isolation: 
from praisonaiagents.context import MultiAgentLedger

multi_ledger = MultiAgentLedger()

# Get ledger for each agent
researcher = multi_ledger.get_agent_ledger("researcher")
writer = multi_ledger.get_agent_ledger("writer")

# Track independently
researcher.track_system_prompt("You are a researcher.")
writer.track_system_prompt("You are a writer.")

# Get per-agent totals
print(f"Researcher: {researcher.get_total()}")
print(f"Writer: {writer.get_total()}")

# Get combined total
total = multi_ledger.get_combined_total()

​
CLI Usage

# View ledger stats in session
/context stats
Output: 
Token Ledger
────────────────────────────────
System Prompt:     1,250 tokens
Rules:               320 tokens
Skills:                0 tokens
Memory:              450 tokens
Tools Schema:      1,800 tokens
History:          45,000 tokens
Tool Outputs:     18,000 tokens
────────────────────────────────
TOTAL:            66,820 tokens

​
Integration with Budgeter

from praisonaiagents.context import ContextBudgeter, ContextLedgerManager

budgeter = ContextBudgeter(model="gpt-4o-mini")
budget = budgeter.allocate()

ledger = ContextLedgerManager()
# ... track segments ...

# Check utilization
current = ledger.get_total()
utilization = budgeter.get_utilization(current)

if utilization > 0.8:
    print("Warning: Approaching context limit!")

​
Best Practices

Split system, history, tools, and retrieval so you know which segment grows fastest.
Compare ledger.get_total() to the budget before calling the LLM on long sessions.
Avoid carrying stale counts when users start a fresh conversation.
Dump ledger state when investigating overflow or unexpected compaction.

Context Budgeter

Set up token budgets

Context Optimizer

Reduce context when over budget