Observations become obligations. Obligations require evidence. Evidence is hash-chained, trust-scored, and append-only. State is never stored — always computed by replaying the ledger.
{"id":"mem_a1b2c3d4","op":"capture","hash":"bed4c1c8...","prevHash":"0000...","payload":{"body":"Customer reported checkout fails on empty cart","kind":"observation"}}
{"id":"cmt_e5f6g7h8","op":"commit","hash":"56789c80...","prevHash":"bed4c1c8...","payload":{"body":"Fix empty cart checkout bug","source":"mem_a1b2c3d4"}}
{"id":"op_i9j0k1l2","op":"claim","hash":"c491a41c...","prevHash":"56789c80...","payload":{"commitment":"cmt_e5f6g7h8"}}
{"id":"mem_m3n4o5p6","op":"capture","hash":"9b280af3...","prevHash":"c491a41c...","payload":{"body":"Fixed null check in cart.ts:42","kind":"evidence"},"trust":{"confidence":0.85}}
{"id":"op_q7r8s9t0","op":"submit","hash":"815fd202...","prevHash":"9b280af3...","payload":{"commitment":"cmt_e5f6g7h8","evidence":"mem_m3n4o5p6"}}
{"id":"op_u1v2w3x4","op":"approve","hash":"7ddb5ab4...","prevHash":"815fd202...","payload":{"commitment":"cmt_e5f6g7h8"},"trust":{"confidence":0.95,"verification":"human_verified"}}Six signals. One unbroken hash chain. Observation → obligation → claim → evidence → submission → approval. That's the whole protocol.
- 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": "bed4c1c85f6561da...",
"prevHash": "0000000000000000...",
"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"
}| 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 — enters in_review |
approve |
Accept a submission |
reopen |
Reject — back 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. The chain is verifiable end-to-end.
import hashlib, json
def compute_hash(signal):
obj = {k: v for k, v in signal.items() if k not in ("hash", "prevHash")}
canonical = json.dumps(obj, sort_keys=True, separators=(",", ":"))
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()The sample ledger ships with real hashes you can verify.
Any agent that can read a file and run shell commands can follow the protocol. No SDK. No integration. Drop AGENTS.md into .mentu/ and the agent knows what to do.
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 reviewWorks for Claude, GPT, Cursor, Devin, Codex — any agent, today.
- Append-only. Signals are never updated or deleted.
- Merkle integrity. Every
prevHashmatches the priorhash. - 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 →
.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 |
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.
A Merkle-chained ledger where commitments require evidence.