QMD — Vault Semantic Search

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:

1. qmd_index in vault-manifest.json, when set — an explicit pin.
2. Otherwise the vault folder name, slugified. The template ships qmd_index empty so every install gets its own store without being asked a question.

Pin the field if you want a name that survives renaming the vault folder, or want to keep a store you already built.

Read the resolved name before running commands rather than assuming either branch:

INDEX=$(node -e '
  const ok = (s) => typeof s === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(s);
  const m = JSON.parse(require("fs").readFileSync("vault-manifest.json", "utf8"));
  if (m.qmd_index && !ok(m.qmd_index)) {
    process.stderr.write("qmd_index is set to an invalid name: " + JSON.stringify(m.qmd_index) + "\n");
    process.exit(1);
  }
  const slug = require("path").basename(process.cwd()).normalize("NFKD").toLowerCase()
    .replace(/[^a-z0-9._-]+/g, "-").replace(/-{2,}/g, "-").replace(/^[^a-z0-9]+|[-._]+$/g, "");
  const name = [m.qmd_index, slug, m.template].find(ok);
  if (!name) { process.stderr.write("no usable qmd index name — set qmd_index in vault-manifest.json\n"); process.exit(1); }
  process.stdout.write(name);