qmd – Data & Science skill for AI agents

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](https://github.com/tobi/qmd). 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):

| Model | Purpose | Size |

|-------|---------|------|

| embeddinggemma-300M-Q8_0 | Vector embeddings | ~300MB |

| qwen3-reranker-0.6b-q8_0 | Result reranking | ~640MB |

| qmd-query-expansion-1.7B | Query expansion | ~1.1GB |

Verify Installation

qmd --version
qmd status

Quick Reference

| Command | What It Does | Speed |

|---------|-------------|-------|

| qmd search "query" | BM25 keyword search (no models) | ~0.2s |

| qmd vsearch "query" | Semantic vector search (1 model) | ~3s |

| qmd query "query" | Hybrid + reranking (all 3 models) | ~2-3s warm, ~19s cold |

| qmd get <docid> | Retrieve full document content | instant |

| qmd multi-get "glob" | Retrieve multiple files | instant |

| qmd collection add <path> --name <n> | Add a directory as a collection | instant |

| qmd context add <path> "description" | Add context metadata to improve retrieval | instant |

| qmd embed | Generate/update vector embeddings | varies |

| qmd status | Show index health and collection info | instant |

| qmd mcp | Start MCP server (stdio) | persistent |

| qmd mcp --http --daemon | Start MCP server (HTTP, warm models) | persistent |

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)

| Syntax | Effect | Example |

|--------|--------|---------|

| term | Prefix match | perf matches "performance" |

| "phrase" | Exact phrase | "rate limiter" |

| -term | Exclude term | performance -sports |

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: mcp_qmd_search, mcp_qmd_vsearch,

mcp_qmd_deep_search, mcp_qmd_get, mcp_qmd_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

Then configure Hermes Agent to connect via HTTP:

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

Tradeoff: Uses ~2GB RAM while running, but every query is fast

(~2-3s). Best for users who search frequently.

Keeping the Daemon Running

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/Users/YOU/.hermes/cache/scratch/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/YOU/.hermes/cache/scratch/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd user service)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP Tools Reference

Once connected, these tools are available as mcp_qmd_*:

| MCP Tool | Maps To | Description |

|----------|---------|-------------|

| mcp_qmd_search | qmd search | BM25 keyword search |

| mcp_qmd_vsearch | qmd vsearch | Semantic vector search |

| mcp_qmd_deep_search | qmd query | Hybrid search + reranking |

| mcp_qmd_get | qmd get | Retrieve document by ID or path |

| mcp_qmd_status | qmd status | Index health and stats |

The MCP tools accept structured JSON queries for multi-mode search:

{
  "searches": [
    {"

… (full content is in the download package)