hjanuschka/pi-qmd/qmd-knowledge

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

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

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

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

1. Use appropriate search type:

• Keywords → qmd_search
• Concepts → qmd_vsearch
• Complex → qmd_query

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

1. 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:

``bash 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