@tobilu/qmd weekly downloads statistics

QMD - Query Markup Documents

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. Ideal for your agentic flows.

QMD combines BM25 full-text search, vector semantic search, and LLM re-ranking—all running locally via node-llama-cpp with GGUF models.

Typed expansions are routed exclusively: lex → BM25/FTS, vec and hyde → vector search. The original query is sent to both backends, then fused with RRF and reranked.

You can read more about QMD's progress in the CHANGELOG.

Quick Start

Using with AI Agents

QMD's --json and --files output formats are designed for agentic workflows:

MCP Server

Although the tool works perfectly fine when you just tell your agent to use it on the command line, it also exposes an MCP (Model Context Protocol) server for tighter integration.

Tools exposed: • query — Search with typed sub-queries (lex/vec/hyde), combined via RRF + reranking • get — Retrieve a document by path or docid (with fuzzy matching suggestions) • multi_get — Batch retrieve by glob pattern, comma-separated list, or docids • status — Index health and collection info

Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

Claude Code — Install the plugin (recommended):

Or configure MCP manually in ~/.claude/settings.json:

HTTP Transport

By default, QMD's MCP server uses stdio (launched as a subprocess by each client). For a shared, long-lived server that avoids repeated model loading, use the HTTP transport:

The server binds to localhost by default. Pass --host (or set the QMD_HOST environment variable) to override — --host 0.0.0.0 is useful when the server runs in a container and a liveness probe connects from a non-loopback address.

The HTTP server exposes two endpoints: • POST /mcp — MCP Streamable HTTP (JSON responses, stateless) • POST /query (alias /search) — structured search without the MCP protocol • GET /health — liveness check with uptime

Origin and Host validation

Every request is screened before routing: a request carrying an Origin header that does not name a loopback address is rejected with 403, as is a Host header naming something other than the address the server is bound to. This is what stops a web page you visit from reading your index through DNS rebinding — loopback binding alone does not, since the browser makes the request from your own machine.

Requests without an Origin header — curl, MCP clients, editors — are unaffected, which covers every normal local client.

| Variable | Effect |

| QMD_ALLOWED_ORIGINS | Comma-separated origins to accept in addition to loopback, e.g. https://notes.internal. Set to * to disable the check entirely. | | QMD_ALLOWED_HOSTS | Comma-separated Host values to accept in addition to loopback and the bind address. |

--host 0.0.0.0 cannot know which Host values are legitimate, so it skips the host check and warns at startup. Set QMD_ALLOWED_HOSTS to re-enable it, and remember the endpoints are unauthenticated — put your own auth in front of a server that is reachable off-host.

LLM models stay loaded in VRAM across requests. Embedding/reranking contexts are disposed after 5 min idle and transparently recreated on the next request (~1s penalty, models remain loaded).

Point any MCP client at http://localhost:8181/mcp to connect.

MCP Tool Parameters

| Tool | Parameter | Type | Notes |

| query | searches | array | Typed sub-queries (lex/vec/hyde), 1–10. Required. First gets 2x weight. | | query | collections | string[] | Filter by collection names (OR). Array only — singular collection is silently ignored. | | query | intent | string | Disambiguation context (does not search on its own) | | query | limit | number | Max results (default 10) | | query | minScore | number | Minimum relevance 0–1 (default 0) | | query | candidateLimit | number | Max candidates to rerank (default 40) | | query | rerank | boolean | Run LLM reranking (default true); set false for RRF-only | | get | file | string | Path, docid (#abc123), or path:from:count (e.g. #abc123:120:40) | | get | fromLine | number | Start line (1-indexed); overrides the :from suffix | | get | maxLines | number | Limit returned lines | | get | lineNumbers | boolean | Prefix lines with numbers (default true) | | multi_get | pattern | string | Glob pattern or comma-separated list | | multi_get | maxBytes | number | Skip files larger than N (default 10240) | | multi_get | maxLines | number | Limit lines per file | | multi_get | lineNumbers | boolean | Prefix lines with numbers (default true) |

Unknown parameters are silently ignored (not rejected) — double-check names if results seem unscoped. The HTTP /query and /search endpoints return qmd://collection/path URIs in the file field, matching the CLI and MCP output.

SDK / Library Usage

Use QMD as a library in your own Node.js or Bun applications.

Installation

Quick Start

Store Creation

createStore() accepts three modes:

Search

The unified search() method handles both simple queries and pre-expanded structured queries:

For direct backend access:

Retrieval

Collections

Context

Context adds descriptive metadata that improves search relevance and is returned alongside results:

Indexing

Types

Key types exported for SDK consumers:

Utility exports:

Lifecycle

The SDK requires explicit dbPath — no defaults are assumed. This makes it safe to embed in any application without side effects.

Architecture

Score Normalization & Fusion

Search Backends

| Backend | Raw Score | Conversion | Range |

| FTS (BM25) | SQLite FTS5 BM25 | Math.abs(score) | 0 to ~25+ | | Vector | Cosine distance | 1 / (1 + distance) | 0.0 to 1.0 | | Reranker | LLM 0-10 rating | score / 10 | 0.0 to 1.0 |

Fusion Strategy

The query command uses Reciprocal Rank Fusion (RRF) with position-aware blending:…

Description from the npm listing.