Praison AI

Context Ledger

Per-segment token accounting for context management

Diagram

Context Ledger

📋 User Request

⚙️ Context Ledger

✅ Result

Diagram
Context LedgerAgentUserContext LedgerAgentUserRequestProcess requestResultResponse
python
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.

Diagram

Context Ledger

📝 Segments

🧠 Track Tokens

🤖 Agent

✅ Budget Report

How It Works

Diagram
LedgerAgentUserLedgerAgentUserSend messagetrack_history / track_system_promptPer-segment token totalsResponse within budget

Quick Start

  1. Create a ledger
    python
    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
    bash
    /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

python
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

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

python
# Reset all counts
ledger.reset()

# Reset specific segment
ledger.reset_history()

ContextLedger Data Class

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

python
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

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

python
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

Track by segment type

Split system, history, tools, and retrieval so you know which segment grows fastest.

Check utilisation each turn

Compare ledger.get_total() to the budget before calling the LLM on long sessions.

Reset ledger on new sessions

Avoid carrying stale counts when users start a fresh conversation.

Export for post-mortems

Dump ledger state when investigating overflow or unexpected compaction.

Related

Context Budgeter

Set up token budgets

 Context Optimizer

Reduce context when over budget