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

# Context Ledger

> Per-segment token accounting for context management

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Context Ledger"
        Request[📋 User Request] --> Process[⚙️ Context Ledger]
        Process --> Result[✅ Result]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Request input
    class Process process
    class Result output
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Context Ledger

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Context Ledger"
        In[📝 Segments] --> Track[🧠 Track Tokens]
        Track --> Agent[🤖 Agent]
        Agent --> Out[✅ Budget Report]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class In input
    class Track process
    class Agent agent
    class Out output
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Ledger

    User->>Agent: Send message
    Agent->>Ledger: track_history / track_system_prompt
    Ledger-->>Agent: Per-segment token totals
    Agent-->>User: Response within budget
```

## Quick Start

<Steps>
  <Step title="Create a ledger">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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()}")
    ```
  </Step>

  <Step title="View stats in chat">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    /context stats
    ```
  </Step>
</Steps>

## 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.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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 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.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

<AccordionGroup>
  <Accordion title="Track by segment type">
    Split system, history, tools, and retrieval so you know which segment grows fastest.
  </Accordion>

  <Accordion title="Check utilisation each turn">
    Compare `ledger.get_total()` to the budget before calling the LLM on long sessions.
  </Accordion>

  <Accordion title="Reset ledger on new sessions">
    Avoid carrying stale counts when users start a fresh conversation.
  </Accordion>

  <Accordion title="Export for post-mortems">
    Dump ledger state when investigating overflow or unexpected compaction.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Context Budgeter" icon="coins" href="/docs/features/context-budgeter">
    Set up token budgets
  </Card>

  <Card title="Context Optimizer" icon="compress" href="/docs/features/optimizer">
    Reduce context when over budget
  </Card>
</CardGroup>