How to use metalmind well.
The README + --help cover what every command does. This page covers how to use them well - the patterns that compound, the anti-patterns that don't, the daily disciplines that turn the vault from a junk drawer into a knowledge graph Claude actually finds things in.
Writing a vault note Claude will find.
A note recall can find quickly is one that's aligned on three axes: title, frontmatter, and graph position. Default to all three.
Frontmatter discipline (the biggest single lever)
metalmind scribe stamps frontmatter automatically when you pipe a body through it - but the fields you pass on the command line shape how recall treats the note for the rest of its life.
- --project <slug> is the strongest discoverability signal. Notes with project: foo auto-link to Work/MOCs/foo.md and surface together. Use a slug, not a label. One project per note.
- --tags a,b,c for cross-cutting themes, not categories. caching, auth, regression-postmortem are tags. Three focused tags beat ten generic ones.
- --kind picks the folder. See What lives where.
Title and first line
The title is the H1. The first sentence is the highest-weighted text the embedder sees. Both should carry the topic.
Anti-patterns
- Orphan notes. A note that nothing links to and that has no project is invisible to graph traversal. Either link from a MOC, give it a project, or accept it's a one-off you may never find.
- Duplicate notes. The most expensive failure mode. Always recall first. If >50% overlap with an existing note, scribe update / scribe patch --find it instead of forking a new one.
- Inline frontmatter when piping through scribe. Scribe stamps automatically. If your body starts with ---, you'll end up with two - and the second one wins, silently overriding your fields.
- Long notes with multiple topics. One note = one topic. If a single note answers three questions, recall returns it for all three with weak-but-not-best scores. Split.
Recall hygiene.
Default tap copper covers 90% of cases - start there. When it doesn't, escalate deliberately rather than reflexively.
| flag | use when | cost |
|---|---|---|
| (none) | Default. Top hit is right 100% of the time to 10k notes, 95% at 50k. | 26-390 ms median by vault size |
| --deep | One hit looks right but you want adjacent context. Walks backlinks one hop. | One round-trip; +1 hop tokens. |
| --expand | Researching a topic broadly - hits + linked-context graph. | Heavier; every linked note loaded. |
| --rerank | Top-of-list precision matters more than latency. Cross-encoder rescore. | ~2 s per query; first call downloads ~500 MB. |
| --compact | Agent-facing recall. Lean per-hit render; full note via scribe show. | ~74% fewer output tokens. |
| --semantic-only / --keyword-only | A/B one retriever leg when a query returns something odd. | Same as default; skips one leg. |
| --verify-code | The note claims something about code and you want to know if it still holds. | rg per ref; 2 s per repo, 10 s per run. |
| --list-recent N | "What was I working on yesterday?" - no query, just recent files. | Cheap - file-mtime scan. |
The 2-3 rephrasings rule
The retriever is a single embedding pass over your phrasing. If the vault uses different wording, one query will miss. Rephrase 2-3 times - literal, then domain-term, then acronym↔spelled-out, then verb↔noun - and union the hits before deciding nothing is there. One miss is not a miss.
Reading the recall log
Set METALMIND_RECALL_LOG_PATH=~/.metalmind/recall-log.ndjson, then run metalmind doctor --recall-audit. Output: top 25 unique candidates ranked by frequency, classified ok / weak-hit / zero-hit. Local-only by design.
Folder by intent, not by project.
Project affiliation lives in the project: frontmatter field. Folders are about what kind of thing the note is.
| folder | kind | what goes here |
|---|---|---|
| Plans/ | plan | Implementation plans, dated filename. Flat - no per-project subfolders. |
| Learnings/ | learning | Durable cross-session lessons. The "I will never again..." file. Evergreen. |
| Work/ | work | Project-scoped decisions, architecture, design. Free-form filename. |
| Work/MOCs/ | moc | One Map-of-Content per project. The curated index + Dataview fallback. |
| Daily/ | daily | Time-bound journal. Action items via atium. Promote insights to Learnings. |
| Inbox/ | inbox | Triage bucket. >14 days untouched → /save proposes triage. |
| Memory/ | memory | Model-managed context. Migrated native memory. Mostly read-only. |
| Personal/ | personal | Non-work. Kept separate so work-recall doesn't surface personal notes. |
| Archive/ | - | Shipped or superseded. Recall still searches here (with rank penalty). |
The decision question
When you're about to write a note, ask:
- 01 Is this a decision (durable) or a logbook entry (time-bound)? Decision → Plans / Learnings / Work. Logbook → Daily.
- 02 Is this insight project-specific or generalisable? Project → Work. Generalisable → Learnings.
- 03 Will I (or another engineer) benefit from this in a year? Yes → write it well, link it from the MOC, give it real frontmatter. No → maybe Inbox for triage, or skip writing entirely.
If you can't answer those three in 30 seconds, the note isn't ready to write yet. Recall the topic first - the existing note (if any) tells you the shape.
Running metalmind beyond Claude Code.
Codex CLI became a first-class host in v0.8.0 and Cursor in v0.9.0, alongside Claude Code. Each gets the same recall-first behaviour with the same headline rule (zero standing MCP-schema tax, bare-bash recall as the default path).
metalmind init shows a multi-select of detected hosts (~/.claude/, ~/.codex/, ~/.cursor/) and stamps only what you choose. It writes seven things into ~/.codex/: a sentinel-bounded block in AGENTS.md, a SessionStart hook entry in hooks.json reusing the same hook script Claude Code uses, a [sandbox_workspace_write] network_access = true block in config.toml (without it Codex's default sandbox blocks loopback to the watcher), a rules/metalmind.rules file pre-approving the metalmind command surface so the first recall doesn't ask for permission, and three skills (writing-vault-notes, synod, save).
We never write to ~/.codex/memories/ (Codex's native memory; orthogonal) or ~/.codex/rules/default.rules (Codex's user-acceptance log). Everything stamped is sentinel-bounded or in metalmind-named files; metalmind uninstall round-trips cleanly.
Opt-in MCP server
Default install registers no MCP server - bare metalmind tap copper "..." via the model's shell tool keeps the standing token cost at zero. Pass --with-mcp if you want the explicit-tool-call shape (~150-400 tokens per turn for the schema; same trade-off Claude Code's stdio MCP fallback offers).
Codex desktop app - coming in v1.1
metalmind covers the Codex CLI (codex in your terminal). The desktop app (codex app) is on the v1.1 roadmap - pending verification that it shares ~/.codex/ storage and that the model has a shell-exec primitive there.
The full cookbook lives in the repo.
The version above covers the four highest-impact patterns. The repo cookbook adds migrating from mem0 / Letta / Notion and scaling past 10k notes, with worked examples per pattern.