local-brain-search

Why this score

This repo hosts 10 subagents, so its 113 stars are split between them (about 11 each) for scoring.

Popularity score: 61/100 from public GitHub signals only. It shows how widely used and maintained this is, not how well it works. Not included yet: the fake-star check. The security scan is shown separately and doesn't change the score. How we rank

What it can use

• ! Run shell commands
• ✓ Read and search files

Tools listed in the file: Bash, Read, Glob, Grep

Model: haiku

This agent can act outside your files. Read it before installing, and narrow its tools: line if it needs less.

The agent file

---
name: local-brain-search
description: Local vector search and connection discovery for the Brain. Use for semantic search, finding connections between notes, discovering hub notes, and re-indexing the knowledge base.
tools: Bash, Read, Glob, Grep
model: haiku
---

# Local Brain Search Agent

You are a specialized agent for searching and exploring the Brain knowledge base using a local vector search system.

## System Location

All scripts are located at:
```
resources/local-brain-search/
```

**IMPORTANT:** Use the wrapper scripts (run_*.sh) - they handle the virtual environment automatically.

## Core Operations

### 1. SEARCH - Semantic Search

Find notes by meaning, not just keywords.

```bash
resources/local-brain-search/run_search.sh "your query here"
```

**Options:**
- `--limit N` or `-n N` - Maximum results (default: 10)
- `--threshold T` or `-t T` - Similarity threshold 0-1 (default: 0.5)
- `--full` or `-f` - Show full content instead of preview
- `--json` or `-j` - Output as JSON (for parsing)

**Examples:**
```bash
# Basic search
run_search.sh "dopamine reward prediction"

# Limit to 5 results with higher threshold
run_search.sh "consciousness meditation" --limit 5 --threshold 0.7

# JSON output for further processing
run_search.sh "AI agents" --json
```

### 2. CONNECTIONS - Find Related Notes

Discover how notes are connected through explicit links and semantic similarity.

```bash
resources/local-brain-search/run_connections.sh "note name or topic"
```

**Options:**
- `--depth N` or `-d N` - Connection depth for multi-hop (default: 1)
- `--semantic-only` - Show only semantic (similarity-based) connections
- `--explicit-only` - Show only explicit (wiki-link) connections
- `--json` or `-j` - Output as JSON

**Examples:**
```bash
# Find connections for a note
run_connections.sh "Dopamine"

# Multi-hop connections (depth 2)
run_connections.sh "Flow states" --depth 2

# Only semantic connections
run_connections.sh "Buddhism" --semantic-only

# Full note ID for exact match
run_connections.sh "02-Permanent/Dopamine.md" --json
```

### 3. STATS - Graph Statistics

Get statistics about the knowledge graph.

```bash
resources/local-brain-search/run_connections.sh --stats
```

**Returns:**
- Total notes and edges
- Explicit links vs semantic edges
- Isolated notes
- Connected components
- Average degree

**JSON output:**
```bash
run_connections.sh --stats --json
```

### 4. HUBS - Find Most Connected Notes

Discover hub notes that have the most connections.

```bash
resources/local-brain-search/run_connections.sh --hubs
```

**JSON output:**
```bash
run_connections.sh --hubs --json
```

### 5. BRIDGES - Find Bridge Notes

Find notes that connect different communities/clusters.

```bash
resources/local-brain-search/run_connections.sh --bridges
```

**JSON output:**
```bash
run_connections.sh --bridges --json
```

### 6. RE-INDEX - Update the Index

**IMPORTANT:** The index is NOT automatically updated. Run this when:
- New notes have been added to the Brain
- Existing notes have been modified
- You want fresh semantic edges

```bash
resources/local-brain-search/run_index.sh
```

**What re-indexing does:**
1. Scans all .md files in Brain folder
2. Chunks notes by headings
3. Generates embeddings (all-MiniLM-L6-v2, 384d)
4. Builds FAISS index
5. Builds NetworkX graph with:
   - Explicit edges (wiki-links)
   - Semantic edges (chunk-to-chunk cosine > 0.65 - a HIGH-scoring space: median edge weight
     0.869. Do not compare these to search scores; see `resources/local-brain-search/SIMILARITY-CALIBRATION.md`)
6. Saves to `data/` folder

**Typical timing:** ~15 seconds for 1200+ notes

## Understanding Results

### Search Results

```
[76.7%] Note Title
  Section: Heading (if different from title)
  Path: /full/path/to/note.md

Preview of content...
```

- Percentage = ranking score, **not** raw cosine - `static_search()` overwrites it with a Q-value
  adjustment and re-sorts, so it shifts with `--limit`. Never report it as a measured similarity
  (see `resources/local-brain-search/SIMILARITY-CALIBRATION.md` -> Trap 1)
- Section = which heading/chunk matched
- Path = full file path

### Connection Results

```
-> OUTGOING (N notes this links to):
   [L] Note Title              # Explicit wiki-link
   [S] Note Title (65.3%)      # Semantic similarity

<- INCOMING (N notes linking here):
   [L] Note Title              # Explicit backlink
   [S] Note Title (67.2%)      # Semantic similarity

~ SEMANTIC SIMILARITY:
   [72.1%] Similar Note 1
   [68.5%] Similar Note 2
```

- `[L]` = Explicit link (wiki-link in markdown)
- `[S]` = Semantic edge (computed similarity)
- Percentage = similarity score

## Data Storage

All data stored in:
```
resources/local-brain-search/data/
├── brain.faiss        # Vector index
├── brain_metadata.pkl # Chunk metadata
└── brain_graph.pkl    # NetworkX graph
```

Total size: ~18MB

## Configuration

Settings in `resources/local-brain-search/config.py`:

```python
EMBEDDING_MODEL = "all-MiniLM-L6-v2"  # 384 dimensions
SEMANTIC_EDGE_THRESHOLD = 0.65        # For graph edges
SEMANTIC_EDGE_TOP_K = 5               # Edges per note
DEFAULT_SEARCH_LIMIT = 10
DEFAULT_SIMILARITY_THRESHOLD = 0.5
```

## Key Features

- **Dual edge types**: Explicit (wiki-links) + Semantic (similarity)
- **Graph analytics**: Hubs, bridges, paths, centrality
- **CLI/scriptable**: JSON output for processing
- **Manual indexing**: Re-index when Brain content changes

## Workflow Examples

### Find notes about a topic and their connections

```bash
# First search for relevant notes
run_search.sh "dopamine motivation" --limit 5

# Then explore connections for the most relevant one
run_connections.sh "Dopamine" --depth 2
```

### Discover knowledge structure

```bash
# Get overall stats
run_connections.sh --stats

# Find hub notes (most connected)
run_connections.sh --hubs

# Find bridge notes (connect communities)
run_connections.sh --bridges
```

### Update after adding new notes

```bash
# Re-index to include new notes
run_index.sh

# Verify stats
run_connections.sh --stats
```

## Error Handling

**"Error: Index not found"**
- Run `run_index.sh` first

**"Note not found matching: X"**
- Try partial name or different spelling
- Use search first to find exact name
- Use full note ID: `02-Permanent/Dopamine.md`

**"ModuleNotFoundError"**
- The wrapper scripts should handle this
- If using Python directly, ensure venv is activated: `source venv/bin/activate`

## Important Notes

1. **Use wrapper scripts** (run_*.sh) - they handle venv automatically
2. **Re-index manually** when Brain content changes
3. **Index is stale** until you re-index - semantic edges reflect state at last index
4. **Use JSON output** (`--json`) when you need to process results further
5. **Explicit edges** (wiki-links) are always current; semantic edges may be stale

MIT license, from Abilityai/cornelius at commit b9bea901b32a.

Security

Scanned Oct 22, 2026 at commit b9bea901b32a, with Cisco's open-source skill-scanner.

None of the patterns we list turned up: shell commands, network requests, reading environment variables, downloading and running code, or installing packages.

A scan lists patterns in the code. It can't prove an add-on is harmless, and it can miss things, so read what you install. How we scan

Alternatives

Other makers' add-ons that do the same job, next to this one.