brain

/brain --- Project Knowledge Tracker

A structured SQLite database (project_brain.db) that lives in each project folder, replacing flat markdown memory files with queryable, relational knowledge.

Quick Reference

BRAIN="python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py"

# Initialize in current project folder
$BRAIN init

# Create a project
$BRAIN add-project "My Project" --slug my-project --desc "Example project description"

# Add entities (upsert --- safe to run repeatedly)
$BRAIN add-entity my-project person "Alice Example" --external-id 2882
$BRAIN add-entity my-project team "Engineering" --external-id 33
$BRAIN add-entity my-project module "PlatformHub"

# Add relationships
$BRAIN add-rel 1 2 member_of
$BRAIN add-rel 1 3 administers

# Tasks
$BRAIN add-task my-project "Configure external reviewer access" --priority 1
$BRAIN update-task 1 --status in_progress
$BRAIN tasks my-project --status open

# Threads (group related work)
$BRAIN add-thread my-project "External User Access" --category request
$BRAIN link-thread 1 task 1
$BRAIN link-thread 1 decision 1

# Decisions
$BRAIN add-decision my-project 2026-04-08 "Use Stakeholder role for external users" \
  --context "No license consumed, view-only" --decided-by You

# Events
$BRAIN add-event my-project 2026-04-08 call "Charlie Customer Call" \
  --summary "Priorities deck shared" --participants "Alice,Bob,Charlie,You"

# CoCo context (session start)
$BRAIN context my-project

# Search across everything
$BRAIN context my-project --search "Morgan"

# Entity graph (show all connections)
$BRAIN graph 1

# Thread detail (show all linked items)
$BRAIN thread-detail 1

/brain:update --- End-of-Session Flush

This is the most important command. When the user runs /brain:update, Claude MUST do a thorough review of the entire conversation and write everything learned to the brain DB. This is a forcing function --- do not skip anything.

Procedure

1. Scan the full conversation from top to bottom. For each project in the brain DB, extract:

   New entities --- any person, team, role, system, or module mentioned for the first time New relationships --- any connection between entities discovered (X owns Y, A reports to B, etc.) New decisions --- anything that was decided, agreed, confirmed, or resolved New events --- meetings, calls, emails read, milestones hit New tasks --- action items, to-dos, next steps, follow-ups Task updates --- tasks that changed status (done, blocked, in_progress) Entity updates --- new info about existing entities (role change, new metadata)

2. Present a summary table to the user showing what will be written:

   BRAIN UPDATE SUMMARY
   ====================
   New entities:      3 (Alice Chen, Bob Kumar, ...)
   New decisions:     2 (Use Stakeholder role, Sandbox all-or-nothing)
   New events:        1 (Charlie CSM call Apr 8)
   New tasks:         4 (Get reviewer details, Get sandbox access, ...)
   Task updates:      2 (task #3 -> blocked, task #5 -> blocked)
   New relationships: 1 (Alice administers Platform)
   Entity updates:    1 (Charlie Sohn: added CSM role metadata)
   

3. Wait for user confirmation ("looks good" / "y" / adjustments)

4. Execute all writes via Python operations and report counts.

When to prompt the user

If the conversation has been long (>10 exchanges) and the user hasn't run /brain:update, gently suggest it:

"We've covered a lot this session. Want me to run /brain:update to capture everything before we wrap?"

Do NOT auto-run it. Always wait for the user to invoke or confirm.

Behavior Rules

Auto-write (no confirmation needed)

• Entity sync from your custom MCP (roles, teams, users)
• Changelog entries when entities are updated
• Task status updates
• Event logging from emails and meetings

Confirm-write (propose to user first)

• New decisions
• New relationships between entities
• Deleting or archiving entities

Semi-auto (extract and confirm)

• After reading emails: propose entities, events, tasks to add
• After meeting notes: propose decisions, action items, new stakeholders

DB Location

Each project folder gets its own project_brain.db:

MyProject/project_brain.db
E&C/project_brain.db
Optimize/project_brain.db

CoCo aggregates across all known DBs at session start.

Memory Architecture

The brain DB is the source of truth for all project knowledge. It syncs to two other stores:

Store	Backend	What syncs	Why
MemPalace	ChromaDB (~/.mempalace/palace)	Entities, decisions, events → drawers	Semantic search across projects
brain.json	JSON (~/.coco/brain.json)	Person entities → people section	CoCo people graph, attention rules

Sync happens automatically at end of /brain-update, /brain-init, and /brain-rescan via brain.memory_bridge.full_sync().

Write path: Always write to brain DB first → sync propagates to other stores. Read path: Use Memory Bus (memory_search) for cross-store federated queries, or brain CLI for structured queries.

Schema (v1)

11 tables: projects, entities, relationships, tasks, threads, thread_items, decisions, events, changelog, tags, taggables

Entity types: person, team, role, system, module, org_unit, document Relationship types: member_of, owns, administers, reports_to, depends_on, blocks, scoped_to, created_by Task statuses: open, in_progress, blocked, waiting, done, cancelled Thread categories: feature, incident, request, decision, research Event types: meeting, email, call, milestone, deploy