Semantic Search

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

Prerequisites

1. qmd installed: Check with which qmd

   • Install: bun install -g qmd or npm install -g qmd
   • First run downloads ~1.5GB models

2. 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:

1. Determine entity type from file path (e.g., docs/adrs/ → ADRs)
2. Load corresponding records from .claude/data/<entity>/records.yaml
3. 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](docs/adrs/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](docs/notes/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