metalmind

What it's actually for

metalmind pays off when your knowledge lives across more than one repo. A single-repo user gets a lot from Claude Code's native /memory — text in CLAUDE.md, free, no moving parts. A multi-repo engineer — same vault across every project, decisions that outlive any single codebase, code graphs that cross service boundaries — is who metalmind is built for.

• One vault, every project. project: frontmatter plus a MOC per project. A decision written in repo A surfaces when you tap copperrecall in repo B if it's topically relevant. Native CLAUDE.md is scoped per-project; learnings don't cross-pollinate.
• Cross-repo code graph via forge. burn bronze "<q>" --forge <group>graph "<q>" --group <group> queries every repo in a group. HTTP-route edges connect a caller in one service to a handler in another — Claude native has no concept of "the other service's code." Details on the forge page.
• Knowledge that compounds. Each new project starts with every learning you've documented elsewhere. Learnings/ is intentionally flat — "CLIs should never paste weird package-manager invocations" applies to every repo you work in. With native memory you'd copy-paste the insight into every CLAUDE.md separately.
• Decisions that outlive the codebase. Repos get archived, rewritten, replaced. The vault doesn't — plain markdown in your own Obsidian directory, searchable forever. When a project finishes, the learnings stay accessible.

Where native /memory still wins: solo repo, under ~50 notes of context, no historical lookback needed. Below the break-even, it's simpler and free. metalmind earns its install cost when you've got more to remember than a single CLAUDE.md can cheaply hold.

Memory

The headline job. Save once, recall forever, with zero standing tax on Claude's context window. Recall is a Bash command hitting a loopback HTTP server in your watcher process — no MCP tool, no per-session schema bloat.

Code intelligence

The vault is half the picture. metalmind also gives Claude eyes on your code — across repos, with route-level edges other tools can't see. Each engine swaps independently; your muscle memory doesn't move.

Workflow that compounds back into the vault

The things you'd do anyway — daily planning, big architectural debates — captured back into the vault as plain markdown. Tomorrow's session starts with today's reasoning, not a blank page.

~/.claude/skills/
  save                  capture the session's key insight into the vault
  synod                 7-persona deliberation on architecture-class decisions
  writing-vault-notes   teach Claude vault conventions (OFM, scribe, MOCs)
  using-teams           coordinate multi-agent teams (TeamCreate / SendMessage)
  obsidian-markdown     Obsidian-flavoured-markdown reference for note bodies

~/.claude/commands/
  /save                 alias of the save skill — one-tap end-of-session capture

~/.claude/commands/  opt-in via metalmind init --with-teams
  /team-feature         architect-led team to design + implement a feature
  /team-debug           3–5 adversaries debate a bug via competing hypotheses
  /team-pr-review       4 reviewers parallel-audit a PR (sec / api / perf / conv)
  /team-multi-repo-audit  one reviewer per repo, parallel cross-repo audit

How metalmind compares

Five "memory for AI" tools, side-by-side on the dimensions that actually differ. Recall numbers on a fixed corpus are above; this is the shape comparison — what each tool stores, how the agent reaches it, and where your data lives.

Why it isn't an MCP server

Most memory tools register themselves as MCP servers. That design injects a handful of tool schemas (search_memory, recall, store, …) into every Claude session before you prompt anything. Those schemas eat context tokens you could be using for the actual task.

metalmind takes the opposite bet: the recall surface is a CLI, Claude learns the command once from your stamped CLAUDE.md, and every session starts with a clean context. The watcher, indexer, and embedding stack still live locally — they just don't live in Claude's tool registry.

Who should NOT use metalmind

Honest anti-personas — install the wrong tool and you'll bounce in an hour:

• You don't use Claude Code. SessionStart hook, stamped CLAUDE.md, MCP fallback — all target Claude Code specifically. Cursor/Codex/Copilot/Gemini are roadmap.
• You don't use Obsidian. The vault is the storage layer. No other UI is planned.
• You want a 30-second install. The wizard takes a few minutes — Python prereqs, embed-model download (~30 MB), first-index. Worth it for daily users; overkill for evaluation.
• You're a team of 5+ with shared memory needs. metalmind is single-dev by design. The forge supports many repos per dev; it does not sync vaults between devs.

Will this still be around?

Fair question for any solo-maintainer tool. The sustainability story:

• Your notes outlive metalmind. The vault is plain markdown in your own ~/Knowledge/ directory. If this project goes unmaintained tomorrow, you keep everything — Obsidian still opens the files, grep still searches them, git still versions them. metalmind is the layer that makes Claude use them well, not the layer that holds them hostage.
• No cloud, no accounts, no phone-home. Embeddings, indexing, recall, code graphs — all local. There is no metalmind backend to shut down, no API quota to throttle, no subscription to lapse. The only network call is the one you were already making to Claude.
• Reversible in one command. metalmind uninstall stops the watcher, strips the sentinel-bounded blocks from your CLAUDE.md files, and clears shell aliases. Your vault is never touched. Try it — then reinstall if you like it.
• MIT licensed. Fork it, vendor it, swap the embedding backend. Architecture decisions are documented in docs/, bench/, and CHANGELOG specifically so a contributor — or a future-you — can keep it running.

Install flow

A single metalmind init drives the whole install — and every step is reversible via metalmind uninstall, which never touches your notes. Scroll the rail below to trace what happens.

1. 01

   Prereqs, detected

   Claude Code, Python 3.11+, uv, git — each checked with a per-failure remediation. Failing prereqs halt the wizard with a concrete fix. Docker is only required when you opt into --legacy.

   ◆  Claude Code   2.1.114
   ◆  Python 3.11+  via python3.12
   ◆  uv            0.11.7
   ◆  git           2.53.0

2. 02

   Vault scaffold

   Picks or creates your Obsidian vault. Drops in Work / Personal / Learnings / Daily / Inbox / Archive / Memory, stamps a CLAUDE.md that teaches Claude to recall via CLI — not MCP tools.

   ◇  Setting up vault
   ◆  Vault at ~/Knowledge
      created: Work, Personal, Learnings, Daily, Inbox, Archive, Memory

3. 03

   Engines installed

   Three Python tools land on PATH via uv — Serena (LSP navigation), graphify (code graph), vault-rag (recall server + watcher + indexer + doctor). Mirror of how you install anything else.

   ◇  Installing Serena      → uv tool install serena-agent
   ◇  Installing graphify    → uv tool install graphifyy
   ◇  Installing vault-rag   → uv tool install metalmind-vault-rag

4. 04

   In-process retrieval stack

   sqlite-vec for vectors and fastembed (BAAI/bge-small-en-v1.5) for embeddings live inside the watcher process — no Docker, no daemon. The 30 MB ONNX model downloads once on first index. Pass --legacy to opt into the older Qdrant + Ollama Docker stack instead.

   ◇  Embedded backend (sqlite-vec + fastembed) — no Docker stack needed
   ◆  Python tool venv at ~/.local/share/uv/tools/metalmind-vault-rag
      model cache at ~/.cache/fastembed/

5. 05

   Services, hook & routing

   Auto-reindex watcher runs as a background service — launchd on macOS, systemd --user on Linux. MCP registers Serena only; vault recall is a CLI call (no schema tokens). A SessionStart hook injects a memory-available reminder so fresh Claude sessions discover the vault without prompting. Optional: disable native auto-memory and route all memory to the vault.

   ◇  Installing watcher service
   ◆  wrote com.metalmind.vault-indexer.plist
   ◇  Installing SessionStart hook
   ◆  registered in settings.json
   ◇  Applying memory routing
   ◆  disabled native auto-memory

6. 06

   Ready

   metalmind pulse verifies the whole chain end-to-end. metalmind uninstall rolls everything back — watcher, MCP entries, settings, aliases (and Docker containers if you used --legacy) — without ever touching your notes.

   $ metalmind pulse
   ◇  Prerequisites
   ◇  Config
   ●  flavor:     scadrial
   ●  vaultPath:  ~/Knowledge
   ●  mcp:        serena, graphify
   └  All systems nominal.

Under the metalmind Under the hood

One verb, one job. Each engine is swappable — so if a backend gets replaced later, your muscle memory doesn't move. Your notes, embeddings, and code graphs never leave your machine.