Collections are the directories you index with QMD. Each collection has a name, path, glob pattern, and optional contexts.
Adding Collections Create a collection to index markdown files in a directory:
Current Directory
Custom Path
Custom Glob Pattern
qmd collection add . --name myproject
The default glob pattern is **/*.md, which indexes all markdown files recursively while excluding common directories like node_modules, .git, .cache, vendor, dist, and build.
Collection Naming If you don’t specify --name, QMD uses the directory basename:
qmd collection add ~/Documents/meeting-notes # Creates collection named "meeting-notes"
Collection names must contain only alphanumeric characters, hyphens, and underscores (a-zA-Z0-9_-).
Listing Collections View all indexed collections:
Example output: Collections (3): notes (qmd://notes/) Pattern: **/*.md Files: 142 Updated: 2h ago meetings (qmd://meetings/) [excluded] Pattern: **/*.md Files: 67 Updated: 1d ago docs (qmd://docs/) Pattern: **/*.md Files: 89 Updated: 3h ago
The [excluded] tag means this collection is not searched by default unless explicitly specified with -c or --collection.
Removing Collections Remove a collection and all its indexed documents:
qmd collection remove notes
Example output: ✓ Removed collection 'notes' Deleted 142 documents Cleaned up 98 orphaned content hashes
Removing a collection deletes all document records and embeddings from the index. The source files remain untouched.
Renaming Collections Change a collection’s name:
qmd collection rename notes personal-notes
Virtual paths are automatically updated:
✓ Renamed collection 'notes' to 'personal-notes' Virtual paths updated: qmd://notes/ → qmd://personal-notes/
Listing Files in a Collection Browse files in a collection:
All Files
With Path Prefix
List All Collections
Example output: 12.3 KB Jan 15 09:30 qmd://notes/meeting-2025-01-15.md 8.7 KB Jan 14 14:22 qmd://notes/ideas/product-roadmap.md 4.2 KB Jan 13 11:05 qmd://notes/retrospective.md
Include/Exclude Filtering Control which collections are searched by default:
Excluding a Collection Mark a collection as excluded from default searches:
qmd collection exclude meetings
Excluded collections are only searched when explicitly specified:
# Searches only 'meetings' collection qmd search "standup" -c meetings # Searches all non-excluded collections qmd search "standup"
Including a Collection Re-enable a previously excluded collection:
qmd collection include meetings
Collections are included by default when created. Use exclusion for archives, deprecated content, or collections you only want to search explicitly.
Update Commands Automate collection updates with custom bash commands. Useful for git repos or synced directories.
Setting an Update Command Git Pull
Git with Stash
Rsync
qmd collection update-cmd brain 'git pull --rebase'
Update commands run in the collection’s directory before re-indexing.
Removing an Update Command qmd collection update-cmd notes
Omit the command argument to clear it.
Running Updates Update all collections (runs custom commands if configured):
Example output: Updating 3 collection(s)... [1/3] brain (**/*.md) Running update command: git pull --rebase Already up to date. Collection: /home/user/brain (**/*.md) Indexed 245 files (89 new, 12 updated, 144 unchanged) Completed in 2.1s [2/3] notes (**/*.md) Collection: /home/user/notes (**/*.md) Indexed 67 files (3 new, 1 updated, 63 unchanged) Completed in 0.8s ✓ All collections updated. Run 'qmd embed' to update embeddings (15 unique hashes need vectors)
Collection Configuration Storage Collections are stored in ~/.config/qmd/index.yml:
collections : notes : path : /home/user/Documents/notes pattern : "**/*.md" context : "/" : "Personal notes and ideas" "/work" : "Work-related notes" update : "git pull --rebase" meetings : path : /home/user/Documents/meetings pattern : "**/*.md" includeByDefault : false context : "/" : "Meeting transcripts and notes"
Manually editing index.yml is supported but use the CLI commands when possible to avoid syntax errors.
Virtual Paths Each collection has a virtual path namespace:
Collection root: qmd://notes/
Files within: qmd://notes/path/to/file.md
Virtual paths work with all QMD commands:
qmd get qmd://notes/meeting.md qmd multi-get "qmd://notes/2025-*.md" qmd context add qmd://notes/work "Work notes"
Best Practices
Organize by domain
Create separate collections for different knowledge domains (personal notes, work docs, research papers, etc.) for better context and filtering.
Add update commands
Configure git pull or sync commands for collections that change frequently.
Use exclusion strategically
Exclude large archives or reference material that you rarely search. Access them explicitly when needed with -c collection-name.
Add context metadata
Use qmd context add to describe what each collection contains. This dramatically improves search relevance. See Context Management . 