irfanfaraaz/claude-kit/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 or load other skills: When skills directories (e.g. ~/.cursor/skills/, ~/.agents/skills/) are indexed as a qmd collection, use qmd query or qmd vsearch to find skills by topic and qmd get to read SKILL.md content. Works with the skill-loader and load-skills command.

Search Commands

Choose the right search mode for the task:

# 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

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:

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