Introduction to QMD
QMD (Query Markup Documents) is an on-device search engine for everything you need to remember. Index your markdown notes, meeting transcripts, documentation, and knowledge bases. Search with keywords or natural language—all running locally on your machine.What is QMD?
QMD combines three powerful search technologies into a single hybrid pipeline:- BM25 full-text search - Fast keyword matching using SQLite FTS5
- Vector semantic search - Understand meaning and context with embeddings
- LLM re-ranking - Intelligent result scoring for the most relevant matches
QMD is ideal for agentic workflows. Use the
--json and --files output formats to integrate with LLMs, or connect via the Model Context Protocol (MCP) server.Why Use QMD?
Privacy First
Your data never leaves your machine. All indexing, embeddings, and search happen locally.Built for AI Agents
QMD exposes structured output formats and an MCP server, making it perfect for:- Giving LLMs access to your knowledge base
- Building retrieval-augmented generation (RAG) systems
- Integrating with Claude Desktop, Claude Code, or custom agents
Hybrid Search Quality
By combining multiple search methods and using position-aware blending, QMD delivers better results than any single approach:- Keyword search finds exact matches and technical terms
- Vector search understands semantic similarity and synonyms
- Re-ranking uses LLM intelligence to score relevance
- Query expansion generates alternative phrasings to catch more results
Smart Context Management
Add descriptive context to collections and paths. QMD returns this context with matching documents, helping LLMs make better decisions about which content to use.Key Features
Multiple Search Modes
Choose from BM25 keyword search, vector semantic search, or full hybrid search with re-ranking.
Collection Management
Organize documents into named collections with custom glob patterns and context.
MCP Integration
Connect to Claude Desktop, Claude Code, or any MCP-compatible client.
Flexible Output
Export results as JSON, CSV, Markdown, XML, or file lists for downstream processing.
Smart Chunking
Documents are chunked at natural markdown boundaries (headings, code blocks) for better retrieval.
Document IDs
Every document gets a short hash ID (docid) for quick retrieval in search results.
How It Works
QMD’s hybrid search pipeline combines multiple retrieval methods:- Query Expansion - Generate alternative phrasings (original query weighted 2x)
- Parallel Retrieval - Each query searches both BM25 and vector indexes
- RRF Fusion - Combine results using Reciprocal Rank Fusion with top-rank bonuses
- Re-ranking - LLM scores top 30 candidates using yes/no with logprobs
- Position-Aware Blending - Preserve high-confidence matches while trusting re-ranker for lower ranks
Search Modes
- search
- vsearch
- query
BM25 Full-Text SearchFast keyword-based matching. Best for exact terms, technical identifiers, and when you know the specific words you’re looking for.
Score Interpretation
QMD normalizes all scores to a 0.0-1.0 range for consistent interpretation:| Score Range | Meaning |
|---|---|
| 0.8 - 1.0 | Highly relevant |
| 0.5 - 0.8 | Moderately relevant |
| 0.2 - 0.5 | Somewhat relevant |
| 0.0 - 0.2 | Low relevance |
Use Cases
Personal Knowledge Management
Index your markdown notes, journals, and research. Search across everything you’ve written with natural language queries.Meeting Intelligence
Index meeting transcripts and notes. Quickly find when topics were discussed, decisions made, or action items assigned.Documentation Search
Make your internal documentation searchable with semantic understanding. Find relevant docs even when they don’t use the exact terms in your query.AI Agent Memory
Give your AI agents access to a searchable knowledge base. Use the MCP server for tight integration or the CLI for scripted workflows.Next Steps
Installation
Install QMD and download the required models
Quick Start
Get your first search working in minutes