tc9011/qmd

QMD - Quick Markdown Search

QMD is a local, on-device search engine for markdown content. It indexes your notes, meeting transcripts, documentation, and knowledge bases for fast retrieval.

QMD Status

!qmd status 2>/dev/null || echo "Not installed. Run: bun install -g https://github.com/tobi/qmd"

When to Use This Skill

• User asks to search their notes, documents, or knowledge base
• User needs to find information in their markdown files
• User wants to retrieve specific documents or search across collections
• User asks "what did I write about X" or "find my notes on Y"
• User needs semantic search (conceptual similarity) not just keyword matching
• User mentions meeting notes, transcripts, or documentation lookup

Search Commands

Choose the right search mode for the task:

| Command | Use When | Speed | |---------|----------|-------| | qmd search | Exact keyword matches needed | Fast | | qmd vsearch | Keywords aren't working, need conceptual matches | Medium | | qmd query | Best results needed, speed not critical | Slower |

# Fast keyword search (BM25)
qmd search "your query"

# Semantic vector search (finds conceptually similar content)
qmd vsearch "your query"

# Hybrid search with re-ranking (best quality)
qmd query "your query"

Common Options

-n <num>                 # Number of results (default: 5)
-c, --collection <name>  # Restrict to specific collection
--all                    # Return all matches
--min-score <num>        # Minimum score threshold (0.0-1.0)
--full                   # Show full document content
--json                   # JSON output for processing
--files                  # List files with scores
--line-numbers           # Add line numbers to output

Document Retrieval

# Get document by path
qmd get "collection/path/to/doc.md"

# Get document by docid (shown in search results as #abc123)
qmd get "#abc123"

# Get with line numbers for code review
qmd get "docs/api.md" --line-numbers

# Get multiple documents by glob pattern
qmd multi-get "docs/*.md"

# Get multiple documents by list
qmd multi-get "doc1.md, doc2.md, #abc123"

Index Management

# Check index status and available collections
qmd status

# List all collections
qmd collection list

# List files in a collection
qmd ls <collection-name>

# Update index (re-scan files for changes)
qmd update

Score Interpretation

| Score | Meaning | Action | |-------|---------|--------| | 0.8 - 1.0 | Highly relevant | Show to user | | 0.5 - 0.8 | Moderately relevant | Include if few results | | 0.2 - 0.5 | Somewhat relevant | Only if user wants more | | 0.0 - 0.2 | Low relevance | Usually skip |

Recommended Workflow

1. Check what's available: qmd status
2. Start with keyword search: qmd search "topic" -n 10
3. Try semantic if needed: qmd vsearch "describe the concept"
4. Use hybrid for best results: qmd query "question" --min-score 0.4
5. Retrieve full documents: qmd get "#docid" --full

Example: Finding Meeting Notes

# Search for meetings about a topic
qmd search "quarterly review" -c meetings -n 5

# Get semantic matches
qmd vsearch "performance discussion" -c meetings

# Retrieve the full meeting notes
qmd get "#abc123" --full

Example: Research Across All Notes

# Hybrid search for best results
qmd query "authentication implementation" --min-score 0.3 --json

# Get all relevant files for deeper analysis
qmd query "auth flow" --all --files --min-score 0.4

MCP Server Integration

This plugin configures the qmd MCP server automatically. When available, prefer MCP tools over Bash for tighter integration:

| MCP Tool | Equivalent CLI | Purpose | |----------|---------------|---------| | qmd_search | qmd search | Fast BM25 keyword search | | qmd_vsearch | qmd vsearch | Semantic vector search | | qmd_query | qmd query | Hybrid search with reranking | | qmd_get | qmd get | Retrieve document by path or docid | | qmd_multi_get | qmd multi-get | Retrieve multiple documents | | qmd_status | qmd status | Index health and collection info |

For manual MCP setup without the plugin, see references/mcp-setup.md.