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.

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/
mnema decision record "Keep money as integer cents" "Float sums drift; cents are exact."
mnema decision move accept ADR-1 --note "Agreed in review."   # a decision enters proposed; accepting puts it in force
mnema link ADR-1 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-1 names the first decision of a new record. To hand the record to an agent, install the plugin for your host; in Claude Code:

claude plugin marketplace add felipesauer/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 of them, and mnema instructions --remove takes them out. The first record, step by step, is Your first record.

How it works

1. 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.
2. 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.
3. 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.
4. 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

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 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

• Use. Install · Hosts · Your first record · How it works · What a session is handed · Features · Switches · The command reference · Where it fits · mnema next to a folder of ADRs · Glossary
• Verify. What it proves · How each claim is held · Windows and macOS · Where a rule arrives · Verify without installing · The page that verifies itself · When two machines disagree · The record format
• Integrate. Packages · SDK · GitHub Action · VS Code extension · Stacks · The plugin · Porting it to a host
• Contribute. Contributing · Build from source · Security policy · Changelog

License

Apache-2.0. See LICENSE and NOTICE.