Qmd

QMD - Quick Markdown Search

Local search engine for markdown content.

Status

!qmd status 2>/dev/null || echo "Not installed: npm install -g @tobilu/qmd"

MCP: query

{
  "searches": [
    { "type": "lex", "query": "CAP theorem consistency" },
    { "type": "vec", "query": "tradeoff between consistency and availability" }
  ],
  "collections": ["docs"],
  "limit": 10
}

Query Types

Writing Good Queries

lex (keyword)

• 2-5 terms, no filler words
• Exact phrase: "connection pool" (quoted)
• Exclude terms: performance -sports (minus prefix)
• Code identifiers work: handleError async

vec (semantic)

• Full natural language question
• Be specific: "how does the rate limiter handle burst traffic"
• Include context: "in the payment service, how are refunds processed"

hyde (hypothetical document)

• Write 50-100 words of what the answer looks like
• Use the vocabulary you expect in the result

expand (auto-expand)

• Use a single-line query (implicit) or expand: question on its own line
• Lets the local LLM generate lex/vec/hyde variations
• Do not mix expand: with other typed lines — it's either a standalone expand query or a full query document

Intent (Disambiguation)

When a query term is ambiguous, add intent to steer results:

{
  "searches": [
    { "type": "lex", "query": "performance" }
  ],
  "intent": "web page load times and Core Web Vitals"
}

Intent affects expansion, reranking, chunk selection, and snippet extraction. It does not search on its own — it's a steering signal that disambiguates queries like "performance" (web-perf vs team health vs fitness).

Combining Types

First query gets 2x weight in fusion — put your best guess first.

Lex Query Syntax

Note: -term only works in lex queries, not vec/hyde.

Collection Filtering

{ "collections": ["docs"] }              // Single
{ "collections": ["docs", "notes"] }     // Multiple (OR)

Omit to search all collections.

Other MCP Tools

MCP Client Config

Claude Code:

{
  "mcpServers": {
    "qmd": { "command": "qmd", "args": ["mcp"] }
  }
}

User-scope Claude Code alternative:

claude mcp add --transport stdio --scope user qmd -- qmd mcp

Codex:

[mcp_servers.qmd]
command = "qmd"
args = ["mcp"]

OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "qmd": {
      "type": "local",
      "command": ["qmd", "mcp"],
      "enabled": true
    }
  }
}

CLI

qmd query "question"              # Auto-expand + rerank
qmd query $'lex: X\nvec: Y'       # Structured
qmd query $'expand: question'     # Explicit expand
qmd query --json --explain "q"    # Show score traces (RRF + rerank blend)
qmd search "keywords"             # BM25 only (no LLM)
qmd get "#abc123"                 # By docid
qmd multi-get "journals/2026-*.md" -l 40  # Batch pull snippets by glob
qmd multi-get notes/foo.md,notes/bar.md   # Comma-separated list, preserves order
qmd collection add ~/notes --name notes --mask "**/*.md"
qmd context add qmd://notes "Personal notes and project memory"
qmd update                         # Re-index all collections
qmd embed                          # Generate or refresh vector embeddings
qmd status                         # Show collections, files, vectors

HTTP API

curl -X POST http://localhost:8181/query \
  -H "Content-Type: application/json" \
  -d '{"searches": [{"type": "lex", "query": "test"}]}'

Setup

npm install -g @tobilu/qmd  # requires Node 22+
# or: bun install -g @tobilu/qmd
qmd collection add ~/notes --name notes --mask "**/*.md"
qmd context add qmd://notes "Personal notes and project memory"
qmd update
qmd embed