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

qmd-knowledge