How do I use QMD as a tool, not a fragile shell wrapper?

Run the embedded [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server so agents can call it as tools and receive structured outputs; use --json/--files to keep responses minimal.

Why do search/vsearch/query return different results?

They are different pipelines: search optimizes exact keyword hits, vsearch optimizes semantic recall, and query fuses multiple signals and reranks to maximize answerable context.

How do I keep sensitive notes private?

Keep everything on-device: content is indexed in [SQLite](https://www.sqlite.org/) and semantic/rerank runs on local cached models. Also audit where you send outputs—shell history, scripts, and logs can leak more than the index.

QMD Deep Dive: Local Markdown Search, RAG Alternative

Pain Points vs Innovation

✕Traditional Pain Points	✓Innovative Solutions
With large Markdown corpora, grep/keyword search misses paraphrases and cross-section clues, which hurts agent context quality.	QMD uses a hybrid pipeline (FTS5/BM25 + vectors + local LLM reranking) to optimize recall and answerability as separate stages.
Agent integrations often either stuff raw text into context or rely on remote vector DBs, creating cost and privacy drift.	An embedded Model Context Protocol (MCP) server plus structured outputs lets agents fetch only the needed snippets instead of scanning everything.

Deployment Guide

1. Install prerequisites (requires Bun)

bash

1bun --version

2. Install QMD globally

bash

1bun install -g https://github.com/tobi/qmd

3. Add collections and build embeddings (first run downloads local model cache)

bash

1qmd collection add ~/notes --name notes && qmd embed

4. Search using the right mode

bash

1qmd search "auth"  # BM25\nqmd vsearch "login flow"  # vector\nqmd query "how to deploy"  # hybrid+rerank

5. Run the MCP server (tool interface for agents)

bash

1qmd mcp  # local stdio MCP server

Use Cases

Core Scene	Target Audience	Solution	Outcome
Local retrieval tool for Claude Code/desktop agents	individuals and teams using agents	index local notes and project docs and return structured JSON snippets	fewer wasted tokens and more grounded answers
Offline retrieval layer for private knowledge bases	security- and compliance-sensitive orgs	run hybrid retrieval and reranking on employee machines or internal hosts	better search and QA without shipping content to external vector DBs
Continuous indexing for meeting notes and logs	managers and engineers tracking decisions	organize transcripts and logs as collections with periodic updates	natural-language recall of what was decided and where it was written

QMD

QMD

What is it?

Pain Points vs Innovation

Architecture Deep Dive

Deployment Guide

1. Install prerequisites (requires Bun)

2. Install QMD globally

3. Add collections and build embeddings (first run downloads local model cache)

4. Search using the right mode

5. Run the MCP server (tool interface for agents)

Use Cases

Limitations & Gotchas

Frequently Asked Questions