QMD (Query Markup Documents)

QMD is an on-device search engine designed for indexing markdown notes, meeting transcripts, documentation, and knowledge bases. It is optimized for agentic workflows by combining three search technologies:

1. BM25 full-text search for keyword matching.
2. Vector semantic search for natural language understanding.
3. LLM re-ranking to refine results.

All search components run locally using node-llama-cpp with GGUF models, ensuring privacy and low latency.

The qmd-finetune package allows you to train small language models (like Qwen/Qwen3-1.7B) to expand raw search queries into structured formats compatible with QMD's hybrid retrieval pipeline.

The model produces three types of expansions:

• lex:: Short, keyword-focused lines for BM25 full-text search.
• vec:: Natural language phrases for vector similarity search.
• hyde:: A hypothetical document passage for embedding-based retrieval.

Example output for a query like "auth config":

hyde: Authentication can be configured by setting the AUTH_SECRET environment variable.
lex: authentication configuration
lex: auth settings setup
vec: how to configure authentication settings
vec: authentication configuration options

QMD stores its index in a SQLite database located at ~/.cache/qmd/index.sqlite. The schema is organized into several specialized tables to support hybrid search:

• collections: Stores indexed directories with their names and glob patterns.
• path_contexts: Stores context descriptions mapped to virtual paths (qmd://...).
• documents: Contains Markdown content, metadata, and a 6-character docid hash.
• documents_fts: A Full-Text Search (FTS5) index for keyword matching.
• content_vectors: Stores embedding chunks (approx. 900 tokens each) with hash, seq, and pos metadata.
• vectors_vec: A sqlite-vec vector index using hash_seq keys.
• llm_cache: Caches LLM responses for query expansion and rerank scores.

QMD uses a sophisticated hybrid search and re-ranking pipeline to return high-quality results:

1. LLM Expansion: The original query is expanded into multiple variants.
2. Dual Search: For each query variant, QMD performs both Vector Search and FTS (BM25) Full-Text Search.
3. RRF Fusion: Results from both searches are fused using Reciprocal Rank Fusion (RRF) with $k=60$. The original query is given $\times 2$ weight.
4. LLM Re-ranking: The top 30 candidates are passed to an LLM reranker to confirm relevance.
5. Position-Aware Blend: The final results are a weighted blend of RRF and reranker scores, where the weight of the reranker increases as the rank decreases (Rank 1-3 is 25% reranker, Rank 11+ is 60% reranker).

QMD queries are structured documents that allow you to combine different search methodologies in a single request. You can use three primary search types:

• lex: Keyword search using BM25 for exact matching and prefix support.
• vec: Semantic similarity search using natural language questions.
• hyde: Hypothetical Document Embedding. You provide a 50-100 word passage describing what you expect the answer to look like.

Queries can be a single-line 'expand query' (which automatically generates all three types) or a multi-line 'query document' where you explicitly define each line with a type prefix.

lex: CAP theorem consistency
vec: how does the rate limiter handle burst traffic
hyde: The rate limiter uses a sliding window algorithm with a 60-second window...

The intent: line provides background context to disambiguate queries (e.g., distinguishing between 'performance' in web vitals vs. team health).

Rules for Intent:

• At most one intent: line per query document.
• It cannot appear alone; it must be accompanied by at least one lex:, vec:, or hyde: line.
• It steers expansion, reranking, and snippet extraction but does not perform a search itself.
• Can be provided inline in a query document, via the --intent CLI flag, or via the intent parameter in MCP.

intent: web page load times and Core Web Vitals
lex: performance
vec: how to improve performance

When generating query expansions for retrieval optimization, use a prefixed line format. Each line must start with a specific prefix indicating its purpose.

Example Output:

hyde: Authentication can be configured by setting the AUTH_SECRET environment variable and enabling the auth middleware in your application's config file.
lex: authentication configuration
lex: auth settings setup
vec: how to configure authentication settings
vec: authentication configuration options

A key feature of QMD is the ability to add hierarchical context to collections or specific paths. This context is returned alongside matching sub-documents, helping LLMs make better contextual choices when selecting documents.

Use qmd context add <qmd_uri> "<context_string>" to add context.

Example:

qmd context add qmd://notes "Personal notes and ideas"

qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://meetings "Meeting transcripts and notes"
qmd context add qmd://docs "Work documentation"