qmd-knowledge

name	qmd-knowledge
description	Knowledge management with QMD (Quick Markdown Search). Search, retrieve, and organize your personal knowledge base, notes, docs, and meeting transcripts. Use when asking about past notes, documentation, meetings, or when needing to recall information from your indexed markdown files.
license	See https://github.com/hjanuschka/pi-qmd

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

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

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

3. Use appropriate search type:

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

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

5. 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