Your notes are only useful if you can find the right one in seconds — the runbook paragraph, the decision from last month's meeting, the incident review that already solved today's outage. Grep finds keywords. What it cannot do is find the document that means the same thing in different words, rank a dozen near-matches, or hand a clean answer to your coding agent.

QMD does all three, on your machine, with no API key. It is a local search engine for markdown: BM25 keyword search, vector search over local embeddings, and a hybrid mode that expands your query with a small local model, fuses the results, and reranks them. Version 2.9.0, released November 18, adds metadata filtering, document processors, and remote-model support — and it is currently trending on GitHub, with 31,248 stars and 1,970 forks at the time of writing. This tutorial installs it, indexes a real folder of docs and notes, and measures every search mode end to end. The project is tobi/qmd on GitHub, MIT licensed.

What you will need#

  • Node.js 22 or newer. QMD is published as the npm package @tobilu/qmd; Bun 1.0+ also works. The tutorial was verified with Node v24.22.1 and npm 10.9.4 on Linux. macOS needs Homebrew SQLite (brew install sqlite) for extension support; Linux needs nothing extra.
  • About 2.3 GB of disk for models, on first use. QMD auto-downloads three GGUF models from Hugging Face: EmbeddingGemma 300M (~318 MB) for embeddings, a fine-tuned Qwen3 1.7B (~1.19 GiB) for query expansion, and Qwen3-Reranker 0.6B (~610 MB) for reranking. They are cached in ~/.cache/qmd/models/. Keyword search needs none of them.
  • No API key, no account, no GPU. Everything runs locally. On a CPU-only machine the small models are slow — budget minutes, not seconds, for the first embedding pass — but they work. This tutorial was verified on a 2-core VM with no GPU.
  • A folder of markdown. Notes, docs, meeting transcripts, a wiki — anything *.md. The tutorial uses a six-document sample (deploy runbook, API auth notes, billing migration plan, onboarding checklist, meeting notes, incident review) so every result below is reproducible.

Step 1 — Install QMD#

npm install -g @tobilu/qmd
qmd --version

Expected output:

qmd 2.9.0 (aa247d0)

The version string includes the git commit the release was built from; aa247d0 is the current tip of tobi/qmd. If you prefer not to install globally, npx @tobilu/qmd runs it directly. qmd --help lists the three search modes up front: search (BM25 only), vsearch (vector only), and query (hybrid — the recommended default).

Step 2 — Create a project index and add collections#

QMD keeps its configuration in a single YAML file and its index in SQLite. A project-local index keeps both inside the project:

cd ~/my-docs
qmd init
qmd collection add ./docs --name docs
qmd collection add ./notes --name notes
qmd collection list

qmd init prints ready to go with new local index and writes .qmd/index.yml, pre-filled with the three default model URIs, plus an empty index.sqlite (about 220 KB before any documents are indexed). Each collection add indexes its folder immediately — four documents from docs/, two from notes/ in the sample — and reports how many chunks still need vectors:

Indexed: 4 new, 0 updated, 0 unchanged, 0 removed

Run 'qmd embed' to update embeddings (4 unique hashes need vectors)

A collection is a folder plus a glob (default **/*.md). You can scope later searches with -c docs or -c notes -c docs, exclude a collection from default searches with qmd collection exclude, and attach a shell hook that runs before every re-index with qmd collection update-cmd notes 'git pull --rebase'. Re-indexing after edits is qmd update; it reported 0 new, 0 updated, 4 unchanged on an unchanged folder. qmd status summarizes the whole index: document count, how many still need embedding, collections, and the model URLs.

Step 3 — First search: BM25, no models required#

Before any model downloads, keyword search already works. QMD's search is BM25 full-text search over the SQLite FTS index:

qmd search "deploy freeze Friday"
qmd://docs/deploy-runbook.md:3 #000713
Title: Deploy runbook
Score:  58%

@@ -2,4 @@ (1 before, 3 after)

The production deploy freezes every Friday at 17:00 UTC; no deploys land after the freeze until Monday 09:00 UTC.

To roll back a bad deploy, run `deploy rollback --to <sha>` from the repo root. The rollback replays the previous healthy release and takes about 90 seconds.

The correct document is first at 58%, ahead of the meeting notes at 54% (which mention the freeze as an open question). A scoped search is sharper still — qmd search "Postgres 16 migration" -c docs returns the billing migration plan at 73%. Scores are normalized to a 0–100% scale; the README's own guide reads 0.8–1.0 as highly relevant, 0.5–0.8 as relevant, 0.2–0.5 as somewhat relevant.

For agents and scripts, --json emits structured results with docid, score, file, line, title, and snippet. qmd search "checkout 500 error rate" --json returned the incident review at 0.79. qmd get then retrieves a full document by path or docid, line-numbered — qmd get "#000713" prints the deploy runbook with its folder context attached.

Terminal output of a real qmd search: the deploy runbook ranks first at 58 percent, followed by meeting notes at 54 percent
Real output from this tutorial’s test corpus: qmd search ranks the deploy runbook first at 58%. Terminal render of a verified run.

Vector search needs embeddings. qmd embed downloads the EmbeddingGemma model on first use and embeds every indexed chunk:

qmd embed
Model: embeddinggemma-300M-Q8_0.gguf
✓ Done! Embedded 6 chunks from 6 documents in 3m 10s

The 3m 10s includes the ~318 MB model download; embedding six short documents is seconds of that. An incremental run after adding one document took 7 seconds. Embeddings are 768-dimensional vectors stored in sqlite-vec; re-running qmd embed only processes changed chunks.

One behavior worth knowing before you run vsearch: it does more than embed your query. QMD expands the query with the 1.7B expansion model first, then runs the original plus the expanded variants through vector search. So the first vsearch also downloads the ~1.19 GiB expansion model. That is the single biggest first-run cost in QMD, and it is not obvious from the command name — budget for it.

qmd vsearch "how do I roll back a bad release"

The expansion model rewrote the question into four vector queries — two paraphrases and one hypothetical passage (HyDE) — and searched them in parallel. The runbook still came first, but the scores are raw cosine similarity, so the gap between first and fourth is narrow:

$ qmd vsearch "how do I roll back a bad release"
├─ how do I roll back a bad release
├─ vec: steps for rolling back software releases
├─ vec: best practices for rollback management
└─ hyde: To roll back a bad release, start by reviewing the requirements and d...
Searching 4 vector queries...

qmd://docs/deploy-runbook.md:5 #000713 — Deploy runbook — 54%
qmd://notes/adr-2026-11-15.md:13 #ff3e50 — ADR: freeze deploys on Fridays — 39%
qmd://notes/incident-2026-11-10.md:3 #b9bf56 — Incident review — 2026-11-10 — 34%
qmd://docs/billing-migration.md:5 #8b613b — Billing migration plan — 32%

Total time: 33.3 seconds on this 2-core CPU VM, most of it loading the 1.7B expansion model. The paraphrase test also shows the small model's limits — asked "are we allowed to ship code over Christmas", it expanded to "how do i navigate christmas celebrations with work schedules?" and returned a single hit, the Friday-freeze ADR at 30%, just above the 0.3 cutoff, in 21.9 seconds.

Paraphrase is where vector search earns its keep: the query shares almost no keywords with the runbook ("roll back" vs "rollback", "bad release" vs "bad deploy"), yet the semantic match still surfaces the right paragraph first. BM25 alone would have ranked it lower or missed it.

If you want vector search without the expansion step, use a typed query document with --no-rerank (see Step 5). The typed form skips expansion entirely and, at 6.9 seconds end to end on this VM, is the fastest semantic path QMD offers.

Step 5 — The full pipeline: qmd query#

qmd query is the mode the README recommends, and it runs all four stages: the expansion model rewrites your question into typed lex:, vec:, and hyde: sub-queries; BM25 and vector search run in parallel; reciprocal rank fusion merges the lists; the Qwen3 reranker scores the top candidates. The first run downloads the reranker (~610 MB) on top of the other two models.

qmd query "how do I roll back a bad release"

The full pipeline expands the same question into six sub-queries — the original, two lex: keyword queries, two vec: paraphrases, and one HyDE passage — runs BM25 and vector search in parallel, fuses the results with RRF, and reranks the top chunks:

$ qmd query "how do I roll back a bad release"
Expanding query... (0ms)
├─ how do I roll back a bad release
├─ lex: steps for rolling
├─ lex: best practices for rollback
├─ vec: steps for rolling back software releases
├─ vec: best practices for rollback management
└─ hyde: To roll back a bad release, start by reviewing the requirements and d...
Searching 6 queries...
 (4.4s)
Reranking 7 chunks... (28.2s)

qmd://docs/deploy-runbook.md:5 #000713 — Deploy runbook — 100%
qmd://notes/adr-2026-11-15.md:13 #ff3e50 — ADR: freeze deploys on Fridays — 40%
qmd://notes/incident-2026-11-10.md:3 #b9bf56 — Incident review — 2026-11-10 — 25%
qmd://docs/billing-migration.md:5 #8b613b — Billing migration plan — 15%
qmd://docs/onboarding.md:7 #c0df37 — Onboarding checklist — 12%

Total time: 33.1 seconds, of which 28.2 seconds was reranking. The reranker is what makes the result usable: the runbook jumps to 100% while the next result drops to 40% — compare with raw vector search, where the spread was 54% to 39% and the ranking was far less decisive.

The pipeline is slower than either mode alone — three model loads on CPU — but it is also the most forgiving of vague questions, because expansion adds the vocabulary your documents actually use. Two flags control the cost: --no-rerank skips the reranker and returns RRF scores (faster on CPU), and -C / --candidate-limit caps how many candidates reach the reranker (default 40).

You can also write the query document yourself, which is what agents should do. A typed query skips the expansion model entirely:

qmd query $'vec: rolling back a failed deployment' --no-rerank
Structured search: 1 queries (vec)
├─ vec: rolling back a failed deployment
└─ Searching...
 (6.5s)
qmd://docs/deploy-runbook.md:5 #000713
Title: Deploy runbook
Score: 100%

@@ -4,4 @@ (3 before, 1 after)

To roll back a bad deploy, run `deploy rollback --to <sha>` from the repo root. The rollback replays the previous healthy release and takes about 90 seconds.

The runbook is first at 100%, followed by the incident review at 50% and the billing migration at 33% — the ranking a human would produce. The same typed form is what the MCP server accepts, so the CLI and the agent path behave identically.

Diagram of the qmd query pipeline: question, query expansion, parallel BM25 and vector retrieval, reciprocal rank fusion, reranking, ranked results
The qmd query pipeline: expansion, parallel retrieval, RRF fusion, reranking. Diagram by AI Frontier Post.

Step 6 — Context and metadata filters#

Two v2.9.0 features make a large index manageable. First, context: short human-written descriptions attached to a collection or a path, returned with every result so an agent knows what it is looking at.

qmd context add qmd://docs "Engineering runbooks: deploys, auth, billing migration"
qmd context add qmd://notes "Team meeting notes and incident reviews"
qmd context list

Second, metadata filtering. Documents opt in with a namespaced frontmatter block — the frontmatter stays searchable content, it just also becomes filterable data:

---
qmd:
  metadata:
    topics:
      - deployment
      - reliability
    status: published
    priority: 4
---

# ADR: freeze deploys on Fridays

After qmd update and qmd embed (one new chunk, 7 seconds), qmd collection metadata notes reports every key with types and value counts — priority number, 1 of 3 documents, status string, published 1, topics string[], deployment 1, reliability 1. Filters are a JSON AST and work on every search surface:

qmd search "deploy freeze" --filter '{"field":"status","operator":"eq","value":"published"}'
qmd search "deploy freeze" --filter '{"field":"status","operator":"eq","value":"draft"}'

The first returns only the ADR (32%); the second returns No results found. Filters compose with and / or / not, comparisons (eq, gte, lt), membership (in, all), and text operators (contains, prefix). Every returned result satisfies the filter before fusion and reranking, so a filter cannot be outvoted by a high score.

Step 7 — Hand it to your agent: the MCP server#

The point of indexing your notes is that your agent can read them. QMD exposes an MCP server with five tools — query, get, multi_get, status, and metadata — over stdio or HTTP:

qmd mcp                    # stdio transport, for Claude Code / Claude Desktop
qmd mcp --http               # localhost:8181, shared long-lived server
qmd mcp --http --daemon      # background daemon; qmd mcp stop to end it

For Claude Code there is a plugin (claude plugin marketplace add tobi/qmd, then claude plugin install qmd@qmd); other clients take the manual mcpServers block from the README. The HTTP server binds loopback by default and rejects non-loopback Origin headers, which blocks DNS-rebinding reads from a web page.

Verified end to end with a small JSON-RPC client over stdio: initialize returns server qmd 2.9.0 with the instruction QMD is your local search engine over 7 markdown documents; tools/list returns exactly the five documented tools; status reports 7 documents, 0 needing embedding, vector index present; metadata returns the three keys with counts; and a typed query call (vec: rolling back a failed deployment, rerank off, limit 3) returns the runbook at 100%, the ADR at 50%, and the incident review at 33% — the same ranking as the CLI. The MCP query tool accepts the same typed search documents, so an agent that generates its own expansions never pays the 1.7B-model cost.

QMD also ships a bundled agent skill (qmd skills list, qmd skill show): a SKILL.md that teaches an agent the search-then-retrieve workflow — search for candidates, fetch the full source with qmd get, and answer from retrieved text rather than from snippets.

Step 8 — Measure it: qmd bench#

QMD ships a benchmark runner so you can measure retrieval quality on your own corpus instead of trusting it. A fixture is a JSON file of queries with expected files and a top-k requirement:

{
  "description": "Retrieval checks for the tutorial corpus",
  "version": 1,
  "queries": [
    {"id": "exact-rollback", "query": "deploy rollback --to", "type": "exact",
     "expected_files": ["deploy-runbook.md"], "expected_in_top_k": 1},
    {"id": "semantic-rollback", "query": "how do I undo a bad release", "type": "semantic",
     "expected_files": ["deploy-runbook.md"], "expected_in_top_k": 1},
    {"id": "exact-postgres", "query": "Postgres 16 migration", "type": "exact",
     "expected_files": ["billing-migration.md"], "expected_in_top_k": 1},
    {"id": "semantic-auth", "query": "how long do login tokens last", "type": "semantic",
     "expected_files": ["api-auth.md"], "expected_in_top_k": 3}
  ]
}

Five queries, four backends each, 3 minutes 20 seconds total. The summary:

Backend   P@k    R@1    R@3    R@5    MRR    F1     Avg
bm25      0.200  0.200  0.200  0.200  0.200  0.200  12ms
vector    1.000  1.000  1.000  1.000  1.000  1.000  939ms
hybrid    1.000  1.000  1.000  1.000  1.000  1.000  14,232ms
full      1.000  1.000  1.000  1.000  1.000  1.000  24,861ms

BM25 scored 1 of 5. It missed the exact rollback query because the query string contains --to: qmd search "deploy rollback --to" returns "No results found", while qmd search "deploy rollback" finds the runbook at 66% — the flag-like token kills the keyword match. Vector, hybrid, and full all scored a perfect 1.00 on every query and every metric. The cost is time: BM25 answers in about 12 ms, vector in about 1 s, hybrid in about 14 s, and the full reranked pipeline in about 25 s on this 2-core CPU VM. On a machine with a GPU the full pipeline is much faster — but on CPU, the reranker dominates the latency.

When to use QMD vs the alternatives#

ToolBest whenRetrievalAgent access
QMDYour knowledge lives in markdown and you want hybrid search + reranking, fully localBM25 + vectors + LLM expansion + rerankerMCP server (5 tools) + agent skill
XERJThe corpus is a codebase and the agent needs an Elasticsearch-compatible APIFull-text over code, reference codingMCP + Elasticsearch API
KensakuYou need desktop-wide file search with OCR over PDFs and imagesLocal file search + OCRMCP
sqlite-vecYou are building your own retrieval into an app and want a library, not a CLIVector search in SQLiteYour code
PageIndexYour documents are PDFs and you want reasoning-based retrieval without embeddingsTree index + keyword search + rerankingPython API
ripgrepYou know the exact string and want the fastest possible answerExact match onlyShell

The honest summary: if the corpus is code, XERJ's Elasticsearch-compatible API fits an agent's existing tooling better; if the corpus is PDFs, PageIndex's tree index is the stronger choice; if you are building retrieval into your own application, sqlite-vec is the component to use. QMD wins when the corpus is markdown notes and docs, you want all four retrieval stages without running a server or paying an API, and you want the same search available to your agent over MCP.

Limitations and honest caveats#

  • First-run downloads are the price of admission. The full pipeline needs ~2.25 GB of models. Keyword search works with none of them, and the typed-query form needs only the 318 MB embedding model — but the first vsearch or default query pulls the 1.7B expansion model, and the first default query also pulls the reranker. Tell readers that upfront.
  • CPU-only is slow. Embedding six short documents took minutes only because of the download; the 1.7B expansion model is the slow part on CPU, and every default query loads it. On a laptop with a GPU (Metal, CUDA, or Vulkan) it is faster; qmd doctor reports the device mode and warns when it is CPU-only.
  • Scores are relative, not absolute. A 58% BM25 score and a 100% vector score come from different normalizations; compare scores within one mode, not across modes. The --min-score default for vsearch is 0.3, which hides weak matches — raise -n or lower the threshold if a search comes back thin.
  • Metadata requires the frontmatter convention. Only documents with a qmd.metadata block are filterable; everything else indexes normally but cannot be filtered. qmd collection metadata shows what is actually indexed before you write a filter.
  • Model downloads show a progress bar but no timeout. During verification, a stalled download (the sandbox's disk quota interrupted writes) left the command waiting with no further output until it was killed and the download re-run. If a first-run download appears stuck, check ~/.cache/qmd/models/ and run qmd pull again.
  • qmd doctor checks presence, not integrity. It counts a model as cached when the file exists; a partial download can pass the check. Verify sizes against the README table (318 MB / 1.19 GiB / 610 MB) if a model-backed command misbehaves.

The takeaway#

QMD is the smallest honest answer to "my agent should be able to search my notes": one npm install, one qmd init, three search modes that go from instant keyword search to a full expand–fuse–rerank pipeline, and an MCP server that gives your agent the same retrieval you have in the terminal. The costs are explicit — ~2.25 GB of local models and CPU time on the first run — and the payoff is a search layer that works offline, keeps your notes on your machine, and returns the right paragraph first. Index your docs folder tonight; the next time your agent asks where the runbook is, it will already know.