mneme

- What it stores is a file you can open.When a session has actually changed something in the vault, the Stop hook appends a timestamped## HH:MM sessionblock tovault/sessions/YYYY-MM-DD.mdwithtype: sessionfrontmatter, written atomically under a cross-process lock;mneme index rebuildreconstructs the FTS5 index over every markdown file in the vault, so the database is derived state you can delete.
- Closing a session costs nothing and takes 2 ms."No LLM call on the critical path" is enforced in CI rather than promised in prose.tools/spec_verify.pyparses all six lifecycle hook modules and fails the build on any import of seven network-capable roots (anthropic,openai,requests,httpx,urllib.request,urllib3,aiohttp), andpackages/mneme-cc-plugin/tests/integration/test_c3_no_network.pyre-checks the full transitive import closure of the three hot-path hooks at runtime, where a static scan cannot see. The Stop-hook proxy benchmark measures 2 ms at p95 over 100 sessions against a 1000 ms ceiling:benchmarks/latency/p95_guard.pyenforces that ceiling inside the same path-scoped benchmark workflow described below, andpackages/mneme-cc-plugin/tests/unit/test_stop_performance.pyre-checks it over 100 real Stop calls on every CI run, which carries no path filter.
- Search quality cannot silently degrade.A pull request that drops production-FTS5 nDCG@5 more than 0.02 below the locked baseline (0.8006, reported as 0.801), drops Recall@10 more than 0.05 below 1.00, or fails the out-of-vocabulary negative probe fails the build —benchmarks/retrieval/regression_guard.py, run by.github/workflows/bench.ymlon every pull request and every push tomainthat touchespackages/mneme-core,packages/mneme-mcp,benchmarks/, or the workflow file itself.

Those numbers come from the in-repo benchmark suite, seeded withMNEME_BENCH_SEED=42. Benchmark A uses a 500-document corpus. Benchmark E uses its default 300-document, 30-query fixture. Reproduce withmake bench-all. Both figures above — the 0.801 and the 2 ms — carry the note that governs every figure in this README:

Note:All figures below are deterministic regression anchors computed on a seeded synthetic corpus; they are not real-world quality measurements (see ADR-012).

Retrieval claims follow the reachable path.The productionmneme_searchpath is FTS5 BM25. The Python core contains an experimental feature-hashed lexical-vector backend and an RRF fusion protocol used by unit tests and synthetic benchmarks, but that backend is not wired into the MCP server or installer. Full-profile summarize and timeline can add gated local Graphiti and Neo4j fields. A true semantic embedding backend remains roadmap.

Privacy and network.Inline<private>tag redaction at staging write with SHA256 audit log. Zero outbound network calls except opted-in compression LLM and optional local Neo4j. Compression happens in the background, opt-in, with a cost cap.

Temporal reasoning.The deterministic claim lifecycle (valid-from/to, supersedes, as-of queries, contradiction detection,temporal blameprovenance time-travel) is built in on every profile — pure SQLite, no extra dependency. Graphiti export and LLM claim extraction remain optional and never run on the Stop or critical path.

Context Continuity Engine (opt-in).Checkpoints are plain markdown in the vault, zero-LLM, default off.

Obsidian is fully optional.A vault is simply a plain directory of markdown files. mneme requires no specific editor, no external application, and no Obsidian installation. You can work with your vault usinggrep,git, VS Code, or any text editor. The term "vault" is borrowed convention for a self-contained markdown directory, not a dependency on any particular tool. Because the vault is plain markdown, a user who already uses Obsidian can point it at the same directory and get rendered notes, backlinks, and graph-view navigation over the wikilinks mneme writes. The two tools coexist cleanly: mneme stores all derived state (indexes, staging, audit logs) inside a.mnemedirectory that Obsidian ignores as a dot folder, and mneme's indexer excludes the.obsidiansettings folder from indexing, so neither tool disturbs the other. Obsidian is a convenient viewer and navigator for vault content. It is not part of mneme's capture, indexing, or retrieval path, and it must not be treated as an installation prerequisite.

The MCP server registers nine tools. Every client that speaks MCP gets all nine; lifecycle hooks and automatic capture are a separate layer that only Claude Code, Codex, and Antigravity provide. The authoritative list ispackages/mneme-mcp/src/tool_registry.ts.

Legend:✓built in ·gatedshipped, needs an opt-in dependency or flag ·~partial ·—not available ·n/athe dimension does not apply.

The 3.0 line closed the former gap rows on mneme's own terms. Team memory is self-hosted (any git remote, redaction-before-share, optional age end-to-end encryption) with a loopback-only web console rather than a vendor cloud. Autonomy is policy-graduated: the agent applies operator-allowed low-risk edit classes on its own, every change is journalled for one-command rollback and chained into a tamper-evident HMAC audit log, and durable categories always keep a human in the loop. The default-on session summary is deterministic and zero-LLM — no key, no cost, no latency — with LLM compression as the opt-in richer layer. Localized presets ship for English and Turkish today (claude-mem still leads on raw language count, hence the honest ~). Where a hosted product is genuinely the better fit,docs/COMPETITIVE.mdsays so.

An honest, at-a-glance map of what is shipped today versus what is gated behind optional infrastructure or still on the roadmap.Shippedmeans present in the default install path and covered by CI.Gatedmeans implemented but inactive until you provide the optional dependency or flag.Roadmapmeans designed (often with a seam or protocol already in place) but not yet packaged.

These come from the in-repo benchmark suite, seeded withMNEME_BENCH_SEED=42. Benchmark A uses a 500-document corpus. Benchmark E uses its default 300-document, 30-query fixture. Reproduce withmake bench-all.

Note:All figures below are deterministic regression anchors computed on a seeded synthetic corpus; they are not real-world quality measurements (see ADR-012).

CI regression guards lock the path-scoped benchmark surface. Pull requests touching benchmarked code run the benchmark workflow. Any run that drops production FTS5 Benchmark A nDCG@5 by more than 0.02 or breaches the 1000 ms Stop hook p95 fails the build. The BoW RRF condition is reported only as a lexical-surrogate ablation.

# Lite: FTS5 + Stop hook + privacy redaction + 9 MCP tools (Python + Node only) pipx install mneme-cc-plugin mneme install --profile=lite # Standard: lite plus the standard optional dependency profile. # The normal MCP search path remains FTS5. No --enable-dense installer flag ships. mneme install --profile=standard # Full: standard + gated Graphiti temporal knowledge graph enrichment (Docker + Neo4j) mneme install --profile=full

mneme is Claude-Code-native by origin. Because its retrieval core (mneme-core), its MCP server (mneme-mcp), and its vault contract are client-neutral, mneme also runs inside the OpenAI Codex CLI as an additive layer, with no loss of fidelity.

# Plugin: skills, MCP server, and lifecycle hooks together codex plugin marketplace add OnourImpram/mneme # Or wire just the MCP server into ~/.codex/config.toml mneme install --client=codex

Codex gets the same nine MCP tools, the same two skills, and the same vault. Four of mneme's six registered Claude Code hook events map to native Codex lifecycle events (SessionStart, PostToolUse, Stop, PreCompact), and SessionEnd folds into Stop. UserPromptSubmit has no Codex mapping. Seedocs/CODEX.mdfor the full coverage table and ADR-014 indocs/ARCHITECTURE.mdfor the multi-client design.

Antigravity (Google's agentic IDE) uses the Gemini-CLI extension model, and mneme ships a native extension for it.

This installs themnemeextension into~/.gemini/extensions/, wiring the same nine MCP tools, the same two skills, aGEMINI.mdrules file, and lifecycle hooks (SessionStart, PostToolUse, Stop, PreCompact) that map to the samemneme hook <event>core path Claude Code and Codex use. Because Antigravity exposes a Stop hook, session capture has full native parity.

Any MCP-capable client (Kimi, Qwen, Cline, Cursor, and others) can use mneme through the open adapter. This is the non-native tier: the nine MCP tools are available for the model to call, but there are no lifecycle hooks and no automatic capture.

mneme install --client=mcp --config <path-to-your-clients-mcp-config.json>

mneme merges only its own server entry and leaves every other server in the config untouched. Seedocs/INTEGRATIONS.mdfor the client-tiering details andexamples/for a config snippet and a portable AGENTS.md template.

- 9 MCP tools:mneme_search,mneme_recall,mneme_write,mneme_prime,mneme_summarize,mneme_timeline,mneme_propose,mneme_checkpoint_list,mneme_working_set_load. Default search is FTS5. Full-profile summarize and timeline can add KG fields when the local graph is active.mneme_checkpoint_listandmneme_working_set_loadsupport the Context Continuity Engine (CCE): list available working-set checkpoints and load a checkpoint's salience-ranked items for JIT context re-injection.
- 5 Claude Code hooks:PostToolUse,SessionStart,Stop,PreCompact,SessionEnd.
- 3 slash commands:/mneme:prime,/mneme:recall,/mneme:migrate.
- 2 skills:mneme-prime,mneme-search.
- 7-benchmark suite (make bench-all): retrieval quality (A), Stop/retrieve latency (B), adaptive-context cost (C), claude-mem migration (D), head-to-head adapter (E), LongMemEval (F), CCE compaction-recall (G).
- One-command migration:mneme-migrate migrate-from-claude-memwith tri-state archive flag, idempotent re-run, and a per-run hash-checked rollback manifest.
- Adaptive Context Layer:distill.shell_compress,distill.injection_dedup,distill.adaptive_topk,distill.compressed_format, plusmneme auditfor token reports andmneme audit-logfor redaction audit entries.
- Pattern memory:mneme patterns {store, search, list, show, delete}writing vault-markdown Signal/Action/Outcome documents.
- Trajectory recorder:mneme trajectory {start, step, end, show, list}capturing per-session decision trails undervault/trajectories/.
- Background AI compression (opt-in, default off):mneme compress {enable, disable, status, dry-run, run}with monthly cost cap ledger.

Eight modules extend mneme's core for specialized workloads. All are gated or shipped as separate packages. All ship with redaction-before-store, provenance on every record, and confidence labels on every extracted claim. None runs on the Stop or critical path.

- Project graph(mneme-graph): tree-sitter extraction for Python, JavaScript, and TypeScript; community detection; PR-impact analysis; entity canonicalization.
- Code memory(mneme-code): AGENTS.md procedural parsing, test-output to failure memory, fix-trajectory capture.
- Domain modes: clinical and security-review modes block external extraction and artifact upload at config layer. A user config can never weaken a built-in privacy mode or disable redaction.
- Agent security: capability firewall, data-flow taint tracking, human-approval gate for durable edits, poisoned-vault benchmark.
- Read-only console: self-contained, offline, injection-safe HTML audit report requiring no server.
- Experimental feature-hashed lexical-vector retrieval: a Python-core backend and RRF seam used by tests and synthetic benchmarks. It is not connected to the installer or production MCP search path.
- Temporal extraction + Graphiti export: rule-based claim extraction, valid-from/to lifecycle, supersedes links, and export to a local Graphiti instance. LLM extraction is optional and never on the critical path. Live Neo4j writes are gated on the full Docker + Neo4j profile.
- Connectors(Obsidian local + GitHub injected-transport): opt-in, default off. Redaction runs before every ingest. Revoke by disabling in config.

A credible "best in market" claim requires honest scope acknowledgment.

- No packaged semantic embedding backend, and no installed dense-retrieval user path. The feature-hashed lexical-vector implementation remains an experimental Python API.
- No dense or KG leg insidemneme_search. MCP search is FTS5. KG enrichment is gated to summarize and timeline when local full-profile graph state is active.
- No cloud SaaS option. mneme is local-first by architectural conviction.
- No web-based knowledge graph visual explorer. Planned.
- No multi-user team features with merge-conflict resolution, per-user ACL, or team dashboards. Read-only shared vaults via git remote work today. Full team support is roadmap.

Seedocs/COMPETITIVE.mdfor the full landscape and which tools may suit those needs better.

- docs/ARCHITECTURE.md: design philosophy and the 16 Architecture Decision Records (ADR-001 through ADR-016, with ADR-006 superseded by ADR-015).
- docs/CONSTRAINTS.md: six sacred constraints and how to verify each.
- docs/VAULT.md: vault contract, frontmatter specification, atomic write pattern.
- docs/HOOKS.md: hook integration guide, timing budgets, fail-soft contract.
- docs/MCP.md: tool API reference with JSON schemas and example calls.
- docs/RELEASE.md: GitHub tag, release, and metadata checklist.
- docs/COOKBOOK.md: ten worked recipes with full Claude Code transcripts.
- docs/MIGRATION-FROM-CLAUDE-MEM.md: one-command migration with tri-state archive and hash-checked rollback walkthrough.
- docs/BENCHMARKS.md: methodology and the locked baseline numbers.
- docs/COMPETITIVE.md: living landscape document (monthly refresh).
- docs/PRIVACY.md: outbound network call audit and telemetry policy (zero by default).
- docs/GOVERNANCE.md: maintenance model, release authority, succession.

Apache License 2.0. SeeLICENSEandNOTICE. Releases up to and including the 2.x line were published under MIT and remain so.

Local Markdown/Obsidian knowledge substrate for MCP agents with governed memory and hybrid search.

Local-first long-term memory for coding agents — in-process embeddings (MLX/CPU), hybrid vector+BM25 search, markdown as source of truth. No cloud, no keys.

Proof-backed implementation memory for coding agents — search and retrieve verified primitives via HTTP API, MCP adapter guide included.

Local-first MCP server for searching private Obsidian vaults with hybrid full-text, fuzzy, semantic, and wikilink graph retrieval.

Self-hosted MCP server for Obsidian: semantic + full-text search, wikilink graph, note CRUD, OAuth, and a self-describing vault guide.

Search your past OpenCode conversation history before starting new work, via a local read-only FTS5 index — no network calls.

Turn LinkedIn saved posts into a queryable knowledge base you can search, chat with, and connect to Claude or ChatGPT through MCP.

Persistent coding memory for AI assistants — MCP stdio + remote URL, hybrid search, knowledge graph, token-efficient context. Self-host on Cloudflare D1 or Postgres.

A local-first, generic memory layer for MCP agents, with multilingual hybrid search and reranking, versioned memories, provenance, temporal recall, relationships, feedback, and secure multi-agent spaces.