zircote · zircote · Feb 16, 2026 · Feb 16, 2026 · Feb 16, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,9 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **[Semantic Search]**: QMD integration for vector and hybrid search
+  - New skill `/mnemonic:qmd-setup` for automated setup
+  - New skill `/mnemonic:qmd-reindex` for re-indexing after captures
+  - Supports BM25 keyword, vector semantic, and hybrid search modes
+  - Auto-discovers memory roots from config
+  - Registered collections: org-level, default, and project-level memories
+  - See [docs/semantic-search.md](docs/semantic-search.md) for details
+
 ### Planned
 
-- Semantic search with embeddings
 - Export/import functionality
 - Web UI for memory browsing
 

diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ A pure filesystem-based memory system for Claude Code. No external dependencies
 - **Skill-First Architecture**: Skills work standalone without hooks or libraries
 - **Cognitive Memory Types**: Semantic, episodic, and procedural memories
 - **Custom Ontologies**: Extend with domain-specific entity types and relationships
+- **Semantic Search**: Optional vector search via qmd integration
 - **Bi-Temporal Tracking**: Valid time vs. recorded time
 - **Git Versioned**: All changes tracked with git
 - **Cross-Session Coordination**: Blackboard for session handoffs
@@ -260,7 +261,11 @@ After running `/mnemonic:setup`, Claude will:
 2. **Auto-Capture**: Automatically save decisions, learnings, and patterns
 3. **Silent Operation**: Memory operations happen in the background
 
-## Search Examples
+## Search
+
+Mnemonic provides both traditional keyword search and semantic vector search.
+
+### Keyword Search (ripgrep)
 
 ```bash
 # Full-text search
@@ -279,6 +284,37 @@ rg "^type: episodic" ${MNEMONIC_ROOT}/ --glob "*.memory.md" -l
 find ${MNEMONIC_ROOT} -name "*.memory.md" -mtime -7
 ```
 
+### Semantic Search (qmd)
+
+For semantic/vector search capabilities, use the integrated `@tobilu/qmd` support:
+
+```bash
+# One-time setup
+/mnemonic:qmd-setup
+
+# Keyword search (BM25)
+qmd search "authentication patterns"
+
+# Semantic vector search
+qmd vsearch "how do we handle user sessions"
+
+# Hybrid search (BM25 + vector)
+qmd query "database migration strategy"
+
+# Scope to specific collections
+qmd search "auth" -c mnemonic-zircote    # org memories only
+qmd search "auth" -c mnemonic-project    # this repo only
+
+# Re-index after adding new memories
+/mnemonic:qmd-reindex
+```
+
+**Requirements:**
+- Node.js >= 22
+- `npm i -g @tobilu/qmd`
+
+See [skills/qmd-setup/SKILL.md](skills/qmd-setup/SKILL.md) for detailed setup instructions.
+
 ## Hooks
 
 Hooks provide proactive automation via `hookSpecificOutput.additionalContext`:
@@ -330,6 +366,7 @@ mnemonic/
 │   └── *.md                # Slash commands
 ├── docs/
 │   ├── architecture.md     # System architecture
+│   ├── semantic-search.md  # QMD semantic search guide
 │   ├── validation.md       # Memory validation guide
 │   ├── agent-coordination.md  # Multi-agent patterns
 │   ├── ontologies.md       # Custom ontology guide
@@ -363,12 +400,19 @@ mnemonic/
 
 ## Requirements
 
+### Core Dependencies
+
 - Claude Code CLI
 - Git
 - ripgrep (recommended for search)
 - yq (required for structured queries)
 - Python 3.8+ (for hooks and tools)
 
+### Optional: Semantic Search
+
+- Node.js >= 22
+- `@tobilu/qmd` (`npm i -g @tobilu/qmd`)
+
 ### Installing Dependencies
 
 ```bash
@@ -379,10 +423,24 @@ brew install ripgrep yq
 apt install ripgrep
 snap install yq
 
+# Optional: semantic search
+npm i -g @tobilu/qmd
+
 # Check installation
 make check-deps
 ```
 
+## Documentation
+
+- **[Semantic Search Guide](docs/semantic-search.md)** - Setup and use QMD for vector search
+- **[CLI Usage](docs/cli-usage.md)** - Command-line operations and search patterns
+- **[Architecture](docs/architecture.md)** - System design and components
+- **[Validation](docs/validation.md)** - Memory validation and MIF compliance
+- **[Custom Ontologies](docs/ontologies.md)** - Extend with domain-specific types
+- **[Agent Coordination](docs/agent-coordination.md)** - Multi-agent workflows
+- **[ADRs](docs/adrs/)** - Architecture decision records
+- **[Enterprise Guides](docs/enterprise/)** - Deployment and governance
+
 ## Related Projects
 
 - **[MIF (Memory Interchange Format)](https://mif-spec.dev)** - The specification this plugin implements. An open standard for portable AI memory storage. Schemas: https://mif-spec.dev/schema/

diff --git a/docs/cli-usage.md b/docs/cli-usage.md
@@ -22,7 +22,51 @@ ${MNEMONIC_ROOT}/{namespace}/{scope}/*.memory.md
 
 ## Searching Memories
 
-### Full-Text Search with ripgrep
+Mnemonic provides multiple search methods optimized for different use cases.
+
+### Method 1: Semantic Vector Search (qmd)
+
+For natural language queries and semantic understanding:
+
+```bash
+# One-time setup
+/mnemonic:qmd-setup
+
+# BM25 keyword ranking
+qmd search "authentication middleware"
+
+# Vector semantic search
+qmd vsearch "how do we manage user permissions"
+
+# Hybrid search (combines both)
+qmd query "error handling best practices"
+
+# Scope to specific collections
+qmd search "api design" -c mnemonic-zircote     # org memories
+qmd search "api design" -c mnemonic-project     # project memories
+qmd search "api design"                         # all collections
+
+# Limit results
+qmd search "docker" -n 5
+
+# Re-index after adding memories
+/mnemonic:qmd-reindex
+# or manually:
+qmd update && qmd embed
+```
+
+**When to use:**
+- Natural language queries
+- Conceptual/semantic similarity
+- Finding related memories across namespaces
+- "What do we know about X" questions
+
+**Requirements:**
+- Node.js >= 22
+- `npm i -g @tobilu/qmd`
+- Initial setup with `/mnemonic:qmd-setup`
+
+### Method 2: Full-Text Search with ripgrep
 
 ```bash
 # Search all memories for a keyword
@@ -63,7 +107,13 @@ rg "confidence: 0.9" $MNEMONIC_ROOT --glob "*.memory.md" -l
 rg "^title:.*PostgreSQL" $MNEMONIC_ROOT --glob "*.memory.md" -l
 ```
 
-### Using find for File Operations
+**When to use:**
+- Exact phrase matching
+- Known keywords
+- Regular expressions
+- Precise control over matching
+
+### Method 3: Using find for File Operations
 
 ```bash
 # List all memories
@@ -79,6 +129,29 @@ find ${MNEMONIC_ROOT} -name "*.memory.md" -mtime +90
 find ${MNEMONIC_ROOT} -name "*.memory.md" | grep -o '/[^/]*/project\|/[^/]*/user' | sort | uniq -c
 ```
 
+**When to use:**
+- Time-based filtering
+- File system operations
+- Batch processing
+- Directory traversal
+
+### Search Method Comparison
+
+| Feature | qmd (Semantic) | ripgrep | find |
+|---------|---------------|---------|------|
+| Natural language | ✅ Best | ❌ No | ❌ No |
+| Exact matching | ⚠️ Good | ✅ Best | ❌ No |
+| Speed | ⚠️ Moderate | ✅ Fast | ✅ Fast |
+| Ranking | ✅ Relevance | ❌ No | ❌ No |
+| Setup required | ⚠️ Yes | ✅ None | ✅ None |
+| Regex support | ❌ No | ✅ Yes | ⚠️ Limited |
+| Time filtering | ❌ No | ❌ No | ✅ Yes |
+
+**Recommendation:**
+- **Complex questions**: Use `qmd query`
+- **Known keywords**: Use `rg`
+- **Time-based**: Use `find` + `rg`
+
 ## Reading Memories
 
 ### View a Memory