qmd - Quick Markdown Search

Local search engine for Markdown notes, docs, and knowledge bases. Use this to find relevant files BEFORE reading them to dramatically reduce token usage.

When to Use (IMPORTANT)

ALWAYS prefer qmd search over reading files directly when:

• Exploring a codebase or documentation
• Looking for specific functionality or concepts
• Finding related files to a topic
• Answering questions about the codebase

Token savings: Instead of reading 5 files (5000+ tokens), search first (50 tokens) and read only the relevant sections (200 tokens).

Search Priority (follow this order)

1. qmd search "query" - Fast BM25 keyword search. Use this first, it's instant.
2. qmd vsearch "query" - Semantic similarity. Use only if keyword search fails.
3. qmd query "query" - Hybrid + reranking. Avoid unless user explicitly requests highest quality.

Common Commands

bash
1# Fast keyword search (DEFAULT - use this first)
2qmd search "authentication" -n 10
3
4# Search specific collection
5qmd search "api routes" -c my-project
6
7# Get file paths only (for deciding what to read)
8qmd search "database schema" --files
9
10# JSON output for parsing
11qmd search "error handling" --json
12
13# Semantic search (slower, use as fallback)
14qmd vsearch "how does the login flow work"

Retrieve Documents

bash
1# Get specific file
2qmd get "path/to/file.md"
3
4# Get by document ID from search results
5qmd get "#docid"
6
7# Get multiple files
8qmd multi-get "docs/*.md" --json

Workflow Example

Bad (token expensive):

1. Read src/auth/login.ts (800 tokens)
2. Read src/auth/session.ts (600 tokens)
3. Read src/auth/middleware.ts (500 tokens)
4. Read src/auth/types.ts (400 tokens)
→ Found answer in middleware.ts
Total: 2300 tokens

Good (token efficient):

1. qmd search "authentication middleware" --files (response: 50 tokens)
   → Returns: src/auth/middleware.ts:45-62
2. Read only the relevant section (150 tokens)
Total: 200 tokens (90% savings!)

Tips for Claude

• Search before reading: Always try qmd search first
• Use --files flag: Get paths without content to decide what to read
• Be specific: More specific queries = better results
• Check collections: Use qmd status to see indexed collections
• Combine with cartographer: CODEBASE_MAP.md gives structure, qmd gives content

Maintenance

bash
1qmd status          # Check index health and collections
2qmd update          # Re-index changed files (fast)
3qmd embed           # Update vector embeddings (slower)