search & vsearch

clawvault search <query> [options]

# Find documents mentioning "database"
clawvault search "database"

# Multi-word queries
clawvault search "API rate limiting"

# Quoted phrases for exact match
clawvault search "PostgreSQL connection"

# Search only in decisions
clawvault search "database" -c decisions

# Search in people files 
clawvault search "frontend" -c people

# Search lessons learned
clawvault search "testing" -c lessons

$ clawvault search "authentication" -c decisions

 Found 3 results for "authentication" in decisions/

┌─────────────────────────────────────────────┐
│ Use JWT over Sessions │
│ decisions/jwt-choice.md │
│ Modified: 2026-02-13 │
│ │
│ Decided on JWT tokens for **authentication** │
│ system. Better for mobile apps and API │
│ access. Sessions don't scale across... │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ OAuth Provider Selection │ 
│ decisions/oauth-provider.md │
│ Modified: 2026-02-12 │
│ │
│ Selected Auth0 for OAuth **authentication**. │
│ Good documentation, handles edge cases... │
└─────────────────────────────────────────────┘

clawvault vsearch <query> [options]

# Find content about user login (matches authentication, signin, etc.)
clawvault vsearch "user login"

# Conceptual queries work well
clawvault vsearch "team communication problems"

# Technical concepts
clawvault vsearch "database performance issues"

# Query: "database performance"
# Matches: "PostgreSQL slow queries", "connection pooling", "query optimization"

# Query: "team collaboration" 
# Matches: "communication issues", "meeting effectiveness", "async workflows"

# Query: "deployment problems"
# Matches: "production bugs", "rollback procedures", "CI/CD failures"

$ clawvault vsearch "how to handle production issues"

 Found 4 semantic matches for "how to handle production issues"

┌─────────────────────────────────────────────┐
│ Incident Response Checklist │
│ lessons/incident-response.md │
│ Similarity: 0.89 │
│ │
│ When production breaks: 1) Check status │
│ page 2) Roll back if possible 3) Gather │
│ logs 4) Communicate to stakeholders... │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ Database Rollback Procedure │
│ facts/rollback-steps.md │
│ Similarity: 0.76 │
│ │
│ Emergency database recovery: pg_dump from │
│ backup, restore to staging, verify data │
│ integrity, coordinate with team lead... │
└─────────────────────────────────────────────┘

clawvault search "database decisions"
# Searches: entire vault (decisions/, people/, lessons/, etc.)
# Powered by: qmd with BM25 + semantic embeddings
# Performance: Fast, local embeddings

memory_search "database decisions" 
# Searches: only MEMORY.md + memory/**/*.md
# Powered by: basic text search
# Scope: Limited to OpenClaw memory structure

# Install qmd
bun install -g qmd
# or: npm install -g qmd

# Verify installation
qmd --version

# Check index status
clawvault status

# Update index after changes
qmd update && qmd embed

# Rebuild index from scratch 
qmd update --force && qmd embed --force

clawvault init ~/memory --qmd-collection my-memory
# Creates: qmd collection for the vault
# Configures: file masks, embedding models, search settings

# AND search (both terms)
clawvault search "database AND performance"

# OR search (either term) 
clawvault search "Redis OR Memcached"

# NOT search (exclude term)
clawvault search "authentication NOT OAuth"

# Prefix matching
clawvault search "auth*" # matches: auth, authentication, authorize

# Suffix matching
clawvault search "*SQL" # matches: PostgreSQL, MySQL, NoSQL

# Search in titles only
clawvault search "title:database"

# Search in specific file paths
clawvault search "path:decisions/*"

# Search by tags
clawvault search "tag:performance"

# Find implementation details
clawvault search "API endpoint" -c facts

# Review past decisions
clawvault vsearch "why we chose this architecture"

# Find relevant people
clawvault search "frontend" -c people

# Check lessons learned
clawvault vsearch "deployment problems" -c lessons

# Research client background
clawvault search "Acme Corp" -c people

# Review related decisions 
clawvault vsearch "user authentication strategy"

# Find project status
clawvault search "dashboard redesign" -c projects

# Find similar issues
clawvault vsearch "database connection timeout"

# Check configuration
clawvault search "Redis config" -c facts

# Review incident history
clawvault vsearch "production outage response" -c lessons

# qmd not installed
clawvault search "query"
# Error: qmd not found. Install with: bun install -g qmd

# No index
clawvault vsearch "query" 
# Error: No embeddings found. Run: qmd embed

# Empty collection
clawvault search "query" -c nonexistent
# Warning: Category 'nonexistent' not found, searching all categories

# Good: Include searchable keywords
clawvault remember lesson "PostgreSQL Connection Pooling with PgBouncer" \
 --content "Database performance issue solved with connection pooling" \
 --tags "postgresql,performance,database,pgbouncer"

# Less searchable: Vague titles
clawvault remember lesson "Thing we learned" \
 --content "It was better"

# Search first, then get context
clawvault vsearch "authentication decisions" -c decisions
# → Find relevant decision IDs

clawvault context "implement OAuth" --profile planning 
# → Get broader context including graph neighbors