mneme is a "vault-native" memory system designed for Claude Code and the MCP ecosystem. Its core proposition is: Markdown is the single source of truth. Whenever vault content is actually modified during a Claude Code session, the Stop hook atomically appends a timestamped session block to vault/sessions/YYYY-MM-DD.md, including type: session frontmatter. You can open these files directly with a text editor, search them with grep, and manage them with git.
Main capabilities
- Local retrieval: by default it uses SQLite FTS5 BM25 retrieval, injects a preflight block at session start (today's heading, git status summary, the five most recently modified session documents), and the agent can query the index on demand via mneme_search.
- Zero LLM critical path: closing a session does not call any model, official benchmarks show the Stop hook p95 is about 2 milliseconds (with an upper limit set to 1000 milliseconds), and "no network calls on the critical path" is enforced in CI through static and runtime checks.
- Redaction before writing: supports inline redaction within <private> tags and records a SHA256 audit log; apart from the compression LLM that the user actively enables and the optional local Neo4j, it makes no external network calls.
- Ten MCP tools: mneme_search, mneme_recall, mneme_write, mneme_prime, mneme_summarize, mneme_timeline, mneme_propose, mneme_health, mneme_checkpoint_list, mneme_working_set_load. Any MCP-capable client can use all ten tools.
- Claude Code integration: registers six lifecycle hooks (PostToolUse, SessionStart, Stop, PreCompact, SessionEnd, with Codex and Antigravity mapping four of them), and provides three slash commands /mneme:prime, /mneme:recall, /mneme:migrate, and mneme-ptwo skills: rime and mneme-search.
- Retrieval quality is guarded by CI: if a PR causes the nDCG@5 of production FTS5 to drop by more than 0.02 from the locked baseline (0.8006), or Recall@10 to drop by more than 0.05 from 1.00, or fails the out-of-vocabulary negative probe, the build fails. All numbers in the text are labeled as deterministic regression anchors based on a seeded synthetic corpus, not real-world quality measurements.
How to use After installing the plugin and registering the lifecycle hooks, you can use mneme doctor to verify the installation status; see the repository documentation for specific commands. Codex and Antigravity have their own native installation methods, with the Antigravity extension installing to ~/.gemini/extensions/. Other MCP clients (Kimi, Qwen, Cline, Cursor, etc.) connect through an open adapter and only get ten MCP tools, with no lifecycle hooks and no automatic capture. Before upgrading, refer to docs/UPGRADING.md; in-place upgrades without data loss are supported.
Use cases
- When you want to preserve architecture, constraints, and existing decisions each time a session starts from scratch, avoiding repeated explanations.
- When you need to record readable, greppable, portable local work records rather than opaque SQLite binary blobs.
- For teams or individuals who are privacy-sensitive, require data not to leave the local machine, and want redaction before writing.
Limitations and notes
- A true semantic embedding backend is still on the roadmap; the production retrieval path is FTS5 BM25, and the feature-hashing lexical vector backend and RRF fusion in the Python core are used only for testing and synthetic benchmarks, and are not yet connected to the MCP server or installer.
- Full-text summaries and timelines can, under full configuration, add local Graphiti and Neo4j fields that must be explicitly enabled.
- Background AI compression is optional, off by default, and has a monthly cost cap.
- Obsidian is entirely optional; the vault is just a plain Markdown directory and does not require any specific editor or external application; all derived state of mneme is stored in the .mneme directory and will not be indexed by Obsidian.
- Team memory is self-hosted (any git remote, redaction before sharing, optional age end-to-end encryption), and only provides a loopback-address Web console.
- The current status is the 4.1.0 public release; packages, plugins, runtime,references and documentation versions are kept in sync by CI. Some advanced modules (mneme-graph project graph, mneme-code code memory, domain schemas, agent security, read-only console, etc.) are in a gated or separate-package state, and none run on the Stop or critical path.
