qmd skill

QMD — Query Markup Documents

Local, on-device search engine for personal knowledge bases. Indexes markdown notes, meeting transcripts, documentation, and any text-based files, then provides hybrid search combining keyword matching, semantic understanding, and LLM-powered reranking — all running locally with no cloud dependencies.

Created by Tobi Lütke. MIT licensed.

When to Use

• User asks to search their notes, docs, knowledge base, or meeting transcripts
• User wants to find something across a large collection of markdown/text files
• User wants semantic search ("find notes about X concept") not just keyword grep
• User has already set up qmd collections and wants to query them
• User asks to set up a local knowledge base or document search system
• Keywords: "search my notes", "find in my docs", "knowledge base", "qmd"

Prerequisites

Node.js >= 22 (required)

# Check version
node --version  # must be >= 22

# macOS — install or upgrade via Homebrew
brew install node@22

# Linux — use NodeSource or nvm
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# or with nvm:
nvm install 22 && nvm use 22

SQLite with Extension Support (macOS only)

macOS system SQLite lacks extension loading. Install via Homebrew:

brew install sqlite

Install qmd

npm install -g @tobilu/qmd
# or with Bun:
bun install -g @tobilu/qmd

First run auto-downloads 3 local GGUF models (~2GB total):

Verify Installation

qmd --version
qmd status

Quick Reference

Setup Workflow

1. Add Collections

Point qmd at directories containing your documents:

# Add a notes directory
qmd collection add ~/notes --name notes

# Add project docs
qmd collection add ~/projects/myproject/docs --name project-docs

# Add meeting transcripts
qmd collection add ~/meetings --name meetings

# List all collections
qmd collection list

2. Add Context Descriptions

Context metadata helps the search engine understand what each collection contains. This significantly improves retrieval quality:

qmd context add qmd://notes "Personal notes, ideas, and journal entries"
qmd context add qmd://project-docs "Technical documentation for the main project"
qmd context add qmd://meetings "Meeting transcripts and action items from team syncs"

3. Generate Embeddings

qmd embed

This processes all documents in all collections and generates vector embeddings. Re-run after adding new documents or collections.

4. Verify

qmd status   # shows index health, collection stats, model info

Search Patterns

Fast Keyword Search (BM25)

Best for: exact terms, code identifiers, names, known phrases. No models loaded — near-instant results.

qmd search "authentication middleware"
qmd search "handleError async"

Semantic Vector Search

Best for: natural language questions, conceptual queries. Loads embedding model (~3s first query).

qmd vsearch "how does the rate limiter handle burst traffic"
qmd vsearch "ideas for improving onboarding flow"

Hybrid Search with Reranking (Best Quality)

Best for: important queries where quality matters most. Uses all 3 models — query expansion, parallel BM25+vector, reranking.

qmd query "what decisions were made about the database migration"

Structured Multi-Mode Queries

Combine different search types in a single query for precision:

# BM25 for exact term + vector for concept
qmd query $'lex: rate limiter\nvec: how does throttling work under load'

# With query expansion
qmd query $'expand: database migration plan\nlex: "schema change"'

Query Syntax (lex/BM25 mode)

HyDE (Hypothetical Document Embeddings)

For complex topics, write what you expect the answer to look like:

qmd query $'hyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'

Scoping to Collections

qmd search "query" --collection notes
qmd query "query" --collection project-docs

Output Formats

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP Integration (Recommended)

qmd exposes an MCP server that provides search tools directly to Hermes Agent via the native MCP client. This is the preferred integration — once configured, the agent gets qmd tools automatically without needing to load this skill.

Option A: Stdio Mode (Simple)

Add to ~/.hermes/config.yaml:

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

This registers tools: mcpqmdsearch, mcpqmdvsearch, mcpqmddeepsearch, mcpqmdget, mcpqmd_status.

Tradeoff: Models load on first search call (~19s cold start), then stay warm for the session. Acceptable for occasional use.

Option B: HTTP Daemon Mode (Fast, Recommended for Heavy Use)

Start the qmd daemon separately — it keeps models warm in memory:

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default