# Brain Search Implementation Specification

> **Version:** V43.12 | **Status:** active
> **Purpose:** Full algorithm specs for brain search engine + CLI reference

---

## Architecture

```
User WANT
    |
    v
brain_search.py (ThreadPoolExecutor, 5 workers)
    |
    +-- search_anti_patterns() --> ANTI_PATTERNS.md
    +-- search_wins()          --> history/WINS/*.md
    +-- search_fails()         --> history/FAILS/*.md
    +-- search_domains()       --> domains/*.md
    +-- search_evidence()      --> evidence/*.json
    |
    v
{query, total_results, elapsed_ms, results{}}
    |
    v
brain_recommender.py
    |
    +-- extract_warnings()
    +-- extract_approaches()
    +-- extract_context()
    +-- detect_contradictions()
    +-- compute_confidence()
    |
    v
{approach, confidence, warnings, contradictions}
```

---

## Salience Scoring

```
salience(relevance, days_old) = relevance * 0.7 + recency * 0.3
where: recency = e^(-days_old / 100)
```

| Days Old | Recency Factor | Notes |
|----------|---------------|-------|
| 0 | 1.000 | Brand new |
| 7 | 0.932 | This week |
| 30 | 0.741 | This month |
| 69 | 0.502 | ~50% decay |
| 100 | 0.368 | 1/e |
| 230 | 0.100 | Archive threshold |
| 365 | 0.026 | Very stale |

---

## Text Similarity

Jaccard word-overlap similarity:
```
sim(A, B) = |words(A) & words(B)| / |words(A) | words(B)|
```

Thresholds:
- > 0.1: Include in results
- > 0.3: Contradiction candidate
- > 0.5: Strong match
- > 0.8: Near-duplicate

---

## CLI Reference

```bash
# Basic search
python .claude/automation/brain_search.py "translation hallucination"

# JSON output
python .claude/automation/brain_search.py "TTS voice cloning" --json

# Limit results
python .claude/automation/brain_search.py "keyboard layout" --top 3

# Full recommendation
python .claude/automation/brain_recommender.py "add new /stats command"

# JSON recommendation
python .claude/automation/brain_recommender.py "refactor handlers" --json
```

---

## Performance

- Target: < 100ms for full 5-source parallel search
- ThreadPoolExecutor with 5 workers (one per source)
- Timeout: 5 seconds per source (configurable)
- All I/O is local filesystem (no network)

---

## Configuration

All thresholds configurable in `automation/brain_config.json`:

```json
{
  "search": {
    "max_results_per_source": 10,
    "min_salience": 0.1,
    "recency_weight": 0.3,
    "relevance_weight": 0.7,
    "thread_timeout_seconds": 5
  }
}
```

---

*V43.12: Brain Search Engine - parallel search with salience scoring*
