How to Search Local Markdown Notes with QMD and Verify the Results

The example uses three synthetic release notes. Download the notes, exact command outputs, and reproduction instructions to repeat it. Their rollback rule is test data. We ran QMD 2.8.3 with a separate config and cache; no personal notes were searched.

Make sure QMD indexed the intended files

Install @tobilu/qmd, then register the directory that actually contains your .md files. QMD's documented requirements are Node.js 22 or later or Bun 1.0 or later; on macOS, its README also specifies Homebrew SQLite. Replace the path below with your notes folder:

npm install -g @tobilu/qmd
qmd collection add ~/Documents/notes --name notes --mask '**/*.md'
qmd collection show notes
qmd ls notes
qmd status

collection add indexes matching files as it creates the collection. In our three-note fixture, it reported Indexed: 3 new. qmd ls notes then listed the three qmd://notes/... paths, while qmd status showed three indexed files and zero embedded vectors. That was enough to run keyword search. If a file is missing from qmd ls, check the directory and mask shown by collection show; changing query wording will not make an unindexed file appear. QMD's default mask is **/*.md, and it excludes directories such as .git, node_modules, vendor, dist, and build. After changing a collection path, mask, or ignore rule, inspect the update hooks described below before running qmd update. These controls are described in the collection configuration.

Use keyword results to locate notes, then reject the wrong ones

For a phrase or distinctive term, start with BM25 keyword search. -c notes limits the search to your collection; -n 10 shows more than the default five candidates:

qmd search 'rollback window' -c notes -n 10

In the fixture, this returned Launch sync first, Old launch checklist second, and Launch decision third. The first note says no rollback decision or window was recorded. The second calls itself superseded. Only the third is marked current. It says the release lead checks the error dashboard and deployment log before deciding, gives a 30-minute sample window, and expressly rules out automatic rollback. The CLI displayed Score: 0% for all three keyword hits, although their snippets matched. The result list located candidate notes; neither score nor rank established the answer. In a real vault, a note's current label can itself be stale, so compare it with the decision record your team treats as authoritative.

If you know a rare phrase from the wanted note, try it directly. Here, qmd search 'copper lantern' -c notes returned only Launch decision. Read the note anyway: the phrase alone says nothing about its status or the limit on automatic rollback.

Use semantic search when the note uses different words

Run qmd embed before vector or hybrid search. If none are cached, QMD's default embedding, reranking, and query-expansion models can require about 2 GB of downloads across this workflow, according to its model list. If you know an exact title, code symbol, or phrase, qmd search avoids those model-backed steps. For an indirect question, the maintainer recommends writing intent: plus lexical and semantic clues instead of passing a bare sentence to qmd query. The multiline command below uses Bash or Zsh quoting:

qmd embed
qmd vsearch 'Who decides whether to undo a deployment after checking the error dashboard?' -c notes -n 3
qmd query $'intent: Prefer the current release decision over meeting chatter and superseded checklists.\nlex: release lead rollback window deployment log\nvec: who decides whether to undo a launch after reviewing the error dashboard' -c notes -n 3

In the three-note run, that structured query ranked Launch decision first, followed by the meeting note and superseded checklist. The intent: field steered ranking; it did not filter those two notes out. A qmd vsearch question about who decides after checking the error dashboard also put the current note first. This small corpus is not an accuracy benchmark for a larger vault. QMD's search-mode reference distinguishes keyword, vector, and hybrid retrieval. If model loading or reranking fails, run qmd doctor; while diagnosing it, use qmd search with sharper terms, as the maintainer guide suggests.

Open the result and verify the source

A search hit supplies a qmd:// URI and a short #docid. Retrieve the complete note with either one. The URI below comes from the fixture; replace it with a path returned from your own collection:

qmd get qmd://notes/releases/launch-decision.md
qmd get qmd://notes/releases/launch-decision.md --full-path

Our get result numbered the lines: line 3 marked the note current, line 5 named the release lead's checks, line 7 gave the sample window, and line 9 ruled out automatic rollback. Quote or cite the line that supports your answer and keep line 9 with any description of line 7. The --full-path form identifies the current on-disk file, which you can open in an editor and compare with the retrieved text. QMD may print a ./-prefixed relative path when the file sits under your current working directory. The maintainer guide also documents qmd multi-get for comparing several hits and qmd get '#docid:from:count' for a line range in a long note.

Use the URI or path for a note you may revisit after edits. In our fixture, the current note's docid changed from #96823b to #f22eb9 when its content changed; the qmd://notes/releases/launch-decision.md URI still identified the file.

Check whether the index reflects the current files

Before running qmd update on your usual notes, inspect the active index.yml for each collection's update: field. QMD refreshes every collection in that index and runs any configured update command, such as git pull, before reindexing. The downloadable fixture sets separate configuration and cache directories and has no update hook. See QMD's index-maintenance documentation for the hook behavior.

We added the line Freshness marker: indigo compass. to the current fixture note. Before refreshing, qmd search 'indigo compass' -c notes returned No results found. After qmd update reported 1 updated, the same search found the changed note. This is an observable way to separate a stale index from a genuine missing term when you have edited a file you can inspect.

A deleted file can leave a more misleading hit. We removed the fixture's old checklist without updating QMD, then ran qmd search 'old checklist' -c notes --full-path. QMD still returned its indexed qmd:// result, but warned that the file could not be resolved on disk. After qmd update reported 1 removed, the old checklist no longer appeared. QMD documents this --full-path warning in its search options. When using vector or hybrid search after changed notes, run qmd embed as well so the embeddings correspond to the refreshed index.

Diagnose a missing answer in the right place

For searches across several collections, note one QMD-specific limit: multiple -c flags draw from a shared top-ranked candidate pool before collection filtering. If one collection dominates a short result list, search the smaller collection alone or raise -n. An unscoped search also omits collections marked excluded unless you name them with -c. Both behaviors are stated in QMD's collection filtering reference.