howto-qmd

What this skill does

# Using qmd for Knowledge Base Search

## Overview

qmd is a local search engine for markdown documents. It combines BM25 keyword search, vector semantic search, and LLM-powered hybrid re-ranking. Use it to find relevant context in documentation, notes, and knowledge bases when grep is too literal and you need conceptual matching.

## When to Use

**Prefer qmd over grep when:**

- Searching documentation or notes for conceptually related content
- You know what you're looking for but not the exact terms used
- You need to find relevant context across a large markdown knowledge base
- Building context for a task from scattered documentation

**Use grep instead when:**

- Searching code files (qmd indexes markdown only)
- Looking for exact string matches or regex patterns
- The search target is a known identifier, import, or error message

## Search Modes

| Mode | Command | Speed | Best For |
|------|---------|-------|----------|
| Keyword (BM25) | `qmd search` | Fast | Known terms, exact phrases |
| Semantic (vector) | `qmd vsearch` | Slow | Conceptual queries, fuzzy recall |
| Hybrid (re-ranked) | `qmd query` | Slowest | Highest quality, broad exploration |

**Default to `qmd search`** unless keyword results are insufficient. Escalate to `vsearch` or `query` only when needed.

## CLI Quick Reference

```bash
# Keyword search (fast, use first)
qmd search "authentication flow"

# Semantic search (finds conceptually related content)
qmd vsearch "how users log in"

# Hybrid with LLM re-ranking (most thorough)
qmd query "best practices for session management"

# Restrict to a collection
qmd search "rate limiting" -c api-docs

# More results
qmd search "error handling" -n 20

# Full document content in results
qmd search "deployment" --full

# With line numbers
qmd search "config" --full --line-numbers

# JSON output for structured processing
qmd search "auth" --json --full

# Retrieve a specific document
qmd get "docs/auth.md" --full

# Retrieve from a specific line
qmd get "docs/auth.md:45" -l 100

# Batch retrieve by glob
qmd multi-get "docs/**/*.md" --json
```

## Collection Management

```bash
# Add a collection
qmd collection add ~/projects/docs --name project-docs --mask "**/*.md"

# List collections
qmd collection list

# Remove a collection
qmd collection remove old-notes

# Rebuild keyword index
qmd update

# Generate/update vector embeddings (required for vsearch/query)
qmd embed

# Check index health
qmd status
```

## Output Formats

| Flag | Format | Use Case |
|------|--------|----------|
| (default) | Human-readable | Interactive use |
| `--json` | JSON | Programmatic processing |
| `--files` | CSV: docid,score,filepath,context | File-oriented workflows |
| `--xml` | XML | Structured integration |
| `--md` | Markdown | Documentation pipelines |

## Filtering and Scoring

```bash
# Minimum relevance threshold
qmd search "deployment" --min-score 0.5

# All results above threshold
qmd search "config" --all --min-score 0.3

# Skip large files
qmd search "setup" --max-bytes 50000
```

## Practical Patterns

**Gather context before starting a task:**

```bash
# Find all relevant docs for a feature area
qmd search "authentication" -c project-docs -n 10 --files
# Then retrieve the most relevant ones
qmd get "docs/auth-design.md" --full --line-numbers
```

**Escalation pattern when keywords miss:**

```bash
# 1. Try keyword first (fast)
qmd search "retry logic"
# 2. If too few results, try semantic
qmd vsearch "how failures are retried"
# 3. If still unclear, use hybrid
qmd query "error recovery and retry mechanisms"
```

**Bulk context loading:**

```bash
qmd multi-get "design-docs/*.md" --json
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Using `qmd query` for every search | Start with `qmd search`, escalate only if needed |
| Forgetting to run `qmd embed` | Required once before `vsearch`/`query` work |
| Searching code files with qmd | qmd indexes markdown only; use grep or ast-grep for code |
| Not specifying `-c` with many collections | Restrict to relevant collection for better signal |
| Ignoring `--min-score` with `--all` | Unfiltered results include low-relevance noise |

## Red Flags

- Running `qmd query` repeatedly in a loop (expensive; cache or batch instead)
- Using qmd when a simple grep for a known string would suffice
- Forgetting `qmd update` after documents change
- Not running `qmd embed` after adding new collections