QMD Search

STOP — Read Config First

• Use the Read tool to read .claude/qmd.json . If missing, tell the user: "qmd is not configured for this project. Run /qmd:configure to set it up." Then STOP.

• Extract project name and collections (each has: name, path, pattern, description).

• Pick the best collection for the query (match against descriptions). If only one, use it.

Every qmd command MUST include --json and -c <collection_name> . No exceptions.

Do NOT

• Run qmd without --json flag

• Run qmd without -c <collection>

• Use npx to run qmd — it is already installed

• Use qmd get to read files — use the Read tool//

• Use the --full flag — it floods the context window

• Skip reading .claude/qmd.json before searching

Query Types

qmd provides three search commands. Pick the right one for the situation:

qmd search — BM25 keyword search

Best when you know the exact terms or vocabulary used in the documents.

qmd search "<query>" -c <collection> --json -n 5

Query writing tips:

• Use 2-5 specific terms, no filler words

• Use exact phrases with quotes: qmd search "error handling" -c col --json -n 5

• Exclude terms with minus: qmd search "auth -oauth" -c col --json -n 5

• Think about what words actually appear in the documents

qmd vsearch — Vector/semantic search

Best when you don't know the exact vocabulary or want conceptual matching.

qmd vsearch "<query>" -c <collection> --json -n 5

Query writing tips:

• Write a full natural language question

• Be specific about what you're looking for

• Good: "How does the authentication system handle session expiry?"

• Bad: "auth sessions"

qmd query — Auto-expand + rerank (most powerful)

Best for complex topics. Automatically generates query variations and reranks results.

qmd query "<query>" -c <collection> --json -n 5

Query writing tips:

• Use for complex or multi-faceted topics

• Write naturally — the system auto-generates search variations

• Good for exploratory searches where you're not sure what you'll find

Strategy

Situation Use

Know exact terms qmd search

Don't know vocabulary qmd vsearch or qmd query

Best recall needed Try search first, vsearch if poor results

Complex or broad topic qmd query

Reading Results

JSON output contains an array:

[ { "docid": "#abc123", "score": 0.74, "file": "qmd://<collection>/path/to/file.md", "title": "Document Title", "context": "Collection description...", "snippet": "..." } ]

Score interpretation:

• 0.7+: Highly relevant — read this document

• 0.5-0.7: Worth reading if topic matches

• < 0.5 on all results: Try a different query type or refine your query

To read a result file:

• Extract the file path from the file field

• Strip the qmd://<collection>/ prefix

• Prepend the collection's path from config to get the repo-relative path

• Use the Read tool to read the file

Fallback

After poor results from 2 query types or 2 retries with refined queries, fall back to Glob/Grep on the directory. Default -n 5 (use 3 for narrow queries, 10 for broad).