7.3 KiB
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:
- Add comment: "Cap reached at 3 review cycles"
- Summarize: "Unresolved issues: [list]"
- Task status →
review(awaiting human) - 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"
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"
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
- Check TOOLS.md for existing projects
- Create in
/Users/mattbruce/Documents/Projects/OpenClaw/[Web|iOS]/ - Update TOOLS.md immediately
- 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.
- Table Names: Always use underscores, never hyphens in Supabase
- Gitea Server: Runs on 192.168.1.128:3000 (NOT localhost!)
- Port 3000: Reserved for Gantt Board dev (don't use for other projects)
- 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:
-
Log to memory file →
memory/YYYY-MM-DD.md- What was requested
- What was decided
- What was done
-
If mistake made → Append to
memory/LEARNINGS.md- What went wrong
- Why it happened
- How to avoid next time
-
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.