mnemo

mnemo keeps what your Claude Code sessions learned, puts the relevant piece in front of the next prompt, and fans out sessions that start out knowing it.

What that adds over Claude Code's own memory is measured below.

Monday, in your app repo, you tell Claude: "never use npm in this repo, always yarn." You run mnemo learn — or you just end the session and let it happen. Thursday, a new session, you ask Claude to add a dependency: that rule is injected before Claude answers, only when it clearly applies.

What gets injected is the rule's whole body, under a reflex context: header and a • [[use-yarn-not-npm]]: line: a median of about 300 tokens a rule, and never more than 9,000 bytes for the whole block, the most Claude Code reads inline from a hook. A body too long to fit is cut at a line break and ends with its page's path; Claude can call read_mnemo_rule over MCP for the rest, and /mnemo:doctor tells you if that server is not connected. A rule that recurs in two different repos is promoted to universal and follows you everywhere.

Install

Inside Claude Code, type:

/plugin marketplace add xyrlan/mnemo
/plugin install mnemo@mnemo-marketplace

That's the whole thing. No terminal, no Python, no Node — mnemo ships as a self-contained binary that the plugin fetches for your platform on first use. Restart Claude Code, and it's running.

Claude Code deletes transcripts after 30 days unless cleanupPeriodDays says otherwise, and they are what mnemo learns from: add "cleanupPeriodDays": 365 to ~/.claude/settings.json (mnemo init merges it in for you, and mnemo doctor warns while it is missing).

npx @xyrlan/mnemo install              # prompts for global or project scope
npx @xyrlan/mnemo install --yes        # global, no prompts
npx @xyrlan/mnemo install --project --yes

pipx install mnemo-claude    # or: uv tool install mnemo-claude
mnemo init                   # global, or `mnemo init --project`

Check it worked

Correct Claude in your own words, run mnemo learn, read the output, type your next prompt on that subject (the five minutes). Step 3 is the whole feature:

read: ~/.claude/projects/-Users-you-github-app/3f2a….jsonl
briefing: bots/app/briefings/sessions/3f2a….md (1 correction(s))
learned: use-yarn-not-npm — Use yarn, never npm (evidence: "never use npm in this repo, always yarn")
next prompt about this will surface it — check with `mnemo why`

The evidence: quote is your own sentence, carried back to you. A rule with a quote is a rule mnemo can prove you asked for.

Per-prompt recall is silent by design — it injects a rule only when one clearly beats the rest — and /mnemo:why shows each decision with its arithmetic. Silence with a reason is the difference between "my vault has nothing useful" and "my thresholds are a little too tight".

Does an injected rule change the answer?

Yes, when it is on point. On the maintainer's own prompts: 64 (prompt, rule) pairs where a blind rater said the rule applied, each answered twice by the same model, once as typed and once with the rule injected exactly the way the hook injects it, two samples per arm, then scored by a judge that cannot see which arm it is reading:

followed the rule   without it 41.0%   with it 72.1%   (61 pairs judged)
lift                +31.1 pp   95% CI [+19.7, +42.6]

claude-sonnet-5, no tools, tools/measure_rule_lift.py (#434). That measures the rule once it arrives. Whether the right rule arrives is the other half, and it is yours to check: /mnemo:why shows every decision with its arithmetic, and mnemo replay runs your own history through it.

Does it prevent a repeated correction? No, measured. mnemo's promise is that the agent does not repeat a mistake you already corrected. On the maintainer's own history (120 of 265 human sessions, 2026-08-26 → 09-27), two blind raters on different models judged, for every prompt, which rule you had already taught by correcting the agent applied to it. The transcript then showed whether mnemo had put that rule in context, and whether Claude Code's own CLAUDE.md or auto-memory already carried it. Multiplied by the lift above:

relevant corrected rules   0.40 per session          [0.29, 0.51]
delivered, and new          2 of 48   4.2%            [0, 10.3%]
   by channel               SessionStart 12.5%   reflex 0%   MCP 0%
   already in CLAUDE.md / auto-memory                 62.5%
lift                       +31.1 pp                  [+19.7, +42.6]
prevented repeats          0.005 per session         [0, 0.026]    bar: 1 per 15 (0.067)
verdict                    NULL, before the reflex judge went live and after it

The bottleneck is frequency, not delivery: Claude Code's own memory already held most of the corrected rules, so even if mnemo had delivered every one it lacked, the most it could prevent is one repeat per ~21 sessions, under the bar. Counting any vault rule instead of corrected ones gives 0.135 per session [0.070, 0.225], carried mostly by the reflex. That counts answers a rule would change, not mistakes you corrected, and the lift it uses measures whether an answer follows the rule, not whether it is better. mnemo adds a median ~2.2k tokens per session. Reproduce with tools/measure_prevented_repeats.py (#520).

Would a fixed block of rules at session start do better? No, measured. A block holding every rule with a verified correction, sent once at SessionStart, would have delivered 44 of the 46 corrected-rule units a perfect channel could, for 0.056 prevented repeats per session [0.030, 0.087]. Perfect delivery would reach only 0.059, still under the bar (#598). For any relevant rule, not only corrected ones, the lift survives distance: alone at the top of the session, a median of 12 turns before the prompt, a rule lifts the follow rate by +28.3 pp. The block that would carry it does not fit, though: the 15 rules the reflex judge picked in the most earlier sessions have a median of 44.8 KB as whole bodies, five times the 9,000-byte budget (#613). In a compact form they fit a hook entry of their own (p95 7.7 KB), and among the 14 other rules the lift halves:

where the rule sits                       lift       95% CI
beside the prompt (the reflex)            +31.1 pp   [+19.7, +42.6]   #434
alone at session start, ~12 turns back    +28.3 pp   [+15.8, +40.8]   #613
among 14 others, compact                  +14.9 pp   [+2.6, +27.2]    #618
among 14 others, one line each            +12.3 pp   [+0.0, +24.6]    #618

With the diluted lift, the compact block of 15 reaches 0.095 per session, but only through one rule: without it, 0.038, under the bar (#618). A judge reading what the agent did in a turn, instead of the prompt, fared no better: four weeks of history held one correction of a rule the vault already had, so deciding would take about 2.8 years (#599). None of the three was built. Reproduce with tools/measure_settled_block.py, tools/measure_relevance_block.py and tools/measure_action_reviewer.py.

Do those changes make the answer better? Not measurably. The test covered all 265 sessions and the 138 times mnemo put a rule in context that Claude Code's own memory lacked. Each prompt was answered twice, with the rule and without its bytes, and two blind raters who never saw the rule picked the better reply. With the rule, the reply was better 34% of the time, worse 27% and tied 39%. Net help per rule is +0.07 [−0.04, +0.17], which comes to 0.036 helpful changes per session [−0.019, +0.094], about 1 in 28, against the bar of 1 in 15. The result is inconclusive with no sessions left to extend into, so it counts as null. Reproduce with tools/measure_broad_value.py (#527).

Why not? Leads, not findings yet. A zero-model pass over what those two studies left on disk shows three things. Most rule bytes (78%) go to rules no rater found relevant. Of the relevant rules mnemo delivers, 64% are already in CLAUDE.md or auto-memory. And the agent reads the full rule behind a reflex line in 8 of 1,336 cases. The drop after the reflex judge went live is not the judge's: rules the judge never selected dropped more. Each lead is ranked with the cheapest fresh test that would confirm or kill it. Reproduce with tools/measure_memory_panorama.py (#530).

The whole rule helps where the one-line preview did not. Until #542 the reflex injected a 300-character preview of the rule. On #527's reflex units, the same prompts were answered again with the rule's whole body in its place and judged by the same two blind raters against the reply without the rule. Net help rose from −0.02 with the preview to +0.22 with the whole body; the paired difference is +0.24 [+0.09, +0.40] over the 72 units whose rule is unchanged since its session, above the +0.10 bar set before measuring. Both record pages and advice pages help. The reflex has injected the whole body since #542. That reading is on old units, so a fresh check was registered on sessions that ran the change. It was read once, early, and stopped for cost before any answer was judged (#627): 91 fresh sessions hold 100 units, rules both raters call relevant that the reflex delivered whole and Claude Code's own memory lacked, and the effect on them is not measured. Reproduce with tools/measure_full_body.py (#535); the fresh check is tools/measure_full_body_fresh.py (#545).

A session starts with an index of your recent briefings, not the last one whole. Every session that ends writes a briefing. The next session used to get the newest one pasted in whole, a median of 6.3 KB. That was the right briefing for its work in only 17.6% of sessions (#534). A right briefing helps: net help +0.218 [+0.105, +0.327] against none. A wrong one doubles the replies that assume a wrong state of the work (#540). So since #551 a session starts with a [recent-briefings] block: the date and ## TL;DR of the project's ten newest briefings, newest first, a median of about 4.6 KB. SessionEnd still writes each briefing in full. Against no briefing, the index scored +0.109 [+0.005, +0.218]. That is inconclusive against its own bar of +0.15, but it matched or beat the whole newest briefing whether that briefing was the right one (+0.21 vs +0.22) or not (+0.05 vs −0.06), and it did not raise wrong-state replies (5.9% vs 6.8% with none). Reproduce with tools/measure_briefing_index.py (#548). The fresh check on sessions that ran the index was read once, at 89 of the registered 100, and stopped for cost with its second judge partway (#627). Against the whole newest briefing, the index scored +0.208 [+0.079, +0.337] with one judge over all 89 sessions and +0.100 [−0.180, +0.380] with the other over 25, the same direction (κ 0.41), with fewer wrong-state replies on both (5.1% vs 10.1% on the first). That is not the registered verdict, since the two-judge interval over 25 sessions still includes 0, and against no briefing there is no verdict; the index stays. Reproduce with tools/measure_briefing_index_fresh.py. briefings.sessionStart picks index (the default), last or none.

Your own numbers, with a baseline. mnemo replay runs every prompt you typed through the hook's own decision and sorts every rule that would have fired by when the vault learned it. The maintainer's vault, 2026-09-14:

prompts replayed          2107   (219 sessions, 2026-08-03 → 2026-09-14)
rules in the vault        1830   (78 cite a correction you typed: 18 verified by the evidence gate today, 60 label only)

  reflex would have fired               230   prompts   10.9%
  ├─ rule from an EARLIER session      116   prompts   5.5%  (95% CI 4.6–6.6%)   ← the vault's contribution
  │    citing your own words              0   prompts   0.0%  (95% CI 0.0–0.2%)   verified by the evidence gate today
  │    label only, gate can't check       3   prompts   a `verified` from mnemo reclassify; its briefing has no Corrections to check against
  ├─ rule from this SAME session         24   prompts   hindsight — the vault could not have helped
  └─ rule not learned yet                90   prompts   today's vault fires, but the rule postdates the prompt

not measured: whether an injected rule changed the answer; tokens, session length, or time saved; what CLAUDE.md or auto-memory would have covered instead.

The earlier-session line is the only one the vault can take credit for; a naive replay would claim all three. A rate only once there are enough prompts. "Your own words" is the strongest claim on the page, so it is held to the evidence gate as it stands today: the quote must sit in the ## Corrections of a briefing the rule was built from. A confidence: verified the gate cannot re-check — the 2026-09 mnemo reclassify labels cite briefings written before that section existed — is printed on its own line and never quoted as the number. The block's last line is the replay's own: it cannot see an answer change, which is what the lift above measures.

Every number on this page comes from a command or a script in tools/ you can run, each report stamped with the commit and vault state it ran on and what it could not see, and the design notes and measurement write-ups behind them are in design/.

Day one

A fresh vault has nothing to inject, and mnemo does not go rummaging through your history uninvited. Your first session in a repo with harvestable transcripts prints one line — how many, and roughly what reading them costs — and nothing runs until you say so:

mnemo backfill --dry-run    # exactly what it would read, and what that costs
mnemo backfill              # this repo
mnemo backfill --all        # every project

Backfilled pages are reconstructed rather than observed, so every rule from them lands in shared/_inbox/ for you to read — never auto-promoted into shared/. mnemo inbox lists what's waiting and takes the decision in one command — --promote <key> to keep a page, --drop <key> to throw it away — and mnemo names the oldest of them at session start rather than waiting for you to ask (details).

When you run many sessions

The same vault follows every session mnemo starts for you. Friday there are three issues that could be built at once:

mnemo dispatch 197 198 199    # or /mnemo:dispatch 197 198 199, from inside a session

Each gets a background Claude Code session in its own worktree and branch, handed the issue body and scope limits — never a preferred solution, so a child can refuse a wrong one. The children run under the same hooks you do, and a worktree resolves to the repo it was cut from, so every rule the vault holds for that repo — use yarn, never npm included — is injected into them exactly as it is into you.

Not every issue wants a patch. Some want an answer first:

mnemo dispatch 361 --read-only

That child investigates and posts its finding as a comment on the issue instead of building. Its file-editing tools are closed at spawn — Edit, Write and NotebookEdit, its own subagents included — so habit cannot turn an investigation into a branch. It can still write through the shell if it sets out to, which is why it keeps a worktree of its own: the restriction is there to prevent drift, not to contain a child that means to build. It publishes nothing, so --may is refused alongside it.

mnemo sessions is the queue. Blocked on a human comes first, because nothing happens there until you act:

WAITING ON YOU (1)
  a41c8e2f  #196 queue liveness                   4m  Which of the two should own the hint?

WORKING (2)
  13b6f4f3  #207 sessions docs                 Read docs/getting-started.md (+31)    9k
  3a14bdd9  #206 label column                  Bash pytest -q (+12) ↻                7k

DONE (1)
  7c1e9a04  #205 unblock consumer              #199                                 22k

  attach: claude attach a41c8e2f

Attach, answer the question, detach. That answer is a correction, and mnemo treats it as one: the SessionEnd hook runs mnemo sessions --consume-unblocks, which learns from what you told the blocked child the way mnemo learn does, so the next child to hit the same fork already has your answer. A child ends itself: it reports, opens its own pull request when git says there is something to publish, and stops — and only a stopped child fires SessionEnd, which is where its briefing is written. A report that cannot reach its parent, because the parent restarted or was busy, is held, and the parent's next prompt shows it, exactly once. If that PR then goes red, gets a review or conflicts with its base, mnemo wakes the child to deal with it, a bounded number of times, and hands it back to you after that. The merge is yours — unless you name the repository in dispatch.autoMerge.repos, and then the same watcher merges the PR once it is open, mergeable and every check has passed: squash, pinned to the head it read, never --admin, never a twin or a contract piece, and not a merge queue (details). Dispatch it with --may none and it publishes nothing; then it is delivered by name — mnemo deliver 7c1e pushes its branch and opens the pull request, Closes #205 included — and naming it is the approval; no flag approves them all.

To see how far apart two runs of one issue land, mnemo dispatch 449 --twins starts two children with the same prompt, byte for byte, from the same commit, neither told of the other, neither publishing, and both with Claude Code's auto-memory off. mnemo twins show <pair> prints their diffs, each with its closing report, as A and B in a drawn order, mnemo twins prefer <pair> A|B|tie records which you would merge and only then says which was which, and you deliver the one you chose. Only a delivered twin writes a briefing: the other's work never shipped, so it teaches the vault nothing. tools/measure_child_pairs.py reads the pairs back, and --exclude human-input leaves out a pair where you answered one twin and not the other.

When the unit of work is a feature rather than issues, ask any session to "decompose this for dispatch": the decomposing-for-dispatch skill writes a contract — the pieces, the files each may touch, the signatures each exposes and consumes — and mnemo dispatch --contract <path> spawns one child per piece. mnemo land <contract> is the last metre: every piece in landing order, owners before consumers, and whether each promised signature actually exists on its branch:

contract dispatch-last-metre (3 pieces, in landing order)
  1. delivery            feat/dispatch-last-metre/delivery  [origin/feat/dispatch-last-metre/delivery]
       PR: https://github.com/xyrlan/mnemo/pull/219 (MERGED)
       exposes  ✓ `ready(worktree, *, repo_root) -> Readiness`
       exposes  ✓ `pr_for(branch, *, repo_root) -> str | None`
  2. contract-discovery  feat/dispatch-last-metre/contract-discovery  [origin/feat/dispatch-last-metre/contract-discovery]
       PR: https://github.com/xyrlan/mnemo/pull/220 (MERGED)
  3. watch-modes         feat/dispatch-last-metre/watch-modes  [origin/feat/dispatch-last-metre/watch-modes]
       PR: https://github.com/xyrlan/mnemo/pull/221 (MERGED)

  all landed — nothing to do

--merge rehearses the sequence in a throwaway worktree — merge, check the signatures, run the suite, next piece — and only then runs gh pr merge in the same order. Neither the queue nor dispatch ever reaches Claude on its own: no hook and no MCP tool exposes them, because a parent's context is the thing they exist to save. Both forms, every flag: docs/getting-started.md.

How it compares

CLAUDE.md — you write it and prune it by hand, and it is loaded whole, every session, whether or not any of it is relevant to what you're doing.

Claude Code auto memory — Claude writes it for you, but only the head of the index loads every session (200 lines as of 2026-09) and the rest is silently dropped. Nothing is ranked against the prompt in front of you.

claude --bg by hand — Claude Code runs a session in the background for you, and then you have six of them: in whatever directory each was started, with no view of which one is waiting for a human, and nothing that pushes a finished one or merges them in the order their dependencies require.

ai-memory — a memory server a whole team's agents point at, across 20+ agent tools and machines, injected once at session start with no LLM call on its default path: cheaper and broader than mnemo. Its published numbers measure retrieval, not whether a recalled memory changes the answer. Neither project has shown, end to end, that the agent makes fewer mistakes. Seven of mnemo's fixes came out of reading it (#591–#597).

mnemo — learns from your corrections and keeps a verifiable quote of what you actually said. Rules it can't verify stay staged for your review instead of entering the vault. Then it injects at most two rules per prompt — usually one — chosen by BM25F against the prompt text. No database, no daemon, and no per-prompt LLM call unless you turn on the judge. Claude Code holds your first prompt until SessionStart returns; on a 10,000-page vault that takes 0.65 s at the median and 1.3 s at p95, and every hook declares a timeout set from measured durations (#610). Dispatch gives every child a worktree and a branch, the queue puts the blocked ones first, each child inherits the vault, deliver and land finish the job, and what you answer at a blocked child goes back in.

Commands

/mnemo:status   vault state + hook health
/mnemo:why      why per-prompt recall fired, or didn't, on your last prompts
/mnemo:doctor   full diagnostic with actionable fixes
/mnemo:learn    learn from this session now
/mnemo:dispatch spawn a background child per issue, or per piece of a contract
/mnemo:help     list commands

mnemo inbox     pages extraction staged for review: promote one, or drop it
mnemo sessions  the queue: blocked first, then what each running child is doing
mnemo deliver   push a finished child's branch and open its PR
mnemo resume    wake the children the account's limit stopped, once it has reset
mnemo land      a dispatched contract's pieces in landing order; --merge lands them
mnemo replay    your transcripts against your vault: what would have come back, and from when
mnemo stale     live rules citing a file this repo no longer has, and where it moved to
mnemo sync      one vault on two of your own machines, through a private git remote (off until `sync init`)

Your rules are yours. mnemo export writes the ones for the repo you're in to .claude/rules/mnemo.md — a plain file Claude Code loads by itself, one lead sentence and your own quote per rule (--full for whole bodies) — so a teammate without mnemo gets them too, and leaving mnemo costs you nothing. mnemo init --host cursor (or codex) registers the MCP server there and mnemo export --host cursor writes the rules where that tool looks.

Rules can also travel between vaults, through the repo. mnemo publish writes the rules for the repo you're in to .mnemo-shared/<type>/<slug>.md — your quote kept, your vault paths dropped, an opaque vault id as provenance and never a name or an email — for you to commit like any other file. A teammate runs mnemo import: every rule is staged in their shared/_inbox/ for review, never promoted, marked as another contributor's words rather than their own, and a rerun brings only what changed. mnemo status says when the published tree is behind your vault.

Everything else is a CLI subcommand (mnemo help --all): mnemo open, mnemo fix, mnemo backfill, mnemo reclassify, mnemo autopilot, and the rest. The status line (mnemo · 9 topics · 7↓ today, plus N esperando while children wait on you) is opt-in, since plugins can't set one: mnemo statusline --install.

Uninstall with /plugin uninstall mnemo. The vault is always preserved.

Docs

• Getting started — the deeper tour: every install path, where things live, the dispatch loop end to end, the autopilot
• Configuration — every knob in mnemo.config.json
• Troubleshooting — when something looks wrong
• Obsidian — optional: browse the vault as a graph
• Design notes — how it was decided and measured, built in the open
• Privacy — what stays on your machine, and the three opt-in switches that send anything, and what mnemo sync publishes once you run it

Privacy

Local by default. Three switches can make a network call, all off until you turn them on: autopilot.network.enabled; recall.rerank.provider, which sends the query of a list_rules_by_topic call and the first 800 characters of each rule in that topic to a third-party ranking model (what is sent, and why); and reflex.judge.provider, which sends the text of the prompts you type — the first 1,200 characters, whenever per-prompt retrieval finds candidates — plus up to three candidate rules, to the same model, from inside the UserPromptSubmit hook (what is sent, and why). That last one is the only thing mnemo can send that you did not type into a tool call on purpose, so it has its own consent (asked separately at the end of mnemo rerank --setup, or later with mnemo rerank --reflex on) and mnemo rerank --off turns it off along with everything else. Both replace secrets with [redacted] before the prompt or query leaves — API keys and tokens, JWTs, private keys, passwords in URLs, *_TOKEN=-style assignments — the judge before its 1,200-character cut, so no piece of a secret straddling it gets out, and the same pass runs on what mnemo writes into the vault. mnemo sync is not a switch but a command, and nothing runs it for you: until you type mnemo sync init or mnemo sync join, no part of the vault goes anywhere. Once you have, the hooks pull before a session starts and push what a session wrote, and push sends your rule pages, briefings, mirrored memory, extraction state and HOME.md to the one git remote you named, through your own git — never logs, indexes, telemetry or the config — and refuses while any file it would publish holds a secret shape (exactly what leaves, and where it goes). If <vault>/.mnemo/private-names.tsv lists names (name<TAB>alias), a git push or gh command that would publish one outside a private repo is denied, and the message gives the alias. No third-party Python dependencies. Every piece of telemetry (.mnemo/*.jsonl) stays on disk. LLM calls go through the claude CLI you already have — one per session for the briefing, one per ten new files at extraction time — never on the prompt path. Logs are capped at 1 MB; briefings accumulate, one file per session. The one other outbound call is the plugin downloading its binary from GitHub Releases on first use (checksum-verified, and released only from a commit whose CI passed). Read the source.

License

MIT — see LICENSE.