howto-qmd

# 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