roasbeef/vault-search

Vault Search Skill

Provides semantic search and SQL queries over the Obsidian vault using sqlite-vec for vector storage and ChromaDB's embedding function.

Python Environment

Interpreter: /Users/roasbeef/vault/.claude/venv/bin/python

Required packages:

• sqlite-vec (vector search extension)
• chromadb (embedding function only)

Database Location

Path: /Users/roasbeef/vault/.claude/vault_search/vault.db

Contains:

• notes table: frontmatter metadata for all markdown files
• vec_chunks table: vector embeddings for semantic search

Available Scripts

search.py - Semantic Search

Find notes by meaning using vector similarity.

# Basic semantic search
python scripts/search.py --query "options trading strategies" --n-results 5

# Filter by folder
python scripts/search.py --query "earnings analysis" --folder "investing"

# Filter by metadata
python scripts/search.py --query "task automation" --where "status='open'"

# Combined: semantic + metadata
python scripts/search.py --query "portfolio risk" --where "folder LIKE 'investing%' AND status='open'"

Arguments:

• --query (required): Search query text
• --n-results: Number of results (default: 5)
• --folder: Filter by folder prefix
• --where: SQL WHERE clause for metadata filtering
• --db-path: Database path (default: .claude/vault_search/vault.db)

Output:

• Human-readable results with snippets
• JSON block for programmatic use

dataview.py - SQL Queries (Dataview Replacement)

Query frontmatter metadata using SQL.

# Open tasks due this week
python scripts/dataview.py --sql "SELECT path, due, priority FROM notes
                                   WHERE status = 'open'
                                   AND due < date('now', '+7 days')
                                   ORDER BY due"

# Tasks by folder
python scripts/dataview.py --sql "SELECT path, status, priority FROM notes
                                   WHERE folder LIKE 'TaskNotes%'
                                   AND status != 'done'"

# Investing positions
python scripts/dataview.py --sql "SELECT path, ticker, strategy, expiry FROM notes
                                   WHERE folder LIKE 'investing/Portfolio/Positions%'"

# Query by tags (using json_each)
python scripts/dataview.py --sql "SELECT DISTINCT n.path, n.title
                                   FROM notes n, json_each(n.tags) t
                                   WHERE t.value = 'automation'"

Arguments:

• --sql (required): SQL query to execute
• --db-path: Database path (default: .claude/vault_search/vault.db)
• --format: Output format: "table" or "json" (default: table)

Available columns:

• path, folder, filename, title, modified
• Frontmatter: status, priority, due, scheduled, tags, projects, contexts
• Investing: ticker, strategy, expiry

index.py - Build/Rebuild Index

Rebuild the search index from vault files.

# Full rebuild
python scripts/index.py --vault-path /Users/roasbeef/vault --rebuild

# Incremental update (default)
python scripts/index.py --vault-path /Users/roasbeef/vault

# Show statistics
python scripts/index.py --stats

Arguments:

• --vault-path: Path to vault root (default: /Users/roasbeef/vault)
• --db-path: Database path (default: .claude/vault_search/vault.db)
• --rebuild: Force full rebuild
• --stats: Show index statistics

When to Use This Skill

Use semantic search (search.py) when:

• User asks to "find notes about X"
• User wants "related notes" to a topic
• Answering questions about vault contents
• Exploring a topic across the vault

Use dataview queries (dataview.py) when:

• User asks to "list tasks" or "show open tasks"
• Filtering by specific metadata (status, due date, tags)
• Aggregating or counting notes
• Building dashboards or summaries

Use combined queries when:

• "Find notes about X that are also open tasks"
• "Show investing notes related to Y"

Example Usage

Find Related Notes

User: "What notes do I have about HTLC routing?"
→ python scripts/search.py --query "HTLC routing payment channels" --n-results 5

List Open Tasks

User: "Show my open high-priority tasks"
→ python scripts/dataview.py --sql "SELECT path, due FROM notes
                                     WHERE status='open' AND priority='high'
                                     ORDER BY due"

Combined Search

User: "Find investing notes about semiconductor supply chain"
→ python scripts/search.py --query "semiconductor supply chain"
                           --folder "investing"
                           --n-results 10

Rebuilding the Index

Use the /vault-index command to rebuild the index when:

• Many files have changed
• Search results seem stale
• After bulk imports

Technical Details

• Embeddings: ChromaDB DefaultEmbeddingFunction (ONNX MiniLM, 384 dims)
• Storage: sqlite-vec virtual tables
• Chunking: Split by markdown headings (v1)
• Excluded folders: .obsidian, .smart-env, .claude, assets, Templates