# BABEL BOT - Memory System Design History

> **Status:** HISTORICAL DOCUMENT (V42.x → V43.x evolution)
> This documents the 10-iteration analysis that led to the current V43.3 brain architecture.

---

## ⚠️ Evolution Context

**What was planned (V42.x):**
- `memory/INDEX.md` as main router
- `reference/` folder for docs
- `QUICK.md` as 80-line summary

**What exists now (V43.3):**
- `CLAUDE.md` is the router (INDEX.md merged into it)
- `docs/` folder replaced `reference/`
- Brain science applied (chunking, sparse representation)
- Model-aware delegation (Haiku orchestrates)

**Why this doc exists:** Shows the thinking process. Useful for understanding WHY the current structure exists.

---

---

## ITERATION SUMMARY

### Token Analysis (Before)
| File | Lines | Purpose |
|------|-------|---------|
| CLAUDE.md | 733 | Rules + architecture + examples |
| SESSION.md | 70 | Current session state |
| LESSONS.md | 138 | What worked/failed |
| PATTERNS.md | 236 | Reusable code patterns |
| FAILED_ATTEMPTS.md | 94 | Mistakes to avoid |
| **TOTAL** | **1,271** | Loaded every session |

### The Problem
~1,300 lines loaded every session, but:
- 80% is reference material (needed rarely)
- 50% is code examples (only relevant when coding that area)
- Only ~10% is truly session-critical

---

## ITERATION 1-3: Skill Patterns Identified

### Skills to Create
| Skill | Trigger | Agent | Purpose |
|-------|---------|-------|---------|
| `/cleanup` | After feature, "audit", "deprecated" | Senior Engineer | Delete old code, refactor bloated files |
| `/version` | "bump", "release" | Haiku | Update CHANGELOG, version refs, suggest commit |
| `/explore` | "where", "find", "search" | Explore | Thorough codebase search |
| `/plan` | "how should we", major feature | Plan | Design before implementation |
| `/refactor` | File >300 lines | Senior Engineer | Split bloated file |
| `/deps` | New dependency | Haiku | License check (Law 4) |

### Auto-Trigger Rules
```
Feature completed → /cleanup (automatic)
"Where is X?" → /explore (automatic)
File >300 lines detected → /refactor (suggest)
New import added → /deps (automatic)
```

---

## ITERATION 4-6: Memory Architecture V2

### New Structure
```
.claude/
├── settings.json       # Hooks (exists)
│
├── QUICK.md           # THE ONE FILE (~80 lines)
│                      # - Current version
│                      # - Active task
│                      # - Critical rules (Laws 1-8 condensed)
│                      # - Last session summary
│
├── memory/
│   ├── INDEX.md       # What's where (quick scan)
│   │
│   ├── domains/       # Load ONLY when working on that area
│   │   ├── translation.md   # Guards, chunking, bridge
│   │   ├── ui.md            # Components, menus, callbacks
│   │   ├── handlers.md      # Message flow, routing
│   │   └── detection.md     # Language detection, GlotLID
│   │
│   ├── history/
│   │   ├── wins.md          # Compressed: what worked
│   │   └── fails.md         # Compressed: what failed
│   │
│   └── sessions/
│       └── latest.md        # Current session notes
│
├── skills/            # Skill definitions
│   ├── cleanup.md
│   ├── version.md
│   └── explore.md
│
└── reference/         # Deep docs (load only when needed)
    ├── ARCHITECTURE.md
    ├── TESTING.md
    └── LAWS.md
```

### Token Savings
| Scenario | Before | After | Savings |
|----------|--------|-------|---------|
| Session start | 1,271 | ~150 | **88%** |
| Working on UI | 1,271 | ~250 | **80%** |
| Working on translation | 1,271 | ~300 | **76%** |
| Full reference needed | 1,271 | 1,271 | 0% |

---

## ITERATION 7-8: Compression Patterns

### Original (verbose)
```markdown
## Hallucination Detection (V42.2)

### The Problem
Model adds garbage at end of translations: "e non un", "y no un"

### Failed Attempts
- **Hardcoded word lists** - Broke on new inputs, violated Law 2
- **Language-specific regex** - Doesn't scale to 400 languages

### What Worked
Structural pattern detection - comma + short words at end = garbage
```

### Compressed (dense)
```markdown
## Hallucinations (V42.2)
❌ Hardcoded words → Law 2 violation
❌ Language-specific regex → doesn't scale
✅ `comma + short≤4 words at end` → trim
```

**Result:** 12 lines → 4 lines (67% reduction)

---

## ITERATION 9: Auto-Delegation Matrix

### Task → Agent Routing
```
┌─────────────────────────────────────────────────────┐
│ User Input                                          │
└─────────────────────┬───────────────────────────────┘
                      │
        ┌─────────────┴─────────────┐
        │ Pattern Detection          │
        └─────────────┬─────────────┘
                      │
    ┌─────────────────┼─────────────────┐
    │                 │                 │
    ▼                 ▼                 ▼
┌────────┐      ┌──────────┐      ┌──────────┐
│Explore │      │  Plan    │      │ Execute  │
│ Agent  │      │  Agent   │      │ (Self)   │
└────────┘      └──────────┘      └──────────┘
"where"         "how should"       Everything
"find"          "design"           else
"search"        "architecture"
```

### Complexity → Model Routing
```
Simple (typo, config)     → Haiku-level reasoning
Medium (feature, handler) → Sonnet-level work
Complex (guards, debug)   → Opus-level analysis
Exploration               → Subagent (fresh context)
```

---

## ITERATION 10: Implementation Plan

### Phase 1: Create QUICK.md (The One File)
- Condense Laws 1-8 to one-liners
- Current version + active task
- Last 3 decisions made
- Domain pointers ("see domains/translation.md for guards")

### Phase 2: Split Reference Material
- Move architecture diagrams to reference/ARCHITECTURE.md
- Move testing details to reference/TESTING.md
- Move detailed law explanations to reference/LAWS.md

### Phase 3: Create Domain Files
- translation.md: Guards, chunking, bridge, language profiles
- ui.md: Components, menus, callbacks
- handlers.md: Message routing, state management
- detection.md: GlotLID, script DNA, character DNA

### Phase 4: Compress History
- Merge LESSONS.md + FAILED_ATTEMPTS.md → wins.md + fails.md
- Use dense format (emoji indicators, one-liners)

### Phase 5: Create Skill Definitions
- Each skill in separate .md file
- Contains: triggers, agent, procedure, examples

---

## KEY INSIGHTS

### 1. Lazy Loading is Critical
Don't load everything. Load:
- QUICK.md always (~80 lines)
- Domain file only when working on that domain
- Reference only when explicitly needed

### 2. Skills Enable Reuse
Pattern → Skill → Automatic trigger
No need to re-explain workflows each session.

### 3. Compression Preserves Signal
Dense format with emoji indicators:
- ❌ = failed attempt
- ✅ = what worked
- ⚠️ = gotcha/warning
- 💡 = key insight

### 4. Domain Isolation Prevents Bloat
Each domain file only contains domain-specific lessons.
Cross-domain patterns go in QUICK.md.

### 5. Auto-Delegation Saves User Effort
User shouldn't think about agents/models.
Pattern detection → Automatic routing.

---

*Analysis completed: 10 iterations*
*Token savings potential: 76-88% on typical sessions*
