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 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. Right answer 90% of the time. | ~8 ms median |
| --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 ~150 MB. |
| --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.
The full cookbook lives in the repo.
The version above is the v0 — three highest-impact patterns. The repo cookbook adds migrating from mem0 / Letta / Notion and scaling past 10k notes, with worked examples per pattern.