coco-research/coco/brain-init

/brain:init --- Initialize Project Brain

Sets up a new project_brain.db in the current working directory and bootstraps it from existing project knowledge.

Procedure

Step 1: Check existing state

Run:

python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py info

• If no DB exists → proceed to Step 2 (full init)
• If DB exists with project(s) → skip to Step 3 (scan only). Tell user: "Brain already initialized. Running scan for new/changed files..."

Step 2: Create the database and project record

Run:

python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py init

Ask the user:

• Project name (e.g., "My Project A", "My Project B")
• Slug (short URL-safe identifier, e.g., "my-project-a", "my-project-b")
• Description (one-liner)

Then run:

python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py add-project "{name}" --slug {slug} --desc "{description}"

If the project has sub-scopes (like ProjectA-Phase1 and ProjectA-Phase2 under one umbrella), ask if the user wants multiple project records.

Step 3: Scan the project folder

Run the scanner to discover what's available:

python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py scan

This returns a JSON report with:

• manifest_diff: new/changed/unchanged file counts, whether this is the first scan
• files_to_process: paths of new or changed files
• knowledge_sources: which CLAUDE.local.md, memory files, docs, and emails were found

Show the user a summary:

FOLDER SCAN
===========
First scan:     yes/no
Files found:    NN total (NN new, NN changed, NN unchanged)
 
Knowledge sources detected:
  CLAUDE.local.md:  found / not found
  CLAUDE.md:        found / not found
  Memory files:     N files (list names)
  Documents:        N files in docs/
  Emails:           N files in emails/
  Reference docs:   N files

If nothing to process (all unchanged): "Everything up to date. No new knowledge to extract." → done.

Step 4: Extract knowledge from sources (Claude-driven)

Process sources in priority order. For each source, read the file, extract structured knowledge, and collect proposed writes. Do NOT write to the brain yet — collect everything first.

Priority 1: CLAUDE.local.md

If found, read the full file. Extract:

• Sections like "Key Decisions" → decisions (with date, decision text, decided_by if mentioned)
• People mentioned by name → person entities (with metadata like role, email, team if mentioned)
• Systems/tools mentioned → system entities (e.g., Snowflake, Postgres, Datadog)
• Teams mentioned → team entities
• Folder structure sections → document entities for key docs
• Recent Changes entries → events (with date, type, title)

Priority 2: Memory files (~/.claude/projects/.../memory/*.md)

Each memory file has frontmatter (name, description, type) and content. Read each file:

• project type memories → decisions or context to enrich existing entities
• feedback type memories → skip (these are Claude behavior guidance, not project knowledge)
• reference type memories → system or document entities with metadata

Priority 3: Document inventory

For each file in docs/, emails/, and Reference Doc/:

• Create a document entity with metadata: {"path": "relative/path", "type": "doc|email|reference", "size": N}
• Use the filename (cleaned) as the entity name
• Do NOT read the full content of every file — just register them in the inventory

Priority 4: CLAUDE.md (project-level, if exists)

Same extraction as CLAUDE.local.md but lower priority (may overlap).

Step 5: Present extraction summary

Show proposed writes:

BRAIN BOOTSTRAP SUMMARY
========================
Project: {name} ({slug})
 
From CLAUDE.local.md:
  Entities:    N (list: name [type])
  Decisions:   N (list: short text)
  Events:      N (list: title)
 
From memory files:
  Decisions:   N (list: short text)
  Entities:    N (list: name [type])
 
Document inventory:
  Documents:   N (list: filename [doc|email|reference])
 
Total proposed writes: NN

Ask: "Write all to brain? [Y/n/adjust]"

Step 6: Execute writes

On confirmation, write in this order using Python:

import sys
sys.path.insert(0, '$HOME/.claude/skills/brain/scripts')
from brain.schema import get_db
from brain.operations import *

1. Entities — use upsert_entity (idempotent, safe to re-run)
2. Relationships — use create_relationship (also idempotent)
3. Decisions — use create_decision (check for duplicates by matching decision text before inserting)
4. Events — use create_event (check for duplicates by matching title + date)
5. Document entities — use upsert_entity with type="document"

After all writes, sync to MemPalace and brain.json:

from brain.memory_bridge import full_sync
full_sync("project_brain.db", project_slug)

After writes complete, update the manifest:

python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py scan-update

Step 7: Report

BRAIN INITIALIZED
=================
DB:            {path}/project_brain.db
Project:       {name} ({slug})
Schema:        v1 (11 tables)
 
Bootstrapped from existing knowledge:
  Entities:      +N (total: N)
  Decisions:     +N (total: N)
  Events:        +N (total: N)
  Documents:     +N (total: N)
  Relationships: +N (total: N)
 
Manifest updated: N files tracked
 
Next: Run /brain-update at end of session, or /brain-rescan when files change.

Step 8: Generate knowledge articles

After completing brain writes (Step 6) and confirming the manifest is updated (Step 6 scan-update), initialize the knowledge engine for this project.

First, register the project with the knowledge engine:

import sys, os
sys.path.insert(0, os.path.expanduser("~/.coco/knowledge"))
from engine import KnowledgeEngine
engine = KnowledgeEngine()
engine.register_project("{slug}", os.path.abspath("project_brain.db"))

This is required before the cron can harvest the project. (FIX M1: register_project must be called before running any cron phases.)

Then, bootstrap article generation:

engine.full_refresh("{slug}")

Or equivalently via CLI:

python3 ~/.coco/knowledge/cron.py --run --project {slug} --phases 2,3,5

This runs:

• Phase 2 (harvest evidence from the brain DB you just populated + infer relationships)
• Phase 3 (generate articles for all entities — first run will generate all)
• Phase 5 (FTS5 index the new articles)

Show the user:

KNOWLEDGE ENGINE
================
Articles generated:  N
FTS5 indexed:        N
Estimated cost:      $0.XXX
 
Articles written to: ~/.coco/knowledge/articles/
Search with: /brain-wiki search "{project_name}"

Skip this step silently if:

• ~/.coco/knowledge/ does not exist (knowledge engine not installed)
• The cron.py call fails for any reason (non-blocking — brain init still succeeds)

Important Rules

• Dedup before writing. Always check what exists in the DB before proposing new writes. Use upsert_entity which handles this automatically for entities.
• Don't read every file. For doc inventory, just register the file — don't parse 130KB HTML files to extract content. That's what /brain-update is for (conversation-driven).
• Date everything. Decisions and events need dates. Parse from the source if available, fall back to file modification date, then today.
• Memory files are structured. They have frontmatter — use the type field to decide what to extract.
• Manifest tracks scan state. Always run scan-update after writes so the next scan is incremental.