QMD (Query Markup Documents) is an on-device search engine for markdown notes, meeting transcripts, documentation, and knowledge bases. You group folders into named collections, attach descriptive context to collections and paths, and search them by keyword or natural language from a CLI, an MCP server, or a TypeScript library.
Search combines BM25 full-text search (SQLite FTS5), vector semantic search, and LLM re-ranking, all running locally through node-llama-cpp with GGUF models. A query is expanded into typed sub-queries (lex for keywords, vec for dense sentences, hyde for hypothetical documents), sent to both backends, fused with Reciprocal Rank Fusion, and re-ranked. Position-aware blending gives retrieval scores more weight for the top few results so the reranker does not bury exact matches.
Three local models handle the pipeline, downloaded from Hugging Face on first use:
| Model | Purpose | Size |
|---|---|---|
| embeddinggemma-300M-Q8_0 | Vector embeddings (default) | ~300MB |
| qwen3-reranker-0.6b-q8_0 | Re-ranking | ~640MB |
| qmd-query-expansion-1.7B-q4_k_m | Query expansion (fine-tuned) | ~1.1GB |
Each model role can be overridden, and Qwen3-Embedding is a supported alternative embedding family for multilingual (including CJK) content. Context entries attached to collections are returned alongside matching documents so an agent can judge where a result came from.
The output formats target agent workflows: JSON results, file lists above a score threshold, and full-document retrieval by path, document ID, or glob. The MCP server exposes query, get, multi_get, status, and metadata tools over stdio or a shared HTTP transport that keeps models loaded between requests. QMD is also packaged as a Claude Code plugin.
Features
- Hybrid search: BM25 keyword search, vector similarity search, and a full pipeline with query expansion, RRF fusion, and LLM re-ranking
- Local models: embedding, re-ranking, and query-expansion GGUF models run on device through node-llama-cpp
- Collections and context: index folders as named collections and attach tree-structured context that returns with matching documents
- Smart chunking: splits markdown at scored natural break points such as headings and code fences, with tree-sitter AST chunking for TypeScript, JavaScript, Python, Go, and Rust
- Metadata filtering: filter results on indexed front-matter metadata and discover keys, types, and value counts
- MCP server: query, get, multi_get, status, and metadata tools over stdio or HTTP, plus plain HTTP search and metadata endpoints
- Agent output formats: JSON, file lists with minimum scores, markdown, and full-document retrieval for feeding an LLM
- TypeScript SDK: create a store, manage collections and context, and call search, lexical, vector, and retrieval methods from Node.js or Bun
- Benchmarking: a bench command reports precision@k, recall, MRR, and F1 across the bm25, vector, hybrid, and full backends
- Editor links: search results link to documents in VS Code, Cursor, Zed, or Sublime Text
