∴ metalmind
Command spelling
Scadrial · Keeper Knowledge · CLI

metalmind

A metalmind for Claude. Store decisions in copper. Tap them when you need them. Persistent memory for Claude. Save decisions. Recall them when you need them.

Every claude invocation is a first meeting. Yesterday's architectural call, the reason you rejected that library, the 40-minute debug you just finished — gone by tomorrow. metalmind is the place Claude stores things, and the way Claude gets them back — without burning context tokens on tool schemas to do it.

$ npm install -g metalmind
Coming to npm Clone the repo to try early builds.
view on GitHub →

What it adds

Four things that survive your claude ending, start fresh, and a fifth that lets you take it all back.

Persistent memory across sessions
store copper "<insight>"save "<insight>" deposits a decision into your local Obsidian vault. metalmind proposes the path, wikilinks, and frontmatter; you approve; it writes. Tomorrow's session recalls it as if yesterday never ended.
Recall without the MCP token tax
tap copper "<query>"recall "<query>" is a Bash call, not an MCP tool — zero schema bloat per session. Most memory tools silently inject 3–5 tool schemas into every Claude Code session before you've typed a prompt. We stamp the command into your CLAUDE.md so Claude reaches for it naturally. --deep follows backlinks; --expand returns hits plus the surrounding graph.
Sight across repos, not just one
burn bronze "<query>"graph "<query>" queries a code graph of every repo in your forgegroup. HTTP-route-match edges connect caller → handler across services. Every inferred edge carries INFERRED_NAME / INFERRED_ROUTE provenance so Claude can trust-grade what it reads.
Reversible to zero
metalmind uninstall stops containers, unloads the watcher service (launchd on macOS, systemd on Linux), restores your prior output style, clears the settings we changed, removes shell aliases. Never touches your notes. Everything we did is undoable in one command — a design constraint, not an afterthought.

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.

Commands

Metal Command Description
Copper ↓ $ metalmind store copper "..." $ metalmind save "..." Deposit an insight to the vault.
Copper ↑ $ metalmind tap copper "<q>" $ metalmind recall "<q>" Retrieve semantically (--deep / --expand).
Bronze $ metalmind burn bronze "<q>" $ metalmind graph "<q>" Query the code graph (Seeker).
Iron $ metalmind burn iron "<sym>" $ metalmind symbol "<sym>" Pull a symbol and its neighbors.
Steel $ metalmind burn steel <o> <n> $ metalmind rename <o> <n> Coordinated rename via Serena.
Tin $ metalmind burn tin $ metalmind verbose Enhanced output — verbose toggle.
Pewter $ metalmind burn pewter $ metalmind reindex Force-rebuild the code graph.
Zinc $ metalmind burn zinc "<bug>" $ metalmind debug "<bug>" Rioter — dispatch a team-debug session.
Aluminum $ metalmind burn aluminum $ metalmind wipe Wipe install (reversible uninstall).
Brass $ metalmind burn brass $ metalmind stamp Soother — re-imprint metalmind managed files (upgrade in place).
Forge $ metalmind forge create <g> $ metalmind group create <g> Define a cross-repo group.
Forge $ metalmind forge add <g> <r> $ metalmind group add <g> <r> Add a repo to the group.
Forge $ metalmind burn bronze "<q>" --forge <g> $ metalmind graph "<q>" --group <g> Query across every repo in the group.
Seeker $ metalmind pulse $ metalmind doctor Pulse-check the install — prereqs, config, MCP state.

Both spellings always work at the CLI. Use the Scadrial / Classic toggle in the nav to re-spell the page.

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. Prereqs, detected

    Claude Code, Docker, Python 3.11+, uv, git — each checked with a per-failure remediation. Failing prereqs halt the wizard with a concrete fix.

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

  2. 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. 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. Local stack

    Qdrant + Ollama start as Docker containers (metalmind-qdrant, metalmind-ollama). nomic-embed-text pulls once. All embeddings stay on your machine.

    ◇  Starting Docker stack (Qdrant + Ollama)
◆  stack at ~/Knowledge/.metalmind-stack
   nomic-embed-text pulled

  5. 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. Ready

    metalmind pulse verifies the whole chain end-to-end. metalmind uninstall rolls everything back — watcher, containers, MCP entries, settings, aliases — 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.

Vault
Obsidian at ~/Knowledge/. Qdrant + Ollama (nomic-embed-text) embed locally. Incremental watcher re-embeds only changed files — no empty-window queries during reindex.
Serena
LSP-backed symbol navigation and coordinated renames. Zero-LLM per query.
graphify
Per-repo code graph — clusters, god nodes, call paths. Tree-sitter AST; optional LLM for docs.
Forge Group
Cross-repo merge layer — name-match + HTTP-route edges tagged with INFERRED_NAME / INFERRED_ROUTE provenance.