Quick Start This tutorial walks you through creating your first QMD index, adding documents, and performing searches. You’ll have a working search engine for your markdown files in minutes.
This guide assumes you’ve already installed QMD . If not, install it first with npm install -g @tobilu/qmd or bun install -g @tobilu/qmd. Step 1: Create Your First Collection Collections tell QMD which directories to index and what files to include.
Choose a directory
Pick a directory with markdown files to index. For this example, we’ll use a notes directory: # Using a notes directory qmd collection add ~/Documents/notes --name notes
Or index the current directory: cd ~/Documents/notes qmd collection add . --name notes
By default, QMD indexes all **/*.md files (markdown files recursively). You can customize this with the --mask flag.
Verify the collection
List all collections to confirm it was added: Expected output: notes Path: /Users/you/Documents/notes Pattern: **/*.md Documents: 0 Updated: never
Index the files
QMD automatically indexes files when you add a collection, but you can manually trigger indexing: This scans all collections and indexes new/changed files. Add Multiple Collections Organize different types of documents into separate collections:
# Personal notes qmd collection add ~/Documents/notes --name notes # Meeting transcripts qmd collection add ~/Documents/meetings --name meetings # Work documentation qmd collection add ~/work/docs --name docs
Custom Glob Patterns Control which files are indexed with the --mask flag:
# Only index files in journals/ subdirectory qmd collection add ~/notes --name journals --mask "journals/**/*.md" # Index both .md and .txt files qmd collection add ~/notes --name all-text --mask "**/*.{md,txt}" # Exclude certain directories qmd collection add ~/notes --name filtered --mask "**/*.md" --exclude "archive/**"
Step 2: Add Context (Optional but Recommended) Context helps QMD understand your documents and returns descriptive metadata with search results. This is especially useful for AI agents.
Add collection-level context
Add a description for each collection: qmd context add qmd://notes "Personal notes and ideas" qmd context add qmd://meetings "Meeting transcripts and notes" qmd context add qmd://docs "Work documentation"
The qmd:// prefix indicates a virtual path to a collection.
Add path-specific context
Add context for subdirectories to provide more granular information: qmd context add qmd://notes/work "Work-related notes" qmd context add qmd://notes/personal "Personal journal entries" qmd context add qmd://meetings/2024 "Meeting notes from 2024"
Add from current directory
You can also add context from within a collection directory: cd ~/Documents/notes qmd context add "Personal notes and ideas" cd work qmd context add "Work-related notes"
QMD auto-detects the collection and path. Context is returned with search results and helps AI agents make better decisions about which documents to use. Think of it as metadata that explains what’s in each part of your knowledge base.
Step 3: Generate Embeddings Embeddings enable semantic search and are required for vsearch and query commands.
This command:
Downloads the embedding model (~300MB) if not already cached
Chunks documents into ~900-token pieces with smart boundary detection
Generates embeddings for each chunk
Stores vectors in the SQLite index
The first run downloads the embeddinggemma-300M-Q8_0 model (~300MB). Subsequent runs use the cached model.
Embedding Progress QMD shows progress as it embeds documents:
Embedding documents... [████████████████████████████████] 100% | 250/250 chunks | ETA: 0s Embedded 250 chunks from 45 documents in 12.3s Average: 20.3 chunks/sec
Re-embedding QMD automatically embeds new or changed documents. To force re-embedding everything:
Step 4: Search Your Documents QMD provides three search modes. Let’s try each one.
query (Hybrid)
search (BM25)
vsearch (Vector)
Hybrid Search (Recommended) Combines BM25, vector search, query expansion, and LLM re-ranking for the best results: qmd query "project timeline"
Example output: docs/roadmap.md:15 #a1b2c3 Title: Q4 Roadmap Context: Work documentation Score: 93% The **project timeline** for Q4 includes three major milestones: - October: Beta release - November: User testing - December: Production launch meetings/planning.md:42 #d4e5f6 Title: Planning Session Context: Meeting transcripts and notes Score: 78% We discussed the project timeline and agreed on key dates. The timeline will be reviewed weekly in standups.
This mode downloads two additional models on first use: qwen3-reranker-0.6b-q8_0 (~640MB) and qmd-query-expansion-1.7B-q4_k_m (~1.1GB).
Keyword Search Fast BM25 full-text search, perfect for exact terms: qmd search "authentication flow"
When to use:
Searching for specific technical terms
Finding exact phrases
Fast searches without LLM overhead
Semantic Search Vector similarity search for natural language queries: qmd vsearch "how to login"
When to use:
Natural language questions
Finding conceptually similar content
When you don’t know exact keywords
Search Options Number of results
Filter by collection
Minimum score
Full content
# Get 10 results instead of default 5 qmd query "user authentication" -n 10
Step 5: Retrieve Documents Once you’ve found relevant documents, retrieve them by path or docid.
Get by File Path qmd get "meetings/2024-01-15.md"
Fuzzy matching: If the path doesn’t exist, QMD suggests similar files:Document not found: meetings/2024-01-15.md Did you mean: meetings/2024-01-16.md meetings/2024-01-14.md
Get by Document ID Every document has a 6-character docid (shown in search results as #abc123):
The # prefix is optional:
Get Multiple Documents Retrieve multiple documents with glob patterns or comma-separated lists:
Glob pattern
Comma-separated
Limit file size
qmd multi-get "journals/2025-05*.md"
QMD provides multiple output formats optimized for AI agents and scripting.
JSON Output Structured data with snippets and metadata: qmd query "authentication" --json -n 10
Example output: [ { "docid" : "#a1b2c3" , "file" : "docs/auth.md" , "title" : "Authentication Guide" , "context" : "Work documentation" , "score" : 0.89 , "snippet" : "The **authentication** flow uses OAuth 2.0..." , "line" : 15 } ]
File List Output CSV-like format with docid, score, filepath, and context: qmd query "error handling" --files --min-score 0.3
Example output: #a1b2c3,0.89,docs/errors.md,Work documentation #d4e5f6,0.67,notes/debugging.md,Personal notes and ideas #g7h8i9,0.45,meetings/incident.md,Meeting transcripts
Perfect for piping to other commands: qmd query "API" --files | cut -d, -f3 | xargs -I {} cat {}
Markdown Output Formatted markdown for LLM context: qmd search "deployment" --md --full
Example output: ## docs/deploy.md ### Deployment Guide The deployment process consists of three stages...
Step 7: Check Index Status View index statistics and health:
Example output: Index: /Users/you/.cache/qmd/index.sqlite (45.2 MB) Documents: 156 (142 active, 14 inactive) Collections: 3 Collections: notes (85 docs) - /Users/you/Documents/notes Context: Personal notes and ideas meetings (42 docs) - /Users/you/Documents/meetings Context: Meeting transcripts and notes docs (29 docs) - /Users/you/work/docs Context: Work documentation Embeddings: 1,234 chunks (100%) Cache: 45 query expansions, 128 rerank scores
Common Workflows Daily Update Update the index with new/changed files:
For git repositories, pull latest changes first:
Search and Open Find a document and open it in your editor:
# Search and get the file path FILE = $( qmd search "deployment" --files -n 1 | cut -d, -f3 ) # Open in your editor code " $FILE " # or vim " $FILE "
Export for LLM Context Get all relevant documents above a score threshold:
qmd query "API design patterns" --all --min-score 0.4 --md --full > context.md
Then use context.md as context for your LLM.
Collection Management List files
Remove collection
Rename collection
# List all files in a collection qmd ls notes # List files in a subdirectory qmd ls notes/work
Next Steps
MCP Integration Connect QMD to Claude Desktop, Claude Code, or custom MCP clients
Search Modes Learn about BM25, vector search, and hybrid query modes
Collection Management Advanced collection configuration and context management
CLI Reference Complete command-line reference with all options and flags
Troubleshooting
Possible causes:
Collection not indexed: Run qmd update to index filesFiles not matched by glob: Check collection pattern with qmd collection listScore too low: Try lowering --min-score or increase -nEmbeddings missing: Run qmd embed for vector/hybrid search
Solutions:
Use search (BM25 only) instead of query for faster results
Filter by collection with -c <name> to reduce search space
Reduce number of results with -n <num>
Check index health with qmd status and clean up with qmd cleanup
Error: Failed to load embedding modelSolutions:
Check internet connection (models download from HuggingFace)
Verify sufficient disk space (~300MB for embedding model)
Try manual download (see Installation )
Check ~/.cache/qmd/models/ for corrupted downloads
Collection path not found
Error: Collection path does not existSolutions:
Use absolute paths: qmd collection add ~/Documents/notes --name notes
Verify the directory exists: ls ~/Documents/notes
Check for typos in the path
