tobi/qmd

QMD – Query Markup Documents

What it is

• A local, on‑device search engine for markdown‑style notes, transcripts, docs, and other knowledge bases.
• Combines three retrieval methods:
  1. BM25 full‑text (keyword) search.
  2. Vector semantic search using embeddings.
  3. LLM re‑ranking (via node‑llama‑cpp and GGUF models) to boost relevance.
• All components run locally; no external API calls are required.

Key concepts

• Typed sub‑queries – you can explicitly ask for a lexical (lex) search, a vector (vec) search, or a HyDE (hypothetical document) expansion. The system fuses results with Reciprocal Rank Fusion (RRF) and then optionally re‑ranks with an LLM.
• Contexts – hierarchical metadata you attach to collections (e.g., “Personal notes and ideas”). Context strings are returned with results, helping downstream agents make better decisions.
• MCP server – a lightweight Model Context Protocol server (stdio or HTTP) that lets other tools (Claude Desktop, custom agents) call QMD programmatically.

---

Quick start (CLI)

# install globally (Node or Bun)
npm install -g @tobilu/qmd   # or bun install -g @tobilu/qmd

# add collections (folders of markdown files)
qmd collection add ~/notes      --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs  --name docs

# give each collection a human‑readable context (optional but recommended)
qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://meetings "Meeting transcripts and notes"
qmd context add qmd://docs "Work documentation"

# generate embeddings for the vector backend
qmd embed

# search examples
qmd search "project timeline"               # fast BM25 keyword search
qmd vsearch "how to deploy"                # pure semantic search
qmd query "quarterly planning process"      # hybrid (BM25+vector) + LLM rerank

# retrieve a file
qmd get "meetings/2024-01-15.md"
qmd get "#abc123"                         # by internal doc‑id
qmd multi-get "journals/2025-05*.md"        # glob pattern

Agent‑friendly output

• --json returns structured data (file URIs, scores, snippets).
• --files adds the absolute file paths, useful for agents that need to open the source.

---

MCP server (programmatic access)

• Run qmd mcp --http to start a persistent HTTP server (default localhost:8181).
• Endpoints:
  • POST /mcp – full MCP stream protocol.
  • POST /query (alias /search) – same parameters as the CLI query tool, returns JSON with file fields like qmd://collection/path.
  • POST /metadata – discover available metadata keys/values.
  • GET /health – liveness check.
• Security: only loopback origins are accepted by default; you can relax this with QMD_ALLOWED_ORIGINS or QMD_ALLOWED_HOSTS.
• The server keeps LLM models loaded in VRAM across requests; embedding contexts are cleared after 5 min of inactivity.

---

SDK / library usage (Node/Bun)

npm install @tobilu/qmd

import { createStore } from '@tobilu/qmd'

const store = await createStore({
  dbPath: './my-index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
      notes: { path: '/path/to/notes' },
    },
  },
})

// Simple hybrid search (auto‑expansion + RRF + LLM rerank)
const results = await store.search({ query: 'authentication flow' })
console.log(results.map(r => `${r.title} (${(r.score*100).toFixed(0)}%)`))

await store.close()

The SDK mirrors the CLI capabilities:

• search, searchLex, searchVector for the three retrieval modes.
• get, multiGet for document retrieval.
• Collection management (addCollection, listCollections, …).
• Context handling (addContext, listContexts).
• Indexing (update) and embedding (embed).
• Rich TypeScript typings for all public objects.

---

When would you use QMD?

• Personal knowledge bases – keep all your markdown notes searchable without sending data to the cloud.
• Agentic workflows – LLM agents (e.g., Claude, Auto‑GPT) can call the MCP server to fetch relevant snippets or whole documents on‑the‑fly.
• Hybrid retrieval – you need both exact keyword matches and semantic similarity, with an optional LLM reranker for top‑quality results.
• Self‑hosted environments – any situation where data privacy or offline operation is a requirement.

---

TL;DR

QMD is a locally‑run, hybrid search engine for markdown‑based knowledge collections. It blends BM25, vector similarity, and LLM reranking, offers a CLI, an HTTP/MCP server for agents, and a full TypeScript SDK for embedding in your own applications.