An accountability ledger for agent work. Observations become obligations. Obligations require evidence. Evidence is hash-chained, trust-scored, and append-only. State is never stored. It is computed by replaying the ledger.
{"id":"mem_a1b2c3d4","op":"capture","hash":"5173eb47...","prevHash":"00000000...","payload":{"body":"Customer reported checkout fails on empty cart","kind":"observation"}}
{"id":"cmt_e5f6g7h8","op":"commit","hash":"2c7a0154...","prevHash":"5173eb47...","payload":{"body":"Fix empty cart checkout bug","kind":"commitment","source":"mem_a1b2c3d4"}}
{"id":"op_i9j0k1l2","op":"claim","hash":"b238a07f...","prevHash":"2c7a0154...","payload":{"kind":"claim","commitment":"cmt_e5f6g7h8"}}
{"id":"mem_m3n4o5p6","op":"capture","hash":"f7658824...","prevHash":"b238a07f...","payload":{"body":"Fixed null check in cart.ts:42","kind":"evidence"}}
{"id":"op_q7r8s9t0","op":"submit","hash":"389f98fe...","prevHash":"f7658824...","payload":{"kind":"submission","commitment":"cmt_e5f6g7h8","evidence":"mem_m3n4o5p6"}}
{"id":"op_u1v2w3x4","op":"approve","hash":"c7fa6811...","prevHash":"389f98fe...","payload":{"kind":"approval","commitment":"cmt_e5f6g7h8"},"trust":{"confidence":0.95,"verification":"human_verified"}}Those hash prefixes are the real ones from examples/sample-ledger.jsonl. Payloads are abbreviated here; the file carries the full rows.
Six signals. One unbroken hash chain. Observation → obligation → claim → evidence → submission → approval. That's the whole protocol.
This repository is the specification, not an implementation. It holds the specs, an agent instruction template, a sample ledger, and a reference verifier. It is for anyone building an agent framework, a ledger, or a trust model who wants agent work to close against evidence rather than assertion.
Verify the sample chain in one command. Python 3 is the only requirement:
git clone https://github.com/mentu-ai/commitment-protocol && cd commitment-protocol
python3 tools/verify_ledger.py examples/sample-ledger.jsonlFor a working CLI, see Agent Workflow below.
- Commitments trace to observations. Every obligation has an origin.
- Closure requires evidence. Proving done, not marking done.
- Append-only, hash-chained. Nothing edited. Nothing deleted. Every entry carries the hash of the one before it.
| You are | Start here |
|---|---|
| Building an agent framework | Protocol Spec: nine operations, state machine, Merkle chain |
| Implementing a ledger | Ledger Format: signal schema, hash computation algorithm |
| Adding trust scoring | Trust Spec: seven-weight model, three confidence values, decay |
| Orchestrating multi-step work | Execution Algebra: ten composable primitives |
| Teaching an agent the protocol | Agent Instructions: drop-in template for any AI agent |
| Exploring by example | Sample Ledger: six signals with real SHA-256 hashes |
Everything in the ledger is an EpistemicSignal. Observations, commitments, evidence, approvals. One type, one schema, one chain.
{
"id": "mem_a1b2c3d4",
"op": "capture",
"ts": "2026-04-02T10:30:00Z",
"actor": "human:rashid",
"workspace": "my-project",
"hash": "<sha256 of this signal>",
"prevHash": "<hash of the signal before it>",
"payload": {
"body": "Customer reported checkout fails on empty cart",
"kind": "observation"
},
"semantic": { "entities": ["checkout"], "domain": ["bug"] },
"trust": { "confidence": 0.85, "verification": "machine_verified" },
"trace": { "parent": [], "causalDepth": 0 },
"relations": [],
"observationLevel": "explicit"
}The block above shows the full field set. id, op, ts, actor,
workspace, hash, prevHash, and payload.body are required. semantic,
trust, trace, and relations are optional and are omitted when unused. For
rows whose hashes you can recompute yourself, read the sample ledger.
LEDGER.md carries the field-by-field table.
| Operation | What it does |
|---|---|
capture |
Record an observation |
commit |
Create an obligation from an observation |
claim |
Take responsibility |
release |
Give it back |
close |
Resolve with evidence |
submit |
Request closure, entering in_review |
approve |
Accept a submission |
reopen |
Reject, returning to claimed |
annotate |
Attach a note to any signal |
State machine:
open ──claim──▶ claimed ──submit──▶ in_review ──approve──▶ closed
▲ │ │
└──release───────┘ │
└──────────────────────reopen──────────┘
Trust is computed from observation, never self-reported. Seven weighted signals (exit code, test pass rate, context utilization, completion detection, duration, error state, evidence depth) produce a confidence score between 0 and 1.
Three values track how trust evolves:
| Value | Lifecycle |
|---|---|
| Asserted | Frozen at creation. What the mechanical model computed. |
| Effective | Evolves. Citations increase it. Contradictions decrease it. |
| Current | Read-time only. Effective × temporal decay. Never stored. |
Evidence fades: 2^(−age_days / half_life_days). A 90-day-old signal at half-life retains 50% confidence. Fresh evidence always weighs more.
Ten composable primitives. Each one accepts an intent, produces evidence, and records both to the ledger.
| Primitive | Signature |
|---|---|
| Step | S: (Intent, Context) → (Evidence, Trust) |
| Formula | fold(S₁, S₂, …, Sₙ): ordered steps, knowledge accumulates |
| Pipeline | F₁ ; F₂ ; … ; Fₙ: sequential formulas, conditional routing |
| Parallel | ‖{F₁, F₂, …, Fₙ}: concurrent, isolated |
| Compound | G = (V, E): dependency graph, topological execution |
| Adversarial | A(F_blue, F_red): Blue defends, Red attacks, trust adjusts |
| Convergent | C({F₁…Fₙ}, σ): N strategies, selector picks the winner |
| Temporal | Scheduled execution with evidence TTL |
| Sentinel | Continuous monitoring with progressive escalation |
| Substrate | Meta-operations on trust weights and configuration |
They form a closed algebra. Any primitive embeds any other without modification. A step runs identically alone or inside a 200-step compound.
Full execution specification →
Every signal carries the SHA-256 hash of the one before it. The genesis signal links to 64 zeros. A signal's own hash covers its content but not that link, so what a verifier can establish about order is which rows the chain places, and it says so (LEDGER.md §Verdict and coverage).
import hashlib, json
def compute_hash(signal):
obj = dict(signal)
obj["hash"] = "" # keys are retained and zeroed, not removed
obj["prevHash"] = ""
canonical = json.dumps(obj, sort_keys=True, separators=(",", ":"))
canonical = canonical.replace("/", "\\/") # Swift JSONEncoder escapes slashes
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()Both details matter. Dropping the two keys instead of zeroing them, or leaving forward slashes unescaped, produces a different digest for every signal.
The sample ledger ships with real hashes, and tools/verify_ledger.py is the reference verifier:
python3 tools/verify_ledger.py examples/sample-ledger.jsonlIt recomputes every content hash, places every hashed row on the chain, and
returns verified (exit 0), failed (exit 1: a mismatch, a missing ancestor,
or a post-cutover unhashed row) or incomplete (exit 2: rows the chain does
not place, which is not a pass). --profile strict also refuses branches. On
the sample ledger it reports 6 of 6 rows on the ancestry, verified.
Any agent that can read a file and run shell commands can follow the protocol. No SDK. No integration. Drop AGENTS.md into the workspace's ledger directory (.mentu/ in Mentu) and the agent knows what to do.
This repository is the specification. mentu is one implementation of it, and
it is what the commands below invoke:
npm install -g mentu
mentu status # read the ledger
mentu claim cmt_e5f6g7h8 # take responsibility
# ... do the work ...
mentu capture "Fixed null check" --kind evidence # record what happened
mentu submit cmt_e5f6g7h8 --evidence mem_xyz789 # submit for reviewThe protocol does not require it. A ledger is JSON Lines and the hash algorithm is a few lines of Python, so any agent that can append to a file can participate.
- Append-only. Signals are never updated or deleted.
- Chain integrity. Every
prevHashresolves to an earlier hashed row, and a verifier states which rows the chain places (LEDGER.md §Verdict and coverage). - Citation gate. Findings must reference their source.
- Mechanical trust. Computed from observation, never self-reported.
- Read before act. Query prior evidence before acting. (recommended)
Full invariant specification →
An implementation chooses where the ledger lives and documents it. Mentu, one implementation, uses:
.mentu/
├── ledger.jsonl # append-only, hash-chained
├── config.yaml # workspace configuration
├── AGENTS.md # agent instruction template
└── genesis.key # constitutional identity (optional)
The ledger is the source of truth. State is always computed by replaying it. Nothing else stores state.
| Spec | What it covers |
|---|---|
| PROTOCOL.md | Nine operations, state machine, signal envelope, conformance |
| LEDGER.md | EpistemicSignal schema, hash algorithm, JSON Lines format |
| TRUST.md | Seven-weight model, three confidences, temporal decay |
| EXECUTION.md | Ten primitives, composition algebra, embedding principle |
| INVARIANTS.md | Five structural guarantees |
| GENESIS.md | Workspace constitution, permissions, trust weights |
| OKF.md | The Open Knowledge Format and the x-mentu extension profile: portable knowledge bundles on the protocol's signal graph |
A substrate for accountable action that isn't itself accountable is a contradiction. The protocol is MIT-licensed, inspectable, auditable, and forkable. If you can improve it, do.
To cite the specification, use CITATION.cff (GitHub shows it as "Cite this repository"). Questions, ambiguities and proposed changes are welcome: see CONTRIBUTING.md. Report a security problem privately, as SECURITY.md describes.
A Merkle-chained ledger where commitments require evidence.