/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
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)
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)
Wait for user confirmation ("looks good" / "y" / adjustments)
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
1---2name: brain3description: "Use when the user says brain, project knowledge, what do we know about, open tasks, or recent decisions, or runs /brain or /brain-update. SQLite project_brain.db tracker for entities, relationships, tasks, threads, decisions, events."4metadata:5 source: https://skillmd.com/skills/coco-research/brain6---78# /brain --- Project Knowledge Tracker910A structured SQLite database (`project_brain.db`) that lives in each project folder, replacing flat markdown memory files with queryable, relational knowledge.1112## Quick Reference1314```bash15BRAIN="python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py"1617# Initialize in current project folder18$BRAIN init1920# Create a project21$BRAIN add-project "My Project" --slug my-project --desc "Example project description"2223# Add entities (upsert --- safe to run repeatedly)24$BRAIN add-entity my-project person "Alice Example" --external-id 288225$BRAIN add-entity my-project team "Engineering" --external-id 3326$BRAIN add-entity my-project module "PlatformHub"2728# Add relationships29$BRAIN add-rel 1 2 member_of30$BRAIN add-rel 1 3 administers3132# Tasks33$BRAIN add-task my-project "Configure external reviewer access" --priority 134$BRAIN update-task 1 --status in_progress35$BRAIN tasks my-project --status open3637# Threads (group related work)38$BRAIN add-thread my-project "External User Access" --category request39$BRAIN link-thread 1 task 140$BRAIN link-thread 1 decision 14142# Decisions43$BRAIN add-decision my-project 2026-04-08 "Use Stakeholder role for external users" \44 --context "No license consumed, view-only" --decided-by You4546# Events47$BRAIN add-event my-project 2026-04-08 call "Charlie Customer Call" \48 --summary "Priorities deck shared" --participants "Alice,Bob,Charlie,You"4950# CoCo context (session start)51$BRAIN context my-project5253# Search across everything54$BRAIN context my-project --search "Morgan"5556# Entity graph (show all connections)57$BRAIN graph 15859# Thread detail (show all linked items)60$BRAIN thread-detail 161```6263## /brain:update --- End-of-Session Flush6465**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.6667### Procedure68691. **Scan the full conversation** from top to bottom. For each project in the brain DB, extract:7071 **New entities** --- any person, team, role, system, or module mentioned for the first time72 **New relationships** --- any connection between entities discovered (X owns Y, A reports to B, etc.)73 **New decisions** --- anything that was decided, agreed, confirmed, or resolved74 **New events** --- meetings, calls, emails read, milestones hit75 **New tasks** --- action items, to-dos, next steps, follow-ups76 **Task updates** --- tasks that changed status (done, blocked, in_progress)77 **Entity updates** --- new info about existing entities (role change, new metadata)78792. **Present a summary table** to the user showing what will be written:80 ```81 BRAIN UPDATE SUMMARY82 ====================83 New entities: 3 (Alice Chen, Bob Kumar, ...)84 New decisions: 2 (Use Stakeholder role, Sandbox all-or-nothing)85 New events: 1 (Charlie CSM call Apr 8)86 New tasks: 4 (Get reviewer details, Get sandbox access, ...)87 Task updates: 2 (task #3 -> blocked, task #5 -> blocked)88 New relationships: 1 (Alice administers Platform)89 Entity updates: 1 (Charlie Sohn: added CSM role metadata)90 ```91923. **Wait for user confirmation** ("looks good" / "y" / adjustments)93944. **Execute all writes** via Python operations and report counts.9596### When to prompt the user9798If the conversation has been long (>10 exchanges) and the user hasn't run `/brain:update`, gently suggest it:99> "We've covered a lot this session. Want me to run `/brain:update` to capture everything before we wrap?"100101Do NOT auto-run it. Always wait for the user to invoke or confirm.102103## Behavior Rules104105### Auto-write (no confirmation needed)106- Entity sync from your custom MCP (roles, teams, users)107- Changelog entries when entities are updated108- Task status updates109- Event logging from emails and meetings110111### Confirm-write (propose to user first)112- New decisions113- New relationships between entities114- Deleting or archiving entities115116### Semi-auto (extract and confirm)117- After reading emails: propose entities, events, tasks to add118- After meeting notes: propose decisions, action items, new stakeholders119120## DB Location121122Each project folder gets its own `project_brain.db`:123```124MyProject/project_brain.db125E&C/project_brain.db126Optimize/project_brain.db127```128129CoCo aggregates across all known DBs at session start.130131## Memory Architecture132133The brain DB is the **source of truth** for all project knowledge. It syncs to two other stores:134135| Store | Backend | What syncs | Why |136|-------|---------|-----------|-----|137| **MemPalace** | ChromaDB (~/.mempalace/palace) | Entities, decisions, events → drawers | Semantic search across projects |138| **brain.json** | JSON (~/.coco/brain.json) | Person entities → people section | CoCo people graph, attention rules |139140Sync happens automatically at end of `/brain-update`, `/brain-init`, and `/brain-rescan` via `brain.memory_bridge.full_sync()`.141142**Write path:** Always write to brain DB first → sync propagates to other stores.143**Read path:** Use Memory Bus (`memory_search`) for cross-store federated queries, or brain CLI for structured queries.144145## Schema (v1)14614711 tables: `projects`, `entities`, `relationships`, `tasks`, `threads`, `thread_items`, `decisions`, `events`, `changelog`, `tags`, `taggables`148149Entity types: person, team, role, system, module, org_unit, document150Relationship types: member_of, owns, administers, reports_to, depends_on, blocks, scoped_to, created_by151Task statuses: open, in_progress, blocked, waiting, done, cancelled152Thread categories: feature, incident, request, decision, research153Event types: meeting, email, call, milestone, deploy