Semantic Search

Search your secondbrain knowledge base using semantic similarity (meaning-based) and full-text search.

Prerequisites

qmd installed: Check with which qmd

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

• First run downloads ~1.5GB models

Search initialized: Check for .claude/search/ directory

• If not initialized, suggest running /secondbrain-search-init

Usage

/secondbrain-search "your natural language query" /secondbrain-search --entity=adrs "database migration" /secondbrain-search --recent=30d "authentication" /secondbrain-search --status=active --tag=kubernetes "deployment"

Workflow

Step 1: Validate Environment

Check qmd is installed

which qmd

Check search is initialized

ls .claude/search/

If qmd not installed:

qmd is not installed. Install it with: bun install -g qmd

or

npm install -g qmd

Then initialize search with: /secondbrain-search-init

If search not initialized:

Search not initialized for this project. Run: /secondbrain-search-init

Step 2: Parse Query and Filters

Extract from user input:

Filter Syntax Example

Entity --entity=<type>

--entity=adrs,notes

Recent --recent=<period>

--recent=7d , --recent=2w , --recent=1m

Date from --from=<date>

--from=2025-01-01

Date to --to=<date>

--to=2025-12-31

Status --status=<status>

--status=active , --status=!archived

Tag --tag=<tag>

--tag=kubernetes

Limit --limit=<n>

--limit=10 (default: 5)

Format --format=<fmt>

--format=brief , --format=detailed , --format=json

Step 3: Execute Search

Run qmd search command:

cd <project_root> qmd query "<user_query>" --json --limit=<limit>

Parse JSON output:

{ "results": [ { "id": "docs/adrs/ADR-0012-kubernetes-deployment.md", "score": 0.92, "title": "Kubernetes Deployment Strategy", "excerpt": "We decided to use Blue-Green deployment for stateless services...", "metadata": { "frontmatter": { "status": "implemented", "created": "2025-12-15" } } } ] }

Step 4: Enrich with Metadata

Load YAML records to add entity-specific metadata:

For each result:

• Determine entity type from file path (e.g., docs/adrs/ → ADRs)

• Load corresponding records from .claude/data/<entity>/records.yaml

• Match by file path and enrich with status, tags, dates, etc.

Step 5: Apply Post-Filters

Filter results based on user criteria:

Pseudocode

for result in results: if entity_filter and result.entity not in entity_filter: skip if status_filter and result.status != status_filter: skip if tag_filter and tag_filter not in result.tags: skip if date_filter and not in_date_range(result.date, from_date, to_date): skip

Step 6: Format Output

Brief Format (default for >3 results)

Search Results

Query: "kubernetes deployment" Results: 4 matches

1. [ADR-0012] Kubernetes Deployment Strategy (0.92) Status: implemented | Updated: 2025-12-15

2. [Note] Kubernetes Scaling Best Practices (0.87) Tags: kubernetes, scaling | Created: 2025-11-20

3. [Discussion] Platform Team - Deployment Pipeline (0.79) Date: 2025-10-05 | Participants: Alice, Bob

4. [Task] Implement Canary Deployments (0.71) Status: in_progress | Priority: high

Detailed Format (default for ≤3 results)

Search Results

Query: "kubernetes deployment" Results: 2 matches

1. [ADR-0012] Kubernetes Deployment Strategy

Score: 0.92 | Status: implemented | Category: infrastructure

File: ADR-0012-kubernetes-deployment.md

Excerpt:

We decided to use Blue-Green deployment for stateless services and Rolling updates for stateful workloads. This approach provides zero-downtime deployments while minimizing resource overhead...

Metadata:

• Created: 2025-12-15
• Author: sergey
• Category: infrastructure

2. [Note] Kubernetes Scaling Best Practices

Score: 0.87 | Tags: kubernetes, scaling

File: 2025-11-20-kubernetes-scaling.md

Excerpt:

Key considerations for scaling Kubernetes deployments:

1. Horizontal Pod Autoscaler configuration
2. Resource requests and limits
3. Pod disruption budgets...

Metadata:

• Created: 2025-11-20
• Status: active

JSON Format

{ "query": "kubernetes deployment", "total": 4, "results": [ { "entity": "adrs", "id": "ADR-0012", "title": "Kubernetes Deployment Strategy", "file": "docs/adrs/ADR-0012-kubernetes-deployment.md", "score": 0.92, "excerpt": "We decided to use Blue-Green deployment...", "metadata": { "status": "implemented", "category": "infrastructure", "created": "2025-12-15", "author": "sergey" } } ] }

Search Tips

Display helpful tips when no results found:

No Results Found

Query: "foobar nonexistent"

Tips

1. Try broader terms — Use general concepts instead of specific jargon
2. Check spelling — Semantic search handles typos but exact terms may miss
3. Remove filters — Try without --entity or --status filters first
4. Use related concepts — "authentication" instead of "OAuth2"

Alternative Actions

• /secondbrain-freshness — See all recent content
• Run without filters: /secondbrain-search "foobar"

Refine Search

After showing results, offer refinement options:

Refine Search

• --entity=adrs — Filter to ADRs only
• --recent=30d — Limit to last 30 days
• --status=active — Exclude archived items
• "kubernetes AND deployment" — Boolean operators

Related Skills

• secondbrain-search-init — Initialize search for this project

• secondbrain-freshness — View items by freshness/staleness