Mnemo

Mnemo

> Persistent memory for Claude Code. Your AI never starts from scratch again.

[](https://github.com/omermaksutii/mnemo/actions) [](https://www.npmjs.com/package/@mnemo-mcp/cli) [](https://www.npmjs.com/package/@mnemo-mcp/server) [](https://www.npmjs.com/package/@mnemo-mcp/core) [](LICENSE)

Mnemo gives Claude Code a brain that survives across sessions. It captures decisions, conventions, and preferences — and recalls them by meaning, on demand, with sub-100ms semantic search.

---

Install

# install the CLI
npm install -g @mnemo-mcp/cli

# install Mnemo into Claude Code (skill + MCP server)
mnemo init

# (optional) also wire auto-capture hooks
mnemo init --with-hooks

# verify
mnemo doctor

After mnemo init, restart Claude Code. The /mnemo skill and the mnemo_* MCP tools are now available — Claude will use them automatically when relevant.

Use it from the terminal too

mnemo remember "our API auth uses OAuth2 with refresh tokens every 30min"
mnemo remember --global "I prefer pnpm over npm"
mnemo recall "what's our auth pattern?"
mnemo recall "auth" --explain          # show the ranking breakdown per hit
mnemo list
mnemo stats
mnemo forget 
mnemo backup                            # timestamped snapshot
mnemo restore mnemo-backups/.json
mnemo migrate                           # rebuild the index after an embedder change
mnemo serve                             # localhost web dashboard
mnemo watch docs/                       # auto-capture matching files as they change

Knowledge graph (v2.1)

mnemo entity create AuthService -t service -d "login + tokens"
mnemo entity link Billing requires AuthService
mnemo entity attach  AuthService
mnemo entity show AuthService --depends   # memories, relations, and what depends on it

Cross-agent, plugins, and sync (v2.3–v2.5)

mnemo agents                            # who captured what (claude-code, cursor, aider…)
mnemo plugins                           # discovered embedder/ranker/hook plugins
# end-to-end encrypted multi-machine sync (server stores ciphertext only):
export MNEMO_ENCRYPTION_KEY=…  MNEMO_SYNC_URL=https://your-host  MNEMO_SYNC_TOKEN=…
mnemo sync push      # encrypt locally → upload
mnemo sync pull      # download → decrypt → import

Run your own sync backend with npx @mnemo-mcp/sync-server — it never sees plaintext.

Encryption at rest

export MNEMO_ENCRYPTION_KEY="a strong passphrase"   # memory.db is then AES-256-GCM at rest

What Mnemo solves

Claude Code forgets everything when the session ends. CLAUDE.md partially helps — it's a static blob loaded on every turn — but it grows unwieldy fast and can't answer "do we have a precedent for X?"

Mnemo gives you semantic, on-demand memory:

| | CLAUDE.md | Mnemo | |---|---|---| | Capacity | A handful of paragraphs before token cost hurts | Tens of thousands of memories | | Retrieval | Always loaded, every turn | On demand, by meaning | | Updates | You edit a file by hand | Captured automatically or via /teach | | Cross-project | Per-project only | Project + global tiers | | Forgetting | Manually delete lines | mnemo forget or /forget |

How it works

Claude Code session
  ├── /mnemo skill              ← teaches Claude when to call the tools
  ├── @mnemo-mcp/server server          ← exposes recall/remember/forget/list/stats
  └── @mnemo-mcp/cli hooks           ← session-start, pre-task, post-edit auto-wiring
              │
              ▼
       @mnemo-mcp/core
       ├── ONNX all-MiniLM-L6-v2  (384-dim embeddings, ~25MB, lazy)
       ├── HNSW vector index      (sub-100ms recall at 50k memories)
       └── sql.js (WASM SQLite)   (~/.mnemo/memory.db)

Everything is local-first. No daemon. No cloud account. No telemetry.

Auto-capture rules

By default the post-edit hook captures any change to:

• CLAUDE.md, AGENTS.md, GEMINI.md
• *.adr.md
• docs/decisions/**
• docs/adr/**

Anything you write to those files becomes a project memory automatically. Disable with mnemo init (no --with-hooks).

Recall scoring

score = 0.7 × cosine_similarity + 0.2 × recency + 0.1 × access_boost

Recency decays with a 30-day half-life. Access boost saturates at 20 reads.

Layout

@mnemo-mcp/core         — pure TS memory engine (embeddings, HNSW, store, graph, plugins, crypto)
@mnemo-mcp/server       — MCP server (drop into Claude Code; 9 tools)
@mnemo-mcp/cli          — terminal commands + hook handlers + init
@mnemo-mcp/sync-server  — self-hostable, end-to-end-encrypted sync backend

Roadmap

• ✅ v0.1 — core engine + CLI
• ✅ v0.2 — MCP server (5 tools)
• ✅ v0.3 — hooks (session-start, pre-task, post-edit)
• ✅ v0.4 — /mnemo skill
• ✅ v1.0 — mnemo init, beefier doctor, CI, polish
• ✅ v1.1 — team mode, channels, secret guard, ingest, why, digest, dead, cite, interactive recall, JSON output, completions
• ✅ v1.2 — JSON mode in all commands, idempotent init, doctor robustness
• ✅ v2.0 — procedural memory: mnemo procedure record/run/suggest/done + 2 new MCP tools + auto-suggestion via pre-task hook
• ✅ v2.1 (2.1.0) — quality of life: backup/restore, migrate, watch, serve dashboard, recall --explain/--stream, encryption at rest, int8 quantization
• ✅ v2.1 (2.2.0) — knowledge graph (entities + relations + BFS depends-on + 2 MCP tools)
• ✅ v2.2 (2.3.0) — self-reflective learning (auto-capture anti-patterns from Stop/SubagentStop hooks)
• ✅ v2.3 (2.4.0) — cross-agent memory (per-agent attribution, mnemo agents, standard MCP discovery)
• ✅ v2.4 (2.5.0) — plug-in framework (custom embedders, rankers, capture rules, hooks)
• ✅ v2.5 (2.6.0) — optional end-to-end-encrypted sync (@mnemo-mcp/sync-server + mnemo sync) + web UI

See [ROADMAP.md](ROADMAP.md) for design notes on each.

Development

npm install
npm run build
npm test                                    # fast (150+ tests, hash embedder)
MNEMO_TEST_ONNX=1 MNEMO_E2E=1 npm test     # full incl. real ONNX (~5s)
npm run lint

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: omermaksutii
• Source: omermaksutii/mnemo
• License: MIT

Install and usage instructions live in the source repository linked above.