qmd - Quick Markdown Search

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

When to use (trigger phrases)

• "search my notes / docs / knowledge base"
• "find related notes"
• "retrieve a markdown document from my collection"
• "search local markdown files"

Default behavior (important)

• Prefer

  qmd search

  (BM25). It's typically instant and should be the default.
• Use

  qmd vsearch

  only when keyword search fails and you need semantic similarity (can be very slow on a cold start).
• Avoid

  qmd query

  unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes/timeouts.

Search modes

qmd search

qmd vsearch

qmd query

Common commands

qmd search "query"              # default - fast keyword search
qmd search "query" -c notes     # search specific collection
qmd search "query" -n 10        # more results
qmd search "query" --json       # JSON output
qmd search "query" --all --files --min-score 0.3

Useful options

• -n <num>

  : number of results

• -c, --collection <name>

  : restrict to a collection

• --all --min-score <num>

  : return all matches above a threshold

• --json

  /

  --files

  : agent-friendly output formats

• --full

  : return full document content

Retrieve documents

qmd get "path/to/file.md"       # Full document
qmd get "#docid"                # By ID from search results
qmd multi-get "journals/2025-05*.md"
qmd multi-get "doc1.md, doc2.md, #abc123" --json

Maintenance

qmd status                      # Index health
qmd update                      # Re-index changed files
qmd embed                       # Update embeddings

Setup (if not installed)

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

# Create collection
qmd collection add /path/to/notes --name notes --mask "**/*.md"
qmd context add qmd://notes "Description of this collection"  # optional
qmd embed  # one-time to enable vector + hybrid search

Performance notes

• qmd search

  is typically instant

• qmd vsearch

  can be ~1 minute on cold start (loads local LLM for query expansion)

• qmd query

  adds LLM reranking on top of

  vsearch

  , even slower

Common Pitfalls

Search query too vague (irrelevant results)

Problem: Broad queries like "notes" or "project" return hundreds of low-relevance matches.

Solution:

• Use specific keywords:

  qmd search "Python async context managers"

  not

  qmd search "Python"

• Combine keywords:

  qmd search "deadline March quarterly review"

• Use quotes for exact phrases:

  qmd search "exact phrase match"

• Check result scores:

  qmd search "query" --all --min-score 0.5

  to filter low-confidence matches

Index not updated (missing recent files)

Problem: Newly created or recently modified files don't appear in search results.

Solution:

# Check index status
qmd status

# Re-index all changed files
qmd update

# Full re-index if update doesn't help
qmd collection remove <name>
qmd collection add /path/to/notes --name <name> --mask "**/*.md"
qmd embed  # if vector search enabled

Path filters wrong (excluding relevant directories)

Problem: Search doesn't find files because the collection mask is too narrow or collection path is wrong.

Solution:

# List current collections
qmd status

# Verify collection path matches your notes location
# If path changed, re-add collection:
qmd collection remove <old-name>
qmd collection add /path/to/notes --name <name> --mask "**/*.md"

# Common issue: subdirectories excluded by mask
# If notes are in journals/2025/*, use: --mask "**/*.md"
# Not: --mask "*.md" (which only matches top level)

Search timeout on large vaults (performance issues)

Problem:

qmd query

qmd vsearch

Solution:

• Avoid

  qmd query

  on large vaults (LLM reranking is too slow)
• Use

  qmd search

  instead (BM25 is fast even on huge collections)
• If semantic search needed, use

  qmd vsearch

  with

  -n 5

  to limit results
• Restrict search scope with

  -c <collection>

  to search one collection instead of all:

  qmd search "query" -c notes -n 5  # faster than searching all collections
  

• If vault exceeds 5000 files, consider splitting into multiple collections

Missing configuration (qmd not initialized)

Problem:

qmd status

qmd search

Solution:

# Install qmd if missing
bun install -g https://github.com/tobi/qmd

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

# Enable vector search (optional but recommended)
qmd embed

# Verify setup
qmd status  # Should show your collection with file count

Semantic search returns irrelevant results (vsearch/query)

Problem: Vector search matches by topic but misses what you actually wanted.

Solution:

• Fall back to

  qmd search

  (BM25 keyword matching is more precise for specific terms)
• Rephrase query to include actual keywords: not "What are my goals?" but "goals quarterly review objectives"
• Use

  qmd query

  if available (adds LLM reranking), but only if you can tolerate slow runtime
• Use

  -n 3

  to get fewer, higher-confidence matches from vector search