qmd - Local Markdown Search

Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast. Use instead of

find

Installation

bun install -g https://github.com/tobi/qmd

Setup

# Add a collection
qmd collection add /path/to/your/notes --name notes --mask "**/*.md"

# Generate embeddings (required for vsearch/query)
qmd embed

# List your collections
qmd collection list

When to Use

• "search my notes / docs / knowledge base"
• "find related notes"
• "find files matching [pattern]" — use instead of

  find

  to avoid hangs on large directories
• "what did we decide about X?"

Default Behavior (important)

• Prefer

  qmd search

  (BM25) — it's instant and should be the default.
• Use

  qmd vsearch

  only when keyword search fails and you need semantic similarity.
• Avoid

  qmd query

  unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes.
• Always use

  --json

  flag for structured output when invoking from an agent.

Search Commands

# Fast keyword search (default)
qmd search "authentication flow" --json
qmd search "config" --json -c notes

# Semantic search (slower, for conceptual queries)
qmd vsearch "how does login work" --json
qmd vsearch "best practices for error handling" --json -n 20

# Combined with reranking (best quality, slowest)
qmd query "implementing user auth" --json
qmd query "deployment process" --json --min-score 0.5

Search Mode Selection

search

vsearch

query

Search Options

-n NUM

-c, --collection

--min-score NUM

--full

--json

--files

--all

Retrieve Documents

# Get full file
qmd get docs/guide.md --json

# Get by document hash ID
qmd get "#a1b2c3" --json

# Get specific lines
qmd get notes/meeting.md:50 -l 30 --json

# Get multiple files by glob
qmd multi-get "docs/*.md" --json
qmd multi-get "*.yaml" -l 50 --max-bytes 10240

Output Formats

• --files

  — paths + scores (for file discovery)

• --json

  — structured with snippets

• --md

  — markdown formatted

• -n 10

  — limit results

Maintenance

qmd update              # Re-index changed files
qmd status              # Check index health
qmd collection list     # List all collections

Keeping Index Fresh

# Hourly incremental updates (BM25):
0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update

# Optional: nightly embedding refresh:
0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed

MCP Server

qmd can run as an MCP server for direct agent integration:

qmd mcp

Exposes tools:

qmd_search

qmd_vsearch

qmd_query

qmd_get

qmd_multi_get

qmd_status

Performance

• qmd search

  is typically instant.

• qmd vsearch

  can take ~1 minute on first run (loads local LLM).

• qmd query

  adds LLM reranking — can be slow, avoid for interactive use.

Models (auto-downloaded)

All run locally — no API keys needed.

• Embedding: embeddinggemma-300M
• Reranking: qwen3-reranker-0.6b
• Generation: Qwen3-0.6B
• Cache location:

  ~/.cache/qmd/models/

• Override with

  XDG_CACHE_HOME

  environment variable.