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)
```bash
qmd search "your query" --collection <name>
```
Fast, accurate keyword-based search. Best for specific terms or phrases.

### Vector Search (semantic)
```bash
qmd vsearch "your query" --collection <name>
```
Semantic similarity search. Best for conceptual queries where exact words may vary.

### Hybrid Search (both + reranking)
```bash
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**:
   ```bash
   qmd collection list
   ```

2. **Search the collection**:
   ```bash
   # 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)

```bash
# 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 specif...