qmd

QMD Search Skill

Search markdown knowledge bases efficiently using qmd, a local indexing tool that uses BM25 + vector embeddings to return only relevant snippets instead of full files.

Why Use This

• 96% token reduction - Returns relevant snippets instead of reading entire files
• Instant results - Pre-indexed content means fast searches
• Local & private - All indexing and search happens locally
• Hybrid search - BM25 for keyword matching, vector search for semantic similarity

Commands

Search (BM25 keyword matching)

qmd search "your query" --collection <name>

Fast, accurate keyword-based search. Best for specific terms or phrases.

Vector Search (semantic)

qmd vsearch "your query" --collection <name>

Semantic similarity search. Best for conceptual queries where exact words may vary.

Hybrid Search (both + reranking)

qmd hybrid "your query" --collection <name>

Combines both approaches with LLM reranking. Most thorough but often overkill.

How to Use

1. Check if collection exists:

   qmd collection list
   

2. Search the collection:

   # For specific terms
   qmd search "api authentication" --collection notes
   
   # For conceptual queries
   qmd vsearch "how to handle errors gracefully" --collection notes
   

3. Read results: qmd returns relevant snippets with file paths and context

Setup (if qmd not installed)

# Install qmd
bun install -g https://github.com/tobi/qmd

# Add a collection (e.g., Obsidian vault)
qmd collection add ~/path/to/vault --name notes

# Generate embeddings for vector search
qmd embed --collection notes

Invocation Examples

/qmd api authentication          # BM25 search for "api authentication"
/qmd how to handle errors --semantic   # Vector search for conceptual query
/qmd --setup                     # Guide through initial setup

Best Practices

• Use BM25 search (qmd search) for specific terms, names, or technical keywords
• Use vector search (qmd vsearch) when looking for concepts where wording may vary
• Avoid hybrid search unless you need maximum recall - it's slower
• Re-run qmd embed after adding significant new content to keep vectors current

Handling Arguments

• $ARGUMENTS contains the full search query
• If --semantic flag is present, use qmd vsearch instead of qmd search
• If --setup flag is present, guide user through installation and collection setup
• If --collection <name> is specified, use that collection; otherwise default to checking available collections

Workflow

1. Parse arguments from $ARGUMENTS
2. Check if qmd is installed (which qmd)
3. If not installed, offer to guide setup
4. If searching:
   • List collections if none specified
   • Run appropriate search command
   • Present results to user with file paths
5. If user wants to read a specific result, use the Read tool on the file path