Summary

QMD is an on-device, hybrid search engine designed for local documents such as notes, transcripts, and knowledge bases. It targets users and AI agents requiring fast, intelligent, and private search capabilities by seamlessly integrating keyword, semantic, and LLM re-ranking.

How It Works

QMD employs a sophisticated hybrid search pipeline. It indexes Markdown content using SQLite FTS5 for BM25 full-text search and generates vector embeddings for semantic search. Queries are expanded by an LLM, then retrieved in parallel via FTS and vector backends. Results are fused using Reciprocal Rank Fusion (RRF) with a top-rank bonus and position-aware blending, followed by LLM re-ranking for optimal relevance. This multi-stage approach balances speed, semantic understanding, and accuracy locally.

Quick Start & Requirements

Installation is via Bun: bun install -g https://github.com/tobi/qmd. Key requirements include:

• Bun runtime (>= 1.0.0).
• Ollama running locally (default: http://localhost:11434).
• macOS users need brew install sqlite.
• Specific Ollama models are auto-pulled: embeddinggemma, ExpedientFalcon/qwen3-reranker:0.6b-q8_0, qwen3:0.6b. Setup involves installing Bun, Ollama, and then running qmd add . on your directories.

Highlighted Details

• Hybrid Search Pipeline: Integrates BM25, vector search, LLM query expansion, and LLM re-ranking with advanced fusion techniques.
• Agent-Native Output: Provides --json, --files, and --md formats optimized for AI agent workflows.
• MCP Server: Exposes search functionalities as a protocol server for tighter application integration (e.g., Claude Desktop).
• Local-First Architecture: All search and LLM operations run entirely on-device, ensuring data privacy.

Maintenance & Community

The repository is maintained by tobi. No specific community channels (Discord/Slack), roadmap, or notable contributor information is provided in the README.

Licensing & Compatibility

QMD is released under the MIT License. This permissive license allows for broad use, including in commercial and closed-source applications, with minimal restrictions.

Limitations & Caveats

The project relies on the Bun runtime, which is less common than Node.js. macOS users require a specific Homebrew installation for SQLite. While designed for local use, it necessitates a running Ollama instance and downloading several LLM models, which can consume significant disk space and initial setup time.