Ledger

What the Ledger Records

Every belief mutation is recorded in an append-only ledger. Each entry captures what changed, who changed it, the state before and after, and a human-readable explanation of why.

No mutation happens without a ledger entry. This is the system's institutional memory: how every belief got to where it is.

Querying the Ledger

Use beliefs.trace() to inspect belief history:

1const history = await beliefs.trace('claim_market_size')
2
3for (const entry of history) {
4  console.log(`${entry.timestamp} | ${entry.action}`)
5  console.log(`  agent: ${entry.agent}`)
6  if (entry.confidence) {
7    console.log(`  confidence: ${entry.confidence.before} → ${entry.confidence.after}`)
8  }
9  if (entry.reason) {
10    console.log(`  reason: ${entry.reason}`)
11  }
12}

You can filter by belief ID, agent ID, time range, or limit the number of entries returned.

Use Cases

Debugging confidence

Why does the agent believe the market is $4.2B with 72% confidence? Trace back through the ledger: created at 85% from a Gartner citation, dropped to 72% when an SEC filing contradicted it, scoped narrower after investigation. Every shift has a recorded reason.

Calibration

Compare predicted confidence with actual outcomes over time. The ledger gives you the full history: how confident the system was at each point and what evidence drove the changes. This is the foundation for evaluating whether the system's confidence is well-calibrated.

Compliance and audit

Every belief that influenced a decision is traceable. Who submitted the evidence? When? What was the confidence before and after? The ledger answers all of these for domains where auditability matters.

Example: Tracing a Claim

Three entries. The full story of how a claim evolved from creation through contradiction to resolution, with every piece of evidence and reasoning recorded.