An MCP server providing an append-only, hash-chained evidence ledger for agent actions. Every record is a tamper-evident receipt cryptographically bound to all prior records, persisted as human-readable local state. Deterministic, no LLM. Agents are non-deterministic; their audit trail should not be.
When an autonomous agent acts, you need a record of what it did that cannot be quietly altered afterward. This is that record: an append-only ledger where each entry's hash is computed over the previous entry's hash, forming a chain. Altering any past record breaks every hash after it, so tampering is not just discouraged -- it is detectable, and the exact altered record can be named.
It runs as an MCP server, so any agent can call it as a tool. The evidence lands in a plain JSONL file you can open and read: a complete, ordered, cryptographically linked account of every action.
Hash-chained, like a mini ledger. record_hash = SHA256(prev_hash + canonical_body). The chain is the integrity guarantee. See ADR 0001.
Append-only, enforced by absence. The server exposes append, read, verify -- and deliberately no update and no delete. History can be written and read, never rewritten. See ADR 0002.
Real, human-readable local state. The ledger is JSONL, one record per line, chosen over a binary store so you can cat your own audit trail. If someone edits the file directly, verify catches it -- which is the point.
Deterministic. No LLM anywhere. Hashing, chaining, and verification are pure functions of the records. Nothing here is probabilistic. An evidence ledger that could be talked out of a finding would not be evidence.
Two runnable demos write real ledgers you can inspect:
uv run python specs/demo_basic.py # record agent actions, verify the chain
uv run python specs/demo_tamper.py # edit a record in the file, watch verify catch itdemo_tamper.py writes a clean ledger, changes an access level from read to admin directly in the file, and shows the verifier pinpointing the tampered record. Tamper-evidence, demonstrated rather than asserted.
uv sync --extra mcp
EVIDENCE_LEDGER_PATH=./evidence.ledger.jsonl uv run python -m ledger.serverThe operator sets the ledger path via EVIDENCE_LEDGER_PATH, not the calling agent -- the agent writes evidence, it does not choose where evidence lands.
| Tool | What it does |
|---|---|
append_record |
Record an action, receive a tamper-evident receipt hash |
verify_ledger |
Re-walk the chain; prove integrity or pinpoint the first break |
get_record |
Fetch one record by sequence |
query_ledger |
Filter by actor, action, target, or time range |
ledger_stats |
Counts, head hash, and a live integrity check |
There is no update tool and no delete tool. That is deliberate.
uv run evidence-ledger --path ./evidence.ledger.jsonl append deploy-agent deploy payments-api --details '{"version":"4.2.0"}'
uv run evidence-ledger --path ./evidence.ledger.jsonl verify
uv run evidence-ledger --path ./evidence.ledger.jsonl statsThe agent supplies the semantics (actor, action, target, details). The ledger owns the integrity fields (seq, timestamp, prev_hash, record_hash) -- an agent cannot forge a hash or a sequence number, because it never computes them.
The core is generic -- any actor, any action. An optional layer maps actions onto the governance failure taxonomy shared across the portfolio (deployment authorization, change management, data governance, and so on), so an evidence ledger can be read through a governance lens without the core depending on it.
| Repo | Relationship |
|---|---|
| mcp-governance-gateway | Enforces governance on the write path; this records tamper-evident proof of what happened |
| ai-governance-framework | The replay imperative this ledger operationalizes |
Apache 2.0