ramonclaudio/search

QMD Search

Decision rules and patterns for searching indexed reference collections via the qmd MCP server.

Status

• Index: !qmd status 2>/dev/null | head -1 || echo "qmd not running"
• Collections: !qmd status 2>/dev/null | grep -cE '^ [a-z]' || echo 0

When to use QMD vs Grep/Glob

| Source of files | Use | |-----------------|-----| | The current working directory (the user's repo) | Grep, Glob, Read | | Indexed reference repos (~/Developer/refs/*) | mcp__qmd__query | | Personal notes / docs that the user added with /qmd:add | mcp__qmd__query |

QMD is for content you can't reach with Grep because it's outside the working tree. Don't use it for files in the current project — Grep/Glob are faster, cheaper, and more precise.

Pipeline note (matters for query quality)

The MCP query tool calls structuredSearch, which skips the local LLM query expansion. The model never gets a chance to fix a vague vec: line. You (Claude) are the expansion model. Compose typed sub-queries deliberately:

• lex: for exact terms, identifiers, error codes, file/symbol names
• vec: for semantic phrasing of the user's question
• hyde: for nuanced topics — write 50-100 words of what the answer would look like
• intent: for any ambiguous keyword (treat as required, see below)

The first sub-query gets 2x weight in RRF fusion. Put your strongest signal first.

The upstream MCP server already injects a full description of the query tool with grammar, lex syntax, and worked examples — you don't need to memorize it, but you should compose queries with the same care you'd put into a vector DB query.

Intent: treat as required

The MCP server's standing instruction is:

Always provide intent on every search call to disambiguate and improve snippets.

Follow it. intent doesn't search on its own — it steers query expansion, reranking, chunk selection, and snippet extraction. A 5-word intent string is essentially free and dramatically improves results for any keyword that's overloaded across domains.

Words that almost always need intent: performance, state, cache, pool, worker, signal, frame, model, router, context, session, migration, lock, queue, channel, agent, bridge, binding, hook, provider, adapter, client, store.

Good intent is specific to the user's actual stack:

• "Convex authQuery wrapper for row-level security" (not "auth")
• "Expo SDK 56 native module bridging on iOS" (not "native module")
• "Next.js App Router server action with form action prop" (not "server action")
• "Postgres advisory lock for cron leader election" (not "locking")

Collections filter

Always pass collections: [...] when you know which repo(s) to search. The indexed set changes over time, so run mcp__qmd__status once per session to see the live list rather than assuming a fixed roster. Names follow a stable convention: <framework>-docs for markdown docs, <framework>-src for TypeScript source, <tool>-skills for agent skill guides, plus qmd itself.

Omitting collections searches every default collection, which is slower and dilutes signal.

Collections marked includeByDefault: false are silently skipped unless explicitly named in the collections array. The MCP status tool's response does NOT include the include/exclude state, so you can't tell from mcp__qmd__status which collections are excluded — if a search returns nothing and the user expected results from a known collection, check via the bash fallback qmd collection list (which marks excluded ones with [excluded]) or qmd collection show <name>.

Named indexes

qmd supports separate indexes via --index <name>. Each named index has its own SQLite DB and YAML config:

• Default: ${XDG_CACHE_HOME:-~/.cache}/qmd/index.sqlite + ${XDG_CONFIG_HOME:-~/.config}/qmd/index.yml
• Named: ${XDG_CACHE_HOME:-~/.cache}/qmd/<name>.sqlite + ${XDG_CONFIG_HOME:-~/.config}/qmd/<name>.yml

The plugin's MCP server uses the default index. If the user has set up additional indexes (e.g. work for client repos, personal for notes), search them via the CLI fallback:

qmd --index work query "deployment runbook"
qmd --index personal query "journal entry about last summer"

Ask the user which index they want before searching if it's ambiguous. Most setups use only the default.

Score interpretation

| Score | Meaning | Action | |-------|---------|--------| | 0.8 – 1.0 | Highly relevant | Show to user | | 0.5 – 0.8 | Moderately relevant | Include if few results, otherwise filter | | 0.2 – 0.5 | Somewhat relevant | Only if user wants more | | 0.0 – 0.2 | Low relevance | Usually skip |

minScore calibration:

• Default minScore: 0 is right for exploratory queries — don't pre-filter.
• minScore: 0.3 is the right floor when you want to prune obvious junk but keep partial matches.
• minScore: 0.5 is too aggressive for broad queries and will return zero rows for anything semantic. Only use for narrow, high-confidence lookups (exact identifier with lex: only).

If a search returns zero results with minScore: 0.5, retry without it before assuming the content isn't there.

Subagent hygiene

Search results take real space in your context. For broad research (multiple queries, many results), delegate to a subagent so the raw retrieval stays out of the main thread:

Use the Explore subagent to research how Convex handles row-level security across the convex-docs and convex-src collections. Use mcp__qmd__query and mcp__qmd__get. Return a summary with file:line references.

For targeted lookups (one query, one collection, top 5 results), search directly. The overhead is fine.

Retrieval

get returns an MCP resource content block with a qmd:// URI and text/markdown mime type. Claude Code surfaces it as a document attachment, not inline text. Same for multi_get (one resource per file, plus text blocks for errors/skips).

Search results now carry an absolute source-file line (qmd 2.5.0), so you can pass a hit's line straight to get as fromLine to land near the match. The snippet still covers the best matching chunk (~900 tokens), so widen with maxLines when you need surrounding context.

@<absolute-path> shortcut: when a search hit points to a file on disk, you can reference it inline via @/Users/.../refs/next.js/packages/.../router.ts to attach the whole file to your reply context without calling get. The collection's on-disk path is in mcp__qmd__status. Useful when the user wants to see the full file rather than a chunked snippet.

Recovery

| Symptom | Cause | Fix | |---------|-------|-----| | Search returns nothing, errors, or misbehaves after an upgrade | Model, GPU, or index health | Run /qmd:doctor first to isolate it | | mcp__qmd__* tools missing from your tool list | MCP server disconnected | Run /qmd:status (Bash fallback) or /mcp to check | | Zero results after a successful index | Mask excluded the relevant files | Re-add with /qmd:add <repo> --mask "<broader-glob>" | | Timeouts or hangs | Index corruption | /qmd:doctor, then /qmd:cleanup and /qmd:embed -f | | Low-quality results | Vague vec query, no intent | Tighten lex:, add intent:, add a hyde: line | | "Collection not found" | Typo or removed collection | mcp__qmd__status to list current collections |

CLI fallback

When the MCP server is down, fall back to bash via the slash commands or directly:

qmd query "<question>" -c <collection>             # Hybrid (slowest, highest quality)
qmd query "<question>" --no-rerank -C 20           # Fast path: skip reranker, fewer candidates
qmd search "<exact term>" -c <collection>          # BM25 only (fastest, no LLM)
qmd get <path> --line-numbers                      # Retrieve a single doc
qmd multi-get "docs/*.md" --json --max-bytes 20480 # Batch retrieve with size cap
qmd query "<q>" --intent "<domain>" --explain --json  # Debug score traces
qmd ls <collection>                                # Browse files in a collection (ls -l style)
qmd ls <collection>/<path>                         # Browse a subdirectory
qmd ls qmd://<collection>/<path>                   # Same, via virtual URI
qmd collection list                                # Show all collections + ignore globs + [excluded] tags

CLI accepts multiple -c flags for cross-collection search. qmd ls is the only way to discover files in a collection without searching — useful when verifying that an /qmd:add mask actually indexed the right files, or when the user asks "what's in this collection?"

Examples

For worked examples covering common patterns (precision queries, hyde for nuance, intent-aware disambiguation, subagent delegation), see references/examples.md.

For pipeline internals (chunking, RRF blending, position-aware reranking, AST chunking), see references/pipeline.md.