01 · the pain
Three ways agent memory dies
Context dies with the session
Close the window and every decision, dead end and hard-won fix is gone. Tomorrow starts from zero.
Discipline doesn’t survive the heat of work
Notes-on-request assume the agent pauses mid-task to go look. It doesn’t. Reminders lose to the next compile error.
Notes rot as code moves
A note about a file that no longer exists is worse than no note. Untended memory turns into misdirection.
02 · the shift
Memory as a pipeline step, not agent discipline
mneme doesn’t ask the agent to be diligent. The engine compiles a recall bundle and delivers it when a phase starts; when the phase closes, what was learned is harvested and staged. Memory stops being a habit and becomes a step that cannot be skipped.
Before: hope
Hope the agent remembers to recall.
# CLAUDE.md, line 42: # "Always check your notes before starting!" # # (three tasks later, under pressure: not checked)
After: delivery
The engine delivers the bundle before work starts.
Recall bundle for phase "vault-unlock": ----- BEGIN MNEME NOTE 8c2f41d7a95b3e60 ----- [decision] Argon2id parameters are frozen: m=64 MiB, t=3, p=4. ----- END MNEME NOTE 8c2f41d7a95b3e60 ----- DIRECTIVE: execute_step
03 · the loop
One phase, five moves
The past reports in
The engine compiles what earlier phases learned and hands it over.
Recall bundle for phase "vault-unlock"
The agent builds
With the bundle already in context — no initiative required.
DIRECTIVE: execute_step attempt: 1
The machine decides
done-when commands run; exit 0 or it isn’t done.
Gate verdict: PASS
[exit-zero]
Learning is distilled
Decisions, fixes and errors become artifacts — automatically staged.
DIRECTIVE: harvest artifacts: 3
You curate
Only what you accept enters the canon.
Accepted note 4e19c7d2;
committed 9f3c1a2
The loop closes: what you accept today argues in tomorrow’s plan.
04 · the human gate
The agent proposes.
You accept.
Every note an agent produces goes to a staging queue, not to memory. You review the queue — accept, reject, supersede — and only accepted notes join the project’s canon. The agent is a scribe. You are the editor.
Nothing enters the canon without your word.
PHASE BOUNDARY: the previous phase is closed and phase "vault-sync" is next and ready.
Staging queue: 3 note(s) awaiting human review.
Its recall bundle compiles when the phase begins, so a note accepted before then is included.
1. [decision] Argon2id costs frozen; conformance vectors are the contract
anchors: src/crypto/kdf.ts
2. [bugfix] zeroize passphrase buffers before dealloc on the Swift side
anchors: apple/Sources/Vault/Unlock.swift
3. [pattern] property-test both directions of every codec pair
1 — accept all ← recommended: all three anchor to files this phase touched
2 — review one by one
3 — reject all
4 — decide later
staging is a queue, not an ultimatum — nothing is written until you answer05 · executable gates
Done means the gate says so
A phase’s done-when is a list of commands, not a paragraph of intent. When the final step reports success, the engine runs them. The machine’s verdict overrides the agent’s opinion — a red gate flips the outcome and issues a retry, with the failure in hand.
Green means the command exited zero — not that the agent felt confident.
Gate verdict for vault-unlock/implement (attempt 1): FAIL
PASS unlock path uses the frozen KDF parameters [exit-zero]
FAIL vault locks after five failed attempts [exit-nonzero]
agent-judged verdicts: 0 of 2 criteria
DIRECTIVE: execute_step
phase: vault-unlock
step: implement
attempt: 2Gate verdict for vault-unlock/implement (attempt 2): PASS
PASS unlock path uses the frozen KDF parameters [exit-zero]
PASS vault locks after five failed attempts [exit-zero]
agent-judged verdicts: 0 of 2 criteria06 · memory mechanics
Recall that earns its rank
fts + cosine, local
Full-text search fused with cosine similarity from a local embedder via Ollama. Recall runs entirely on your machine. Full-text works immediately; the local embedder is an upgrade, not a requirement.
anchors + git staleness
Notes anchor to files. When an anchor’s file dies, the note sinks in ranking instead of misleading you.
four note types
decision · bugfix · antipattern · pattern — each ranked and rendered by what it is, not one amorphous blob.
branch-scoped runs
A workflow run binds to its git branch. Resume picks up exactly where that branch stands — no cross-contamination.
dedup with visible reasons
Near-duplicates surface with the neighbor and the similarity shown. You see why — then you decide.
generalized notes don’t rot
Pattern and antipattern notes are exempt from anchor staleness: generalized knowledge outlives its example file and keeps its rank.
---
id: "4e19c7d2-88a3-4f10-9d42-b7c5e01a2f36"
type: "decision"
anchors: ["src/crypto/kdf.ts"]
commit: "9f3c1a2e07b44d5f8a6c0d1b2e3f4a5b6c7d8e9f"
created: "2026-07-18T09:51:18.240Z"
---
Argon2id parameters are frozen: m=64 MiB, t=3, p=4. The TypeScript and
Swift sides must agree byte-for-byte — conformance vectors live in
tests/conformance/ and are the contract. Treat any KDF edit as a
breaking migration: changing costs invalidates every existing vault.Notes are plain files in a git repo of their own — diffable, reviewable, portable. Every accepted note is a commit: the canon has a history you can read, revert and back up, and none of it touches your project’s tree.
07 · the engine
Built like a database, not a chatbot
Append-only log, deterministic replay, resume from any session.
- Phase graphsPhases declare dependencies; the reducer runs whatever is ready. You write the graph, the engine orders the work.
- Until boundaries“Phases 1–2 today, 3–5 tomorrow.” A planned stop, not an interruption — the run stays resumable.
- Lazy recallThe bundle compiles when a phase starts — so an acceptance window sits between phases, and what you accept now makes the next bundle.
- Event-sourced stateRun state is a fold over the log. Any session can rebuild it exactly; nothing lives in anyone’s head.
{"type":"workflow_run_started","run_id":"3f6a92c1-4b8e-47d2-9c15-a2e07d5b8f41","branch":"feature/unlock","ts":"2026-07-18T09:12:04.118Z","mneme_version":"0.1.6","schema_version":10}
{"type":"recall","query":"vault-unlock kdf passphrase attempts","returned_ids":["8b1f0c2d-5e47-4a19-9c3b-6d2e8f4a7b50","c7a92e14-3f68-4b05-8d1a-92c4e6b7f3d8"],"degraded":false,"origin":"workflow-step","ts":"2026-07-18T09:12:04.564Z","mneme_version":"0.1.6","schema_version":10}
{"type":"workflow_step_applied","run_id":"3f6a92c1-4b8e-47d2-9c15-a2e07d5b8f41","phase_id":"vault-unlock","step_id":"implement","attempt":2,"result_kind":"execute_step","outcome":"success","ts":"2026-07-18T09:47:31.902Z","mneme_version":"0.1.6","schema_version":10}
{"type":"workflow_step_applied","run_id":"3f6a92c1-4b8e-47d2-9c15-a2e07d5b8f41","phase_id":"vault-unlock","result_kind":"harvest","harvested_n":3,"ts":"2026-07-18T09:48:02.677Z","mneme_version":"0.1.6","schema_version":10}
{"type":"staging_resolve","note_id":"4e19c7d2-88a3-4f10-9d42-b7c5e01a2f36","decision":"accept","commit":"9f3c1a2e07b44d5f8a6c0d1b2e3f4a5b6c7d8e9f","ts":"2026-07-18T09:51:18.240Z","mneme_version":"0.1.6","schema_version":10}Every run is a sequence of events like these. Replay folds them back into the exact same state — which is what makes branch-scoped resume safe.
08 · the skills
Eight verbs, one cycle
/mneme:setup
One checkup per repo: diagnose the wiring, fix by digit consent, first note through the gate. Works before any embedder.
/mneme:grill
Question by question until the unstated decisions surface — a protocol file for planning. It never proposes options.
/mneme:arch
Read-only analysis: options, trade-offs, a recommendation. It never edits.
/mneme:plan
A fan of options, your pick, a reviewed delta-spec — migrated into runnable phases.
/mneme:fix
A red repro test, a minimized cause, a one-phase spec whose gate is the regression test. It never fixes code itself.
/mneme:migrate
An external spec becomes phase files with executable gates. Dry-run first, always.
/mneme:dev
Drives the engine phase by phase, gate by gate, boundary by boundary.
/mneme:resume
Where the run stands — closed, ready, blocked — then it stops. Look before you act.
A full cycle from a task in words to shipped code — with a human at every decision point.
09 · why not claude.md
Why not just CLAUDE.md?
CLAUDE.md holds what you sit down and write. Built-in auto memory writes notes for you — and a compressor that paraphrases will sometimes record a discarded idea as a decision, then hand it to your next session as fact.
mneme moves the gate: the agent proposes, you accept. Nothing reaches recall that you did not sign. Notes anchor to real files, so stale knowledge sinks instead of quietly outliving the code. Every retrieval logs its candidates, so ranking is auditable — and replayable — offline.
And the memory is delivered by an engine, not by discipline: the bundle arrives when a phase starts, the harvest is staged when it closes.
What it costs. The bundle is token-budgeted, not a dump: recall fuses full-text and vector search, ranks, and stops at the budget. Stale notes sink by their anchors instead of crowding the window, and the corpus itself never travels — only the handful of notes a phase earns.
When you don’t need mneme. Short, well-scoped work where pointing the agent at the right files is enough, or a project whose conventions fit in a CLAUDE.md you keep tidy. Memory layers earn their keep on long, exploratory work — where the expensive knowledge is the dead ends, the rejected options and the reasons, and re-deriving them costs more than curating them.
10 · proof
mneme built itself
The engine was developed through its own runs: every phase of mneme planned, gated and harvested by mneme. The first product built on top went from an empty repo to hardening in two days.
tests in the engine suite
first product: a password manager, TypeScript + Swift
empty repo → hardening, byte-for-byte crypto conformance
11 · the trust boundary
The trust boundary
The server speaks stdio — no HTTP surface, no auth to misconfigure, no port to leave open. Writes are confined to the corpus under ~/.mneme. Note bodies are sanitised fail-closed on the way in and on the way into a bundle, and every bundle carries a framing line telling the model that what follows is retrieved data, never instructions. Stored text that reaches a model is text a human accepted and the server re-checked.
12 · quickstart
Three moves to a canon
# 1 · install the plugin (marketplace add + install — see the README)
/plugin install mneme
# 2 · one-time checkup — diagnose the wiring, fix by digit consent, first note through the gate
/mneme:setup
# 3 · plan your first task — options, your pick, spec, phases
/mneme:plan "add rate limiting to the unlock flow"Full install and configuration live in the README.