🧠 Claude Brain: Project Intelligence for AI Teams

The connective tissue that transforms individual agent work into collective team intelligence

🎯 Overview

Claude Brain provides project-level intelligence for Claude Code agents. While individual agents focus on specific tasks, the Brain understands the bigger picture - connecting work across agents, tracking project progress, and building team knowledge.

Think of it as a project manager for your AI team:

• Agents write personal notes as they work (their memory)
• Brain reads all notes and understands the project context
• Brain curates important findings to project channels
• All agents benefit from the collective intelligence

🏗️ Core Architecture

Agent Notes → Brain Curation → Project Knowledge → Team Alignment

The Simple Flow

1. Agents Work: Each agent maintains personal notes about their work
2. Brain Observes: When tasks complete, Brain reviews the work in context
3. Brain Connects: Brain understands how this work relates to the project
4. Brain Shares: Curated insights go to project channels for all agents

💡 Key Concepts

Agent Notes (Personal Memory)

Every agent has a personal notes channel where they document:

• What they tried
• What worked or didn't work
• Decisions they made
• Patterns they noticed

Brain Agent (Project Intelligence)

A specialized agent that:

• Reads ALL agents' notes
• Understands project goals and context
• Connects work across different agents
• Curates knowledge to project channels

Project Channels (Shared Knowledge)

Curated channels maintained by Brain:

• project-status: Current state and progress
• project-solutions: Verified fixes and approaches
• project-decisions: Architectural choices made
• project-patterns: Recurring themes and learnings

🚀 Installation

Claude Brain requires Claude-Slack for the messaging infrastructure.

# One-command install via npx
npx claude-team-brain

# Or clone and install manually
git clone https://github.com/theo-nash/claude-brain.git
cd claude-brain
python3 install.py

The installer will:

1. Install claude-slack if needed (check separately)
2. Set up the Brain meta-agent daemon
3. Configure hooks for automatic reflection enforcement and curation
4. Install channel definitions for claude-slack
5. Initialize the Brain's knowledge base
6. NEW: Add reflection guidelines to all agents automatically

Project channels are automatically created by claude-slack on session start, ensuring consistent structure across all agents.

📝 Automatic Reflection Guidance

Starting with v2.0, Claude Brain automatically teaches all agents how to write good reflections:

• On session start, reflection guidelines are added to each agent's .md file
• Agents learn the proper template and best practices
• Ensures high-quality reflections for Brain analysis
• Only added once per agent (idempotent)

🔄 How It Works

During Agent Work

# Agent writes naturally to personal notes
write_note("""
Fixed the database timeout issue by increasing pool size to 50.
This resolved the errors we were seeing under load.
Response time improved from 5s to 0.5s.
""")

After Task Completion

# Brain automatically reviews (via SubagentStop hook)
brain_prompt = """
Review backend-engineer's recent work:
- They fixed database timeouts
- Also check what frontend-dev and test-writer have been doing
- Consider current sprint goals

Update project channels with connected insights.
"""

Brain's Curation

# Brain writes to project channels
send_channel_message("project-status", """
✅ Performance issues resolved through coordinated effort:
- Backend: Fixed root cause with connection pooling
- Frontend: Added caching to reduce load
- Tests: Confirmed 1000 concurrent users supported
Sprint goal achieved!
""")

Next Agent Spawns

# New agent gets project context
context = get_messages("project-status")  # Current state
context += get_messages("project-solutions")  # Known fixes
context += search_my_notes(task_keywords)  # Personal history

# Agent starts with full context!

🎨 Example Workflow

1. FRONTEND-DEV works on API optimization
   → Writes note: "Added Redis caching, 40% faster"

2. BACKEND-ENGINEER fixes timeouts
   → Writes note: "Increased pool size to 50, fixed timeouts"

3. BRAIN sees the connection
   → "Both are part of performance improvements!"
   → Updates project-status with unified view
   → Creates project-pattern about coordinated optimization

4. NEW-AGENT joins to help
   → Immediately sees: "Team is optimizing performance"
   → Knows: "Redis caching and connection pooling already done"
   → Can contribute without duplicating work

🔒 Reflection Enforcement

Claude Brain ensures quality reflections through two mechanisms:

1. Automatic Guidance (SessionStart Hook)

• Adds reflection templates to all agent .md files
• Teaches agents what makes a good reflection
• Provides examples and best practices
• Only added once per agent (checks for existing guidance)

2. Reflection Blocking (SubagentStop Hook)

• Detects when tasks complete without reflections
• Blocks agent from continuing until reflection is written
• Provides the exact template to use
• Ensures no knowledge is lost

This combination guarantees high-quality reflections for the Brain to analyze.

🧠 The Brain Agent

The Brain is not complex infrastructure - it's just another agent with special responsibilities:

Role: Project Intelligence
Reads: All agents' notes, project history, current goals
Writes: Project channels (status, solutions, patterns)
Triggers: After each task completion (SubagentStop)
Focus: Connect dots that individual agents can't see

Brain's Unique Perspective

| Regular Agent | Brain Agent | |--------------|------------| | "Fix this timeout" | "Three agents hit timeouts - systemic issue" | | "I added caching" | "Caching + pooling = coordinated performance fix" | | "Tests pass now" | "Sprint goal achieved through team effort" | | "This worked for me" | "This is now a team best practice" |

📚 Documentation

• Architecture Overview - System design and information flow
• Agent Memory - How agents maintain personal notes
• Brain Curation - How Brain processes and connects information
• Channel Reference - Complete channel structure and usage
• Getting Started - Quick setup guide

🔧 Configuration

# ~/.claude/claude-brain/config.yaml
brain:
  trigger: "SubagentStop"  # When to activate Brain
  context_window: 20       # Recent notes to review
  
channels:
  project:
    - project-status
    - project-solutions
    - project-decisions
    - project-patterns
  
curation:
  min_task_duration: 5    # Minutes before curation
  include_file_context: true
  breadcrumb_format: "agent:timestamp"

🤝 How It's Different

Traditional Approach: Complex pattern recognition, confidence scoring, synthesis pipelines

Claude Brain: Simple curation by an intelligent agent who understands context

| Complex System | Claude Brain | |----------------|--------------| | Pattern extraction algorithms | Brain reads and understands | | Confidence scoring | Brain judges importance | | Synthesis pipelines | Brain connects dots | | Validation workflows | Brain verifies through context |

🎯 Benefits

• No Knowledge Loss: Every agent's learning persists
• Team Coordination: Everyone knows what others are doing
• Project Alignment: Work stays focused on goals
• Emergent Intelligence: Patterns visible only at project level
• Natural Workflow: Agents just write notes naturally

📄 License

MIT - See LICENSE

🙏 Credits

Built on top of Claude-Slack.

Claude Brain transforms isolated agent work into coordinated team intelligence.