222 lines
7.3 KiB
Markdown
222 lines
7.3 KiB
Markdown
# 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-22 | Complete Phases 6-9 |
|
|
| Gantt Board | Maintenance | 2026-02-20 | Bug fixes as needed |
|
|
| Blog Backup | Maintenance | 2026-02-18 | Daily digest running |
|
|
|
|
---
|
|
|
|
## 🧠 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.
|