mnema is the decision record for AI coding agents.

Who decided this, and why? What was turned down? Has it changed since? When an agent settles a choice in a chat that ends, nothing answers. mnema keeps the answer in the repository.

Your decisions, handed to your agents' sessions and held at the edits they govern: append-only and signed in the repository, and checkable by anyone.

How mnema fits: an agent session opens with the decision in force; a write under the path a rule refuses is denied; a write elsewhere lands; a decision the agent records is signed into the chain in the repository; mnema verify checks the chain

Remember	Enforce	Prove
With the plugin, each agent session opens with the decisions in force, by name and id.	A rule addressed at a path can refuse an agent's write there, or hold it for a person where the host allows.	Every write the product makes ends in a signed checkpoint and is hash-chained; anyone can verify it, even in a browser, and a reader's guarantee runs up to the last checkpoint.

Tamper-evident, not tamper-proof: what is still in the record has not changed since it was signed, and a stranger can check that without your keys and without installing this.

Why · Status · Quick start · How it works · Hosts · Family · Watch it · What it proves · Docs

Why

Your agents settle choices all day: a library, an approach, an option turned down. Those choices usually live in a chat
that ends, in one tool's memory or in somebody's head, where nobody can check who decided them or whether they were
changed since. mnema writes them down in the repository, next to the code, with their reasons and what was turned down.
The record is signed and only grows: a change of mind is a new entry that supersedes the old one, never an edit. Where
the host runs hooks, each session opens with the decisions in force, and anyone can check offline that what it holds
was not changed since it was signed. What is measured, and what is not, is on the evidence page.

Status

On npm. @mnema/code is published: install it with npm i -g @mnema/code (docs/install.md); to run the main branch instead, see Build from source.
In the editor stores. The VS Code extension is on the Visual Studio Marketplace and Open VSX as mnema.mnema, and still needs the mnema command from @mnema/code.
These pages describe the next version (the main branch). What has not reached npm yet is listed under Unreleased in the Changelog.
Node. Requires Node 24.15.0 or a later 24, or 26.0.0 or later.
From a checkout. The GitHub Action and the SDK are not published, and run from a clone of this repository (Packages).

Quick start

npm i -g @mnema/code                              # the binary
cd your-repository
mnema init                                        # founds the record in .mnema/
ADR=$(mnema decision record "Keep money as integer cents" "Float sums drift; cents are exact." | grep -o -m1 'ADR-[0-9]*')
mnema decision move accept "$ADR" --note "Agreed in review."  # a decision enters proposed; accepting puts it in force
mnema link "$ADR" src/billing --rel refuses-a-write            # the rule, addressed at a path
mnema verify   # reads the signed record; one line saying it is intact is the green

No agent has run yet: that is the record, a rule in force, and the proof. ADR holds the number
mnema printed for the decision you just recorded. In fish, whose
syntax differs, the first line is set ADR (mnema decision record ... | grep -o -m1 'ADR-[0-9]*').
To hand the record to an agent, install the plugin for your host; in Claude Code:

claude plugin marketplace add mnema-work/mnema
claude plugin install mnema@mnema

Every other host is in Hosts. mnema init also writes the mnema
instructions into AGENTS.md and the other files agent hosts read, naming each; at a
terminal it first asks which hosts, and shows everything it will write before it writes it, and
mnema instructions --remove takes them out. The first record, step by step, is
Your first record.

How it works

Record, rule, hand over, verify: over a signed, append-only record committed with the code

Record. An agent over MCP, or you at the command line, writes a decision with its reasoning and the options turned down, and a task with its description and a handoff with its brief.
Rule. A person accepts it, or an agent where agent-accepts is on (the default; an agent's acceptance is marked as its own), and mnema link addresses it at a path. The rule can govern that path, ask for a person there, or refuse a write.
Hand over. With the plugin, each session opens with what is in force (in Claude Code, so does each subagent), and each edit meets the rules for its file. In Claude Code, a note of the host's own memory is also copied into this machine's private tree, until you switch that off.
Verify. Every write ends in a signed checkpoint and is hash-chained; a reader's guarantee runs up to the last checkpoint. mnema verify, a second reader in Python, or the page mnema site writes checks it.

More in docs/how-it-works.md; what a session is handed, word for word, is in
docs/agent-hosts.md, and how far each host goes is under Hosts.

Hosts

mnema works with any agent host that has an MCP client, and how much more a host gets depends on
what its hooks allow, one rung at a time: (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.

Host	Rung	What it gets	Install
Claude Code _{Anthropic · terminal and editors}	(d)	MCP server · rules file · opening · refusal · pause · rules at an edit	Plugin
VS Code _{Microsoft · the agent of the editor}	(d)	rules file · refusal · pause _{MCP server · opening: read once}	Plugin
Cursor CLI _{Cursor · command line}	(c)	rules file _{MCP server · opening · refusal: read once}	Plugin
Codex _{OpenAI · command line}	(c)	MCP server · rules file · opening · refusal · rules at an edit	Plugin
Copilot CLI _{GitHub · command line}	(d)	MCP server · rules file · opening · refusal · pause · rules at an edit	Plugin
OpenCode _{Anomaly · command line}	(c)	MCP server · rules file · opening · refusal · rules at an edit	Plugin
Gemini CLI _{Google · command line}	(c)	MCP server · rules file · opening · refusal · rules at an edit	Plugin
Qwen Code _{Qwen · command line}	(c)	MCP server · rules file · opening · refusal · rules at an edit	Plugin
Cursor _{Cursor · editor}	(a)	MCP server · rules file _{documented, not measured}	MCP server
Antigravity CLI _{Google · command line (agy)}	(a)	MCP server · rules file _{documented, not measured}	MCP server
Factory Droid _{Factory · command line}	(a)	MCP server · rules file _{documented, not measured}	MCP server
Goose _{Agentic AI Foundation · desktop and command line}	(a)	MCP server · rules file _{documented, not measured}	MCP server

The logos beside the names of the hosts belong to their owners: Anthropic, Microsoft, Anysphere, GitHub, Inc., Anomaly, Google, the Qwen Code project, Factory and the Goose project. They identify the hosts mnema works with and imply no endorsement, either way. mnema is not theirs. Each file is the vendor's own, unmodified, and its source is listed; a host with no logo, Codex, is shown by its name.

Each cell of the full table, how each one is known (held by a test, read once on a real host, or
documented and not measured), and the notes on each host are in
How each claim is held.

The mnema family

@mnema/code holds the record, and the command line and the MCP server that read and write it. The rest stand around
it. The detail of most of them is in Features; for the rest, the Link column leads to the page that has it.

Product	What it is for	Status	Link
`@mnema/code` _{the core}	The signed, append-only record, with the command line and the MCP server over it.	`npm i -g @mnema/code` (Install).	Package
GitHub Action	On a pull request, comments what the change does to the record and fails the check when it is not signed.	Not published; runs from a clone of this repository.	Package
SDK	A library door to the record, for a program that records, reads and verifies.	Not published; runs from a clone of this repository.	Package
VS Code extension	Shows the rules in force over the open file, the decisions waiting for a judgment and the stacks adopted.	On the Visual Studio Marketplace and Open VSX as `mnema.mnema` (`code --install-extension mnema.mnema`); it runs the `mnema` command, so `@mnema/code` stays a prerequisite.	Package
Stacks	Installs a set of skills and agents from a plan shown whole, and records the adoption as a signed fact.	Commands of `mnema`, not a package of their own; the contract they check against, `@mnema/stacks`, ships with `@mnema/code`.	Stacks
An agent in CI	A pipeline's agent records with a key of its own, so what it records is signed as that agent.	A recipe, not a package.	The recipe
A page that verifies itself	`mnema site` writes one HTML file, and the reader's browser checks it.	A command of `@mnema/code`, not a package.	The page

Watch it

_{The first record: the command line in an empty repository, from init to verify. Recorded from the built binary by recordings/first-record.sh.}	_{A changed word caught: one word of an accepted decision is changed by hand in its file, and mnema verify names the event whose hash no longer matches and exits 1. A cut that takes the newest events together with their checkpoint is not caught: a hash chain shows what changed, never what is gone (what it proves). Recorded from the built binary by recordings/a-tamper-caught.sh.}
_{A write refused: the rule addressed at the path stops an agent's edit there. Recorded from the built binary by recordings/a-write-refused.sh.}	_{A decision superseded: a later call takes its place, the old one leaves the rules the next session is handed (the call that replaced it names it) and stays in the record. Recorded from the built binary by recordings/a-decision-superseded.sh.}
_{At a terminal, mnema alone asks what you want to do here, and its first door opens the console: a session that reads the record and refuses to write. It needs a window at least 80 columns wide and 42 rows tall. Driven through a pseudo-terminal by recordings/console.json.}

A case in the suite runs the scripts again against the built binary and fails when a recording no longer
shows what the binary draws, so none of them can go on showing an older product in silence
(the-recordings-are-what-the-binary-draws.test.ts).

What it is not

Each of these is a choice with a reason, and the reasons are in Where it fits.

Not a semantic memory. Search is by the words written in a record; there are no embeddings.
Not an agent runner. It calls no model and runs no tool for the agent.
Not a copy somewhere else. The committed record travels with the repository, and what you record privately stays on this machine, apart from the notes and the private rules your agent's host receives, when a session opens through the plugin and when the agent asks for them, which the host sends to its model; the witness verbs send a digest out, and with Sigstore the identity too, only when you run them.
Not access control. The gate refuses an illegal move; it does not decide who may write.

What it proves, and what it does not

mnema verify reads the events and the committed public keys of a project's trees (no private
key, no network) and prints each verdict verbatim, naming the level it reached.

What holds. A changed or reordered event breaks the hash chain, and an edit made without the signing key is caught where the signed checkpoints remain; verify --require=signed fails when they were taken out.
What does not hold. Nothing proves that nothing was removed: a hash chain shows what changed, never what is gone, and the history a git remote keeps is what covers omission. A record forged whole under a fresh key verifies clean, a key is not proven to be the person a name says, and the agent named on a fact is the name its client announced, unless an agent key signed it (then the name the record enrolled the key under). An agent key's role and its retirement are facts of the record that holds them: verify crosses a project's trees for a retirement, and a reader of one tree does not. A refusal of a write covers a host's editing tools, not its shell: sed -i on a protected file goes round it.
What a green verify means. That nothing verifiable is broken, not that the record is honest, and the gate protects the shape of a change, not who may make it.

The whole table, claim by claim, is in docs/what-it-proves.md; how each
claim about the agent hosts is held, and which are not held yet, is in docs/evidence.md.

Docs

Get started. Install · Your first record · Hosts
Learn. How it works · What a session is handed ·
Where a rule arrives · What it proves ·
Recording decisions · Rules and the commits that cite them ·
Committing the record · A second machine and your key ·
A record that inherits another ·
Importing the decisions you already wrote ·
Switching off what is handed to a model ·
The session journal and compaction · As an MCP server ·
Features · Where it fits ·
mnema next to a folder of ADRs · Windows and macOS ·
When two machines disagree · Glossary
Reference. Commands · MCP tools · Switches ·
The command reference · The record format · Packages ·
SDK · GitHub Action ·
VS Code extension · Stacks · The plugin ·
Porting it to a host
Project. How each claim is held · The page that verifies itself ·
Verify without installing · What comes next ·
Contributing · Build from source ·
Security policy · Changelog

License

Apache-2.0. See LICENSE and NOTICE.