qmd/CLAUDE.md

QMD - Quick Markdown Search

Use Bun instead of Node.js (bun not node, bun install not npm install).

Commands

qmd add .              # Index markdown files in current directory
qmd status             # Show index status and collections
qmd update-all         # Re-index all collections
qmd embed              # Generate vector embeddings (requires Ollama)
qmd search <query>     # BM25 full-text search
qmd vsearch <query>    # Vector similarity search
qmd query <query>      # Hybrid search with reranking (best quality)

Development

bun qmd.ts <command>   # Run from source
bun link               # Install globally as 'qmd'

Architecture

• SQLite FTS5 for full-text search (BM25)
• sqlite-vec for vector similarity search
• Ollama for embeddings (embeddinggemma) and reranking (qwen3-reranker)
• Reciprocal Rank Fusion (RRF) for combining results

Important: Do NOT run automatically

• Never run qmd add, qmd add-context, qmd embed, or qmd update-all automatically
• Never modify the SQLite database directly
• Write out example commands for the user to run manually
• Index is stored at ~/.cache/qmd/index.sqlite

Do NOT compile

• Never run bun build --compile - it overwrites the shell wrapper and breaks sqlite-vec
• The qmd file is a shell script that runs bun qmd.ts - do not replace it