Beliefs

Track what agents concluded, not just what they stored.

Beliefs are first-class objects in XMDB that capture agent conclusions with full provenance. Every belief links to the context the agent retrieved (via receipts), the claims that supported it, and the confidence level. Beliefs can be queried at any point in time, superseded when updated, or invalidated when proven wrong.

Why beliefs matter

When an AI agent makes a decision, you need to know:

What context did it have? → Receipts
What facts did it rely on? → Claims
What did it conclude? → Beliefs
Was it right? → Invalidation history

XMDB is the only system that tracks all four with cryptographic proof.

Belief structure

bash

{
  "belief_id": "bel_8a3f2c1d",
  "receipt_id": "rcp_4e7b9a2f",
  "conclusion": "User prefers dark mode",
  "reasoning": "Based on explicit statement in conversation",
  "reasoning_hash": "sha256:9f3a...",
  "confidence": 0.92,
  "source_claim_ids": ["clm_1a2b3c", "clm_4d5e6f"],
  "agent_id": "assistant-v1",
  "model": "claude-3",
  "valid_from": "2025-01-16T10:30:00Z",
  "valid_to": null,
  "status": "active"
}

| Field | Description | |-------|-------------| | belief_id | Stable identifier across versions | | receipt_id | The context pack receipt that led to this belief | | conclusion | The belief statement | | reasoning | Summary of why the agent concluded this | | reasoning_hash | SHA256 of reasoning for verification | | confidence | 0.0 to 1.0 | | source_claim_ids | Claims that supported this belief | | agent_id | Which agent formed the belief | | valid_from | When the belief became active | | valid_to | When superseded or invalidated (null if current) | | status | active, superseded, or invalidated |

Creating beliefs

API

bash

curl -X POST "https://api.xmdb.cloud/v1/beliefs?workspace_id=prod&scope_id=project" \
  -H "Authorization: Bearer $XMDB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_id": "rcp_4e7b9a2f",
    "conclusion": "User prefers dark mode",
    "reasoning": "User explicitly stated preference",
    "confidence": 0.92,
    "source_claim_ids": ["clm_1a2b3c"],
    "agent_id": "my-agent"
  }'

CLI

bash

xmdbctl beliefs create --workspace prod --scope project \
  --receipt-id rcp_4e7b9a2f \
  --conclusion "User prefers dark mode" \
  --reasoning "User explicitly stated preference" \
  --confidence 0.92 \
  --agent-id my-agent

Querying beliefs

List active beliefs

bash

# API
curl "https://api.xmdb.cloud/v1/beliefs?workspace_id=prod&scope_id=project"

# CLI
xmdbctl beliefs list --workspace prod --scope project

Point-in-time queries

Query what an agent believed at a specific moment:

bash

# What did the agent believe yesterday?
xmdbctl beliefs list --workspace prod --scope project \
  --as-of "2025-01-15T00:00:00Z"

# Filter by agent
xmdbctl beliefs list --workspace prod --scope project \
  --agent-id my-agent \
  --as-of "2025-01-15T00:00:00Z"

Filter by status

bash

# Only active beliefs (default)
xmdbctl beliefs list --status active

# Only invalidated beliefs
xmdbctl beliefs list --status invalidated

# All beliefs including superseded and invalidated
xmdbctl beliefs list --status all

Superseding beliefs

When an agent updates its conclusion, create a new belief that supersedes the old one:

bash

xmdbctl beliefs create --workspace prod --scope project \
  --receipt-id rcp_new123 \
  --conclusion "User prefers light mode" \
  --reasoning "User changed preference in settings" \
  --confidence 0.95 \
  --supersedes-belief-id bel_8a3f2c1d

The old belief's status becomes superseded and valid_to is set to the new belief's timestamp.

Invalidating beliefs

When a belief is proven wrong by external evidence:

bash

# API
curl -X POST "https://api.xmdb.cloud/v1/beliefs/bel_8a3f2c1d/invalidate?workspace_id=prod&scope_id=project" \
  -H "Authorization: Bearer $XMDB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "User explicitly corrected this assumption",
    "invalidating_claim_ids": ["clm_9x8y7z"]
  }'

# CLI
xmdbctl beliefs invalidate --workspace prod --scope project \
  --belief-id bel_8a3f2c1d \
  --reason "User explicitly corrected this assumption"

Tracking changes

See what beliefs changed between two points in time:

bash

# API
curl "https://api.xmdb.cloud/v1/beliefs/diff?workspace_id=prod&scope_id=project&from=2025-01-01T00:00:00Z&to=2025-01-16T00:00:00Z"

# CLI
xmdbctl beliefs diff --workspace prod --scope project \
  --from "2025-01-01T00:00:00Z" \
  --to "2025-01-16T00:00:00Z"

Response:

bash

{
  "added": [...],      // Beliefs created in this window
  "removed": [...],    // Beliefs invalidated in this window
  "changed": [...]     // Beliefs superseded in this window
}

Best practices

Always link to a receipt — Beliefs should trace back to the context that informed them
Use meaningful confidence scores — Calibrate so 0.9 confidence means ~90% accuracy
Include source claims — Link to the specific claims that supported the conclusion
Invalidate, don't delete — Keep the audit trail intact
Use agent IDs — Track which agent formed which beliefs for debugging

Next Steps

Merkle Proofs — Cryptographic proof for any event
External Anchoring — Third-party timestamp attestation
CLI Reference — All belief commands

Documentation

Beliefs

Why beliefs matter

Belief structure

Creating beliefs

API

CLI

Querying beliefs

List active beliefs

Point-in-time queries

Filter by status

Superseding beliefs

Invalidating beliefs

Tracking changes

Best practices

Next Steps

Ready to add durable memory?