Initialize Semantic Search

Set up qmd semantic search for an existing secondbrain project.

Prerequisites

• Secondbrain project exists: Check for .claude/data/config.yaml

• qmd installed: Check with which qmd

Workflow

Step 1: Validate Environment

Check secondbrain exists

ls .claude/data/config.yaml

Check qmd installation

which qmd

If secondbrain not found:

No secondbrain project found in current directory. Run /secondbrain-init to create a new project first.

If qmd not installed:

qmd Not Installed

qmd is required for semantic search. Install it:

Using Bun (Recommended)

bun install -g qmd

Using npm

npm install -g qmd

After installation, run this skill again.

Note: First run will download ~1.5GB of embedding models.

Step 2: Check Existing Search

ls .claude/search/ 2>/dev/null

If search already initialized:

Search Already Initialized

Search is already configured for this project.

Index location: .claude/search/ Last indexed: 2026-01-15 10:30

Options

1. Rebuild index — Re-index all documents /secondbrain-search-init --rebuild

2. Search now — Start searching /secondbrain-search "your query"

3. Check status — View index statistics qmd status

Step 3: Create Search Configuration

Create .claude/search/ directory and qmd config:

mkdir -p .claude/search

Generate qmd.config.json in project root:

{ "name": "{{project_name}}-secondbrain", "paths": ["docs"], "ignore": [ "/node_modules/", "/.vitepress/cache/", "/.vitepress/dist/", "**/TEMPLATE.md" ], "indexDir": ".claude/search", "chunk": { "size": 800, "overlap": 0.15 }, "metadata": { "extractFrontmatter": true, "includeFileMetadata": true } }

Step 4: Update .gitignore

Add search index to .gitignore (index should not be committed):

Semantic search index (regenerate with /secondbrain-search-init)

.claude/search/ qmd.config.json

Step 5: Build Initial Index

Run initial indexing:

qmd index

Show progress:

Building Search Index

Scanning docs/... Found 47 documents

Indexing: [████████████████████░░░░░░░░░░] 35/47 documents

Downloading models (first run only):

• embedding-gemma-300M... done
• qwen3-reranker... done

Building embeddings: [██████████████████████████████] 47/47 documents

Index built successfully!

• Documents: 47
• Chunks: 312
• Index size: 2.4 MB
• Location: .claude/search/

Step 6: Register Hook (Optional)

Ask user if they want automatic index updates:

Automatic Index Updates

Would you like to automatically update the search index when documents are modified?

[x] Yes, add PostToolUse hook (Recommended) - Updates index incrementally on file changes - Adds ~0.5s to Write/Edit operations

[ ] No, I'll rebuild manually - Run qmd index or /secondbrain-search-init --rebuild

If yes, add hook to .claude/settings.local.json :

{ "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "python3 "${CLAUDE_PROJECT_DIR}/.claude/hooks/search-index-update.py"", "timeout": 30000 } ] } ] } }

Copy hook script:

cp "${CLAUDE_PLUGIN_ROOT}/hooks/search-index-update.py" .claude/hooks/

Step 7: Show Summary

Search Initialized Successfully!

Project: my-knowledge-base Documents indexed: 47 Index location: .claude/search/

Quick Start

Search your knowledge base: /secondbrain-search "kubernetes deployment strategies"

Search with filters: /secondbrain-search --entity=adrs "database" /secondbrain-search --recent=30d "authentication"

Index Management

Rebuild index: qmd index --rebuild

Check status: qmd status

View recent searches: qmd history

Automatic Updates

Index updates: Enabled (PostToolUse hook) Documents in docs/ will be re-indexed on save.

Options

--rebuild

Force rebuild of entire index:

qmd index --rebuild

--no-hook

Skip adding the automatic update hook:

/secondbrain-search-init --no-hook

Troubleshooting

Models Download Stuck

If model download hangs:

Clear cache and retry

rm -rf ~/.cache/qmd/models/ qmd index

Index Corruption

If search returns errors:

Remove and rebuild

rm -rf .claude/search/ qmd index

Slow Indexing

For large document sets (>500 docs):

• Initial indexing may take several minutes

• Consider using --batch-size=50 for progress visibility

Related Skills

• secondbrain-search — Search your knowledge base

• secondbrain-init — Create new secondbrain project