QMD Knowledge Management

QMD (Quick Markdown Search) is an on-device search engine for your knowledge base. It indexes markdown notes, meeting transcripts, documentation, and more, providing fast keyword search, semantic search, and hybrid search with LLM reranking.

Available Tools

Tool Best For Speed

qmd_search

Exact keywords, known terms Fast

qmd_vsearch

Conceptual queries, fuzzy matching Medium

qmd_query

Best quality, complex questions Slower

qmd_get

Retrieve full document content Fast

qmd_multi_get

Get multiple docs at once Fast

qmd_status

Check index health Fast

Search Strategy

1. Start with the right search type

Use qmd_search when:

• User mentions specific terms they know exist

• Looking for exact matches (error codes, function names, dates)

• Need fast results

Use qmd_vsearch when:

• Query is conceptual ("how do I deploy", "authentication flow")

• User's words may differ from document terms

• Looking for related content

Use qmd_query when:

• Need highest quality results

• Complex or ambiguous queries

• First two methods returned poor results

2. Retrieve relevant documents

After searching, use qmd_get with the path or docid to fetch full content:

By path (from search results)

qmd_get { "path": "notes/meeting-2024-01-15.md" }

By docid (the #xxx from results)

qmd_get { "path": "#abc123" }

Multiple documents

qmd_multi_get { "pattern": "docs/api/*.md" }

3. Refine if needed

• If results are too broad: add collection filter (collection: "notes" )

• If results are too few: try semantic search or lower minScore

• If results are irrelevant: use hybrid qmd_query

Search Examples

Finding meeting notes

qmd_search { "query": "quarterly planning 2024", "collection": "meetings" }

Finding how-to documentation

qmd_vsearch { "query": "how to set up CI/CD pipeline" }

Complex lookup

qmd_query { "query": "authentication flow for API users" }

Getting specific content

qmd_get { "path": "#a1b2c3", "full": true }

Understanding Results

Search results include:

• path: File path relative to collection

• docid: Short hash (use with qmd_get #xxx )

• title: Document title (from first heading)

• context: Collection/path context description

• score: Relevance 0-100% (green >70%, yellow >40%)

• snippet: Matching excerpt with context

Collections

Users organize content into collections. Check what's available:

qmd_status {}

Common collections:

• notes

• Personal notes

• docs

• Documentation

• meetings

• Meeting transcripts

• work

• Work-related content

Filter searches by collection when user's intent is clear.

Best Practices

Start broad, then narrow: Begin with qmd_query if unsure, refine with filters

Combine tools: Search first, then qmd_get to retrieve full content

Use appropriate search type:

• Keywords → qmd_search

• Concepts → qmd_vsearch

• Complex → qmd_query

Check status first: If searches fail, qmd_status can reveal issues

Respect user's collections: Don't search everywhere if user mentions specific notes

Troubleshooting

"No results found":

• Try semantic search (qmd_vsearch )

• Lower or remove minScore

• Check qmd_status for collection names

"Embeddings not ready":

• User needs to run qmd embed

• qmd_search still works (BM25 only)

"Command not found":

• QMD not installed

• QMD requires Bun runtime

• Tell user to install Bun first, then QMD: brew install oven-sh/bun/bun bun install -g https://github.com/tobi/qmd

Installation & Setup (for users)

Install Bun (required runtime for QMD)

brew install oven-sh/bun/bun

Install QMD

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

Add collections

qmd collection add ~/notes --name notes qmd collection add ~/Documents/meetings --name meetings

Generate embeddings (for semantic search)

qmd embed

Quick Reference

Keyword search

qmd search "API authentication"

Semantic search

qmd vsearch "how to log in"

Hybrid (best quality)

qmd query "user auth flow"

Get document

qmd get "docs/api.md" qmd get "#abc123"

Multiple documents

qmd multi-get "journals/2025-05*.md"

Status

qmd status