# Agent Cache Protocol: Brain-as-Knowledge-Cache

> **Version:** V43.11 | **Status:** active
> **Purpose:** Agents use brain as pre-loaded knowledge cache instead of blind exploration

---

## The Problem

Without brain cache, agents:
- Repeat mistakes already documented in FAILS
- Miss proven approaches from WINS
- Ignore anti-patterns already identified
- Waste tokens rediscovering known patterns

## The Solution

**Brain = Knowledge Cache.** Before any agent starts work, it loads relevant brain context.

---

## Cache Loading Protocol

### Step 1: Query Classification

Classify the user's request into domains:
- translation, tts, ui, detection, handler, architecture, memory

### Step 2: Cache Hit Check

```
brain_search.py "user query"
  -> anti_patterns (WARN)
  -> wins (RECOMMEND)
  -> fails (EXPLAIN why it failed)
  -> domains (CONTEXT)
  -> evidence (RAW DATA)
```

### Step 3: Cache-Informed Agent Spawn

```python
recommendation = brain_recommender.py("user want")
# Agent receives:
# - approach (what worked before)
# - warnings (what to avoid)
# - context (domain knowledge)
# - confidence (how sure we are)
```

---

## Cache Layers

| Layer | Source | Speed | Staleness |
|-------|--------|-------|-----------|
| L1 | domains/*.md | Fast | Low (curated) |
| L2 | PATTERNS/*.md | Fast | Low (synthesized) |
| L3 | evidence/*.json | Medium | Medium (raw) |
| L4 | history/WINS/*.md | Medium | Low (proven) |
| L5 | history/FAILS/*.md | Medium | Low (mistakes) |

---

## Cache Invalidation

- Evidence older than 365 days: flag as stale
- Confidence below 0.3: exclude from recommendations
- Contradictions detected: alert agent to review both sides
- Salience below 0.1: archive (still searchable)

---

## Agent Memory Load Matrix

| Task Type | Must Load |
|-----------|-----------|
| Search | CLAUDE.md only (L1) |
| Feature | CLAUDE.md + ANTI_PATTERNS + PATTERNS (L1-L2) |
| Refactor | + domain file + evidence (L1-L3) |
| Debug | + FAILS + WINS (L1-L5) |
| New command | Full brain search (all layers) |

---

## Metrics

Track cache effectiveness:
- Cache hits: How often brain had relevant info
- Cache misses: New knowledge not in brain
- False positives: Irrelevant recommendations
- Time saved: Tokens avoided by cache-informed agents

---

*V43.11: Brain-as-cache protocol - agents search before building*
