> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Ledger

> Per-segment token accounting for context management

# Context Ledger

The Context Ledger tracks token usage across different context segments, enabling precise budget monitoring and optimization decisions.

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import ContextLedgerManager

# Create ledger
ledger = ContextLedgerManager()

# Track different segments
ledger.track_system_prompt("You are a helpful AI assistant.")
ledger.track_history([
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"},
])

# Get totals
total = ledger.get_total()
print(f"Total tokens: {total}")
```

## Tracked Segments

| Segment         | Description                     |
| --------------- | ------------------------------- |
| `system_prompt` | Agent instructions              |
| `rules`         | Workspace rules (.praisonrules) |
| `skills`        | Skill definitions               |
| `memory`        | Persistent memory context       |
| `tools_schema`  | Tool/function definitions       |
| `history`       | Conversation messages           |
| `tool_outputs`  | Tool call results               |
| `buffer`        | Safety margin                   |

## API Reference

### Track Segments

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Reset all counts
ledger.reset()

# Reset specific segment
ledger.reset_history()
```

## ContextLedger Data Class

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents 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!")
```

## Next Steps

* [Context Budgeter](/docs/features/context-budgeter) - Set up budgets
* [Context Optimizer](/docs/features/context-optimizer) - Reduce when over budget