QMD — Vault Semantic Search

Before reading vault files directly, search with QMD first. It returns relevant snippets without burning context on full file reads.

Tool Surfaces — Preference Order

Pick the highest surface available and stop. All three read the same SQLite store (see Named Index), so they return the same results; the choice is about interface ergonomics and context cost.

1. MCP tools (preferred when registered) — mcp__qmd__query, mcp__qmd__get, mcp__qmd__multi_get, mcp__qmd__status. If these appear in your tool menu, the MCP server is live and pre-scoped to this vault. Call them directly — no --index argument needed, no shell involved, typed arguments. This is the intended path during a session.
2. CLI fallback — qmd --index <name> query|search|vsearch|get|multi-get. Use when the MCP server isn't registered (older vault clones, Windows install drift, disabled in .mcp.json), or for one-off shell checks outside a session. Always pass --index <name>.
3. Grep / Glob / Read — last resort, only when QMD is not installed at all. These burn context on full file reads and don't rank by relevance.

Never fall through surfaces without cause — if MCP is registered, calling the CLI in a Bash tool is just a slower path to the same result.

Named Index (This Vault)

This vault uses a named QMD index so queries, updates, and context strings stay scoped to this vault — not blended with any other vault that shares the machine. Every QMD command in this document passes --index <name>.

The name resolves the same way on all three surfaces (CLI, MCP, SessionStart hook), so they always point at the same SQLite store: