# BRAIN.md - External Memory System

**Purpose:** Structured external memory to reduce context window usage and improve recall accuracy.

**Rule:** If it's not in BRAIN.md, it doesn't exist. Context window is for *active* work only.

---

## 🎯 Active Projects (Top 3 Only)

*Keep only the 3 most active projects here. Archive others to memory files.*

| Project | Status | Last Update | Next Action |
|---------|--------|-------------|-------------|
| Mission Control | In Progress | 2026-02-25 | Complete dashboard Phases 6-9 |
| Gantt Board | Maintenance | 2026-02-25 | CLI fixes, auto-spawning |
| Scrapling Integration | In Progress | 2026-02-25 | Install and integrate MCP server |

---

## 🧠 Key Decisions Log

*Recent architectural or strategic decisions with rationale.*

**2026-02-22: Memory Optimization Implementation**
- **Decision:** Applied Ramya's memory optimizations (BRAIN.md, write discipline, heartbeat state)
- **Rationale:** Token bloat was causing slower responses and missed context
- **Impact:** Reduced skill load, structured memory system

**2026-02-20: Mission Control Architecture**
- **Decision:** Phased approach (dashboard first, automation later)
- **Rationale:** Vox's article showed closed-loop requires solid foundation
- **Impact:** Focus on read-only Phases 6-9 before auto-proposals

---

## 🤖 Subagent Orchestration Rules (MANDATORY)

**When spawning Bob, Alice, or Charlie, these rules are NON-NEGOTIABLE:**

### 1. Progress Comment Requirement
- Subagent MUST add task comment every **15 minutes** using format:
  ```
  [YYYY-MM-DD HH:MM] 🔄 In Progress
  **What was just done:** [completed items]
  **What is next:** [immediate step]
  **What is left to do:** [remaining checklist]
  ```
- Use: `./scripts/task.sh update <id> --add-comment "..."`

### 2. Timeout Behavior
- If subagent times out, it MUST have either:
  - Marked task complete, OR
  - Added comment explaining blocker
- **Never let subagents die silently**

### 3. My Responsibility (Max)
- Check subagent status every 20 minutes during active work
- If no comment in 20 min → investigate immediately
- If user asks "what's happening with X" → I failed, not the subagent

### 4. Spawn Instructions Template
Always include in task spawn:
```
**CRITICAL RULES:**
1. Read your SOUL.md at /Users/mattbruce/.openclaw/workspace/agents/[your-name]/SOUL.md
2. Add progress comment every 15 minutes
3. DO NOT timeout without finishing OR explaining blocker
4. DO NOT mark task as done - end with "Ready for Charlie" or "Needs fixes"
5. You have [X] minutes
```

### 5. Task Status Rules (VIOLATION = REOPEN)
**Bob (Implementer):**
- ✅ CAN: Mark task "in-progress" when starting
- ❌ CANNOT: Mark task "done" or "review" 
- ✅ MUST: End with "Ready for Charlie" announcement
- **SOUL.md:** `/Users/mattbruce/.openclaw/workspace/agents/bob-implementer/SOUL.md`

**Charlie (Tester):**
- ✅ CAN: Mark task "review" if issues found
- ❌ CANNOT: Mark task "done"
- ✅ MUST: End with "Ready for deploy" or "Needs fixes"
- **SOUL.md:** `/Users/mattbruce/.openclaw/workspace/agents/charlie-tester/SOUL.md`

**Alice (Researcher):**
- ✅ CAN: Mark task "in-progress" when starting
- ❌ CANNOT: Mark task "done"
- ✅ MUST: End with "Ready for Bob" or report to user
- **SOUL.md:** `/Users/mattbruce/.openclaw/workspace/agents/alice-researcher/SOUL.md`

**Human (Matt) only:**
- ✅ CAN: Mark task "done" after validation

---

## 🚧 Cap Gates - Task Admission Control (NEW)

**From Alice's Multi-Agent Research (@aiedge_ patterns, 2026-02-24)**

### Maker-Checker Loop Limits
When Bob implements and Charlie reviews:
- **Maximum 3 review cycles** before human escalation
- Cycle 1: Bob → Charlie reject → Bob revises → Charlie re-reviews
- Cycle 2: Repeat once more
- Cycle 3: **HUMAN DECISION REQUIRED** (Cap reached)

### Cap Gate Triggers
When iteration cap reached:
1. Add comment: "Cap reached at 3 review cycles"
2. Summarize: "Unresolved issues: [list]"
3. Task status → `review` (awaiting human)
4. Human decides: approve / reject / extend cap

### Task Admission Criteria (Before Spawning Subagents)
Before spawning Alice/Bob/Charlie, verify:
- [ ] Task has clear deliverable (not just "research X")
- [ ] Task has defined success criteria
- [ ] Estimated effort < 2 hours (else break down)
- [ ] Required inputs are available

**If any unchecked → Do not spawn, ask human for clarification**

---

## 🔗 URL Research Workflow (For Alice-Researcher)

**Choose the right skill based on user intent:**

### Quick Save (No Analysis)
**When user says:** "Save this", "Add to documents", "Archive this", "Keep this for later"

```bash
sessions_spawn:
  task: "Save URL to documents: [LINK]. Use save-url-to-documents skill. Extract via Tavily, save to Mission Control Documents (Research/[folder]/), report back with location and quick summary. No task creation, no analysis."
  label: "Alice-Save-URL"
  runTimeoutSeconds: 300
```

**Output:** Document only (~5 min)

### Full Research (With Analysis)
**When user says:** "Research this", "Should we use this?", "Analyze this"

```bash
sessions_spawn:
  task: "Research URL: [LINK]. Use url-research-to-documents-and-tasks skill. Full workflow: 1) Extract via Tavily, 2) Save to Mission Control Documents, 3) Read BRAIN.md + TOOLS.md for context, 4) Analyze fit against current infrastructure, 5) Create Gantt task with verdict (ADOPT/EVALUATE LATER/PASS), 6) Attach implementation plan if applicable. Report back with verdict, rationale, and key insight."
  label: "Alice-URL-Research"
  runTimeoutSeconds: 1200
```

**Output:** Document + Task + Analysis + Plan (~15-20 min)

**Key difference:** Save = just archive it. Research = should we use it?

---

## 📋 Recurring Patterns

*Code patterns, conventions, and templates used frequently.*

### Supabase Table Naming
```
<project>_<table> with underscores (NO hyphens)
Examples: mission_control_documents, blog_messages, heartbeat_status
```

### Project Creation Checklist
1. Check TOOLS.md for existing projects
2. Create in `/Users/mattbruce/Documents/Projects/OpenClaw/[Web|iOS]/`
3. Update TOOLS.md immediately
4. Set correct git identity (OpenClaw Bot vs Matt Bruce)

### Git Identity Rules
- **OpenClaw projects:** OpenClaw Bot / ai-agent@topdoglabs.com
- **Matt's projects:** Matt Bruce / mbrucedogs@gmail.com

---

## ⚠️ Gotchas & Lessons

*Mistakes made and how to avoid them.*

1. **Table Names:** Always use underscores, never hyphens in Supabase
2. **Gitea Server:** Runs on 192.168.1.128:3000 (NOT localhost!)
3. **Port 3000:** Reserved for Gantt Board dev (don't use for other projects)
4. **Skills Load:** 58 skills available - check SKILL.md before assuming capability

---

## 🔗 Quick Links

*Frequently accessed resources.*

- Mission Control: https://mission-control-rho-pink.vercel.app/
- Gantt Board: https://gantt-board.vercel.app
- Gitea: http://192.168.1.128:3000
- Supabase Dashboard: https://qnatchrjlpehiijwtreh.supabase.co

---

## 📝 Write Discipline

**After EVERY task, you MUST:**

1. **Log to memory file** → `memory/YYYY-MM-DD.md`
   - What was requested
   - What was decided
   - What was done

2. **If mistake made** → Append to `memory/LEARNINGS.md`
   - What went wrong
   - Why it happened
   - How to avoid next time

3. **If significant context** → Update `MEMORY.md`
   - Only during heartbeat reviews
   - Curated wisdom, not raw logs
   - Keep under 100 lines

**Remember:** Text > Brain. If you don't write it down, it dies with the session.