tobi/qmd
ProductivityLocally indexes Markdown notes, meeting transcripts, and docs for keyword, semantic, and hybrid search, with CLI and MCP access for AI agents.
What it does
QMD is a local search engine for Markdown files: notes, meeting transcripts, documentation, and knowledge bases. It runs BM25 full-text search, vector semantic search, and LLM re-ranking on your machine through node-llama-cpp and GGUF models, so the index and model calls do not depend on a hosted search service (project overview).
Three search modes serve different needs: qmd search for fast keyword matching, qmd vsearch for semantic similarity, and qmd query for hybrid retrieval with query expansion and LLM re-ranking. Collections group directories, and context strings describe what each collection or path contains; that context travels with search results and helps an LLM pick the right document.
The same index can be reached through a CLI, a TypeScript SDK, or an MCP server, which is why the README positions it for agentic workflows as well as direct human use.
Quick start
Requires Node.js 22 or later or Bun 1.0 or later. On macOS, install Homebrew SQLite for extension support: brew install sqlite.
npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
qmd context add qmd://notes "Personal notes and ideas"
qmd embed
qmd search "project timeline"
qmd vsearch "how to deploy"
qmd query "quarterly planning process"
The first qmd embed downloads three GGUF models into ~/.cache/qmd/models/: an embedding model (~300 MB), a reranker (~640 MB), and a query-expansion model (~1.1 GB). The index itself is stored at ~/.cache/qmd/index.sqlite.
To connect an agent, install QMD as a Claude Code plugin with claude plugin marketplace add tobi/qmd and claude plugin install qmd@qmd, or launch the MCP server with qmd mcp. qmd mcp --http runs it on localhost:8181 for MCP clients that need a shared long-lived server.
Data and configuration
Each collection reads and writes entries in ~/.config/qmd/index.yml (or $XDG_CONFIG_HOME/qmd/index.yml). A project-local index created with qmd init lives under .qmd/ inside the project. Collections can define an update shell command that runs before qmd update re-indexes them, which is useful for pulling a git remote first.
A checked-in .qmd/index.yml is not trusted automatically: update commands, collection paths outside the project, and custom model URIs are gated and must be approved with qmd trust. Headless runs such as agents and CI skip those fields instead of executing them (trust behavior). The default embedding model is English-oriented; for CJK content, switch to a multilingual model such as Qwen3-Embedding via QMD_EMBED_MODEL and re-embed with qmd embed -f.
Resource and deployment constraints
Local inference means model downloads and disk usage are part of setup, and CPU-only machines will see slower embedding and re-ranking. Use --no-rerank for faster hybrid results, and --max-docs-per-batch or --max-batch-mb to bound memory during embedding on large corpora.
The MCP HTTP server is unauthenticated and checks Origin and Host headers to block DNS-rebinding access through a browser. Binding to 0.0.0.0 disables the host check unless QMD_ALLOWED_HOSTS is set, so any server reachable from another machine needs its own authentication layer in front.
The project is MIT-licensed.
HotRepo's take
QMD appeared on the TypeScript weekly chart in the week ending 2026-11-19 at rank 17, with 175 stars gained and 31,232 stars total (snapshot). The repository was created in December 2025, so that total represents very rapid growth rather than a long-running project.
On Hacker News, the author framed it as packing search-and-retrieval best practices into a local tool without overkill, and said work is ongoing on better fine-tuned query-expansion and reranking models (author comment). Commenters asked about local resource use and about large Obsidian vaults; one reply pointed to Omnisearch as the closest Obsidian equivalent rather than a QMD plugin (discussion). That matches what the README documents: QMD is a general Markdown indexer with CLI, SDK, and MCP access, not an Obsidian-specific integration.
Written by AI from the project's README, updated . The project's own docs are the source of truth.
Hacker News
You might also like
- Timaga/noda-local-ai-notesWindows local-first Markdown note app with knowledge graph, semantic search and cited-source chat.
- refactoringhq/tolariaA desktop and iOS app for editing markdown note vaults that stay as plain files in a git repository.
- jessepinkman9900/claude-second-brainScaffolds a Claude Code–maintained Obsidian wiki with local hybrid search and Git sync for personal knowledge management.
- fastrepl/anarlogA local-first AI meeting notepad that records device audio and keeps notes in local SQLite.
- yjid/kensakuA local desktop launcher that searches file names, document text, image OCR and meaning, and lets AI agents query the same index.