// the decision record for AI coding agents
Who decided this, and why?
mnema keeps the answer.
Each agent session opens with the decisions in force, each edit meets the rules for its file, and anyone can check offline that nothing in the record was changed.
A record as a chain of signed blocks: ADR-1 recorded, Keep money as integer cents, hash 1be7…04d9; ADR-1 accepted, by a person, prev 1be7…04d9; rule at a path, src/billing refuses a write, prev 7c21…9e30; edit refused, the agent asks instead, prev 19be…a4c1; then checkpoint signed, verified T1/T2/T4, offline, no key.
An illustration: every event names the hash of the one before it, and every checkpoint is signed.
block 01 · the problem
A choice settled in a chat that ends is a choice nobody can check.
In a chat that ends. The session closes and the reason goes with it.
In one tool's memory. The next agent, on another host, never sees it.
In somebody's head. Nobody can tell who decided it, or if it changed.
mnema writes it down in the repository, next to the code, with its reasons and what was turned down. The record only grows: a change of mind supersedes, it never edits.
block 02 · how it works
Record. Rule. Hand over. Verify.
record
An agent over MCP, or you at the command line, writes a decision with its reasoning and the options turned down.
rule
Accepted, it is in force. Linked to a path, it can govern it, ask for a person there, or refuse a write.
hand over
With the plugin, each session opens with what is in force, and each edit meets the rules for its file.
verify
Every write ends in a signed checkpoint. mnema verify, a second reader in Python, or a page in the browser checks it.
block 03 · two readers, one record
for developers
Your agent remembers why.
Every session opens with the decisions in force, by name and id, on any host you use.
The agent records its own decisions, with what it turned down, and links them to the code they govern.
One command founds the record. Two install the plugin.
for teams
Rules that meet each edit.
A rule addressed at a path can govern it, ask for a person, or refuse a write in the host's editing tools.
Every acceptance is signed and says who made it: a person, or an agent marked as one.
A change of mind supersedes the old decision, so the history of every choice stays readable.
block 04 · measured, not promised
49 Claude Code sessions, under a published pre-registration.
10/10
A rule written only in AGENTS.md was followed, as in CLAUDE.md.
11/11
Decisions the agent recorded through the plugin, linked to the code they govern.
0/12
The same, through the command line alone.
Counts from one model and a handful of tasks, not rates. The pre-registration, the kit and the result.
block 05 · don't take our word for it
This site's own record, checked in your browser.
The page reads the record this project commits and verifies every signature and every link of the chain on your machine. No key and no network are needed.
block 06 · hosts
Any host with an MCP client. More where its hooks allow.
a · the MCP server and rules in a file b · the opening of a session c · a refusal before a write d · a pause for a person
- Claude Code d
- VS Code d
- Copilot CLI d
- Cursor CLI c
- Codex c
- OpenCode c
- Gemini CLI c
- Qwen Code c
- Cursor a
- Antigravity CLI a
- Factory Droid a
- Goose a
block 07 · the honest part
What it proves, and what it does not.
holds
A changed or reordered event breaks the hash chain.
An edit made without the signing key is caught where the signed checkpoints remain.
does not hold
Nothing proves that nothing was removed: the history your git remote keeps is what covers that.
A green verify means nothing verifiable is broken, not that the record is honest.
Tamper-evident, not tamper-proof. The whole table, claim by claim.
block 08 · yours, in your repository
Start a record in a minute.
Apache-2.0. The record lives in .mnema/, committed with your code. No account, and no server of ours.