Skip to main content
skill CX Codex

brain:init — Claude Code skill: what it does, how to install

brain:init is a Claude Code skill that sets up project_brain.db in the project directory and extracts structured memory from CLAUDE.local.md, docs, and notes.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add coco-research/coco --skill brain:init -a claude-code
Open on GitHub

What brain:init does

This skill initializes a local SQLite database named project_brain.db containing 11 tables. It invokes brain_cli.py to register the project slug, checks for existing database state, and scans directory contents including CLAUDE.local.md, Claude memory files, emails, and documentation.

The agent parses detected files for decisions, system components, people, teams, and change events. Before committing any data, it presents a write summary and asks for approval. Once confirmed, it writes records, synchronizes with MemPalace and brain.json, and triggers the knowledge engine to build FTS5-indexed articles.

The workflow depends on local Python helper scripts placed in ~/.claude/skills/brain/scripts and ~/.coco/knowledge. Re-running the command is safe because entity writes use upserts and decisions are checked against duplicate text.

What it helps with

  • initialize a local SQLite memory store for a project
  • extract decisions and team roles from CLAUDE.local.md
  • index documentation and email archives into an entity catalog
  • generate full-text search articles using FTS5

Example prompts for the agent

  • Run /brain:init to set up memory for this project
  • Execute /brain:init and scan docs/ for knowledge extraction
  • Initialize project_brain.db from CLAUDE.local.md using /brain:init

How to install brain:init

1Skills CLI (Vercel)

npx skills add coco-research/coco --skill brain:init -a claude-code

2Manually: put the files in place

~/.claude/skills/brain-init/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/brain-init/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about brain:init

How do I install brain:init in Claude Code?

Run npx skills add coco-research/coco --skill brain-init -a claude-code. Alternatively, copy the skill specification to ~/.claude/skills/brain-init/SKILL.md.

What does brain:init do?

It builds a structured SQLite database named project_brain.db and populates it with entities, decisions, and documents found in local files.

Can brain:init run on a project that is already initialized?

Yes. If an existing database is detected, the skill skips schema creation and only scans for new or modified files.

Source text

SKILL.md · MIT
---
name: brain:init
description: "Use when setting up project memory in a new folder or on the first brain:init in a project. Creates project_brain.db, registers the project, and bootstraps it from CLAUDE.local.md, memory files, docs, and emails; safe to re-run."
---

# /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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```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:
```python
from brain.memory_bridge import full_sync
full_sync("project_brain.db", project_slug)
```

After writes complete, update the manifest:
```bash
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:**

```python
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:**

```python
engine.full_refresh("{slug}")
```

Or equivalently via CLI:

```bash
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.

© coco-research · MIT · coco-research/coco

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set82

The whole set →
arch Command to build and validate .arch/index.json, which maps each architecture component to the files implementing it. Detects when files and component descriptions have drifted apart. CX Codex +1 ★ 328repo stars develop develop runs a multi-agent build and bugfix pipeline that shards file edits across specialized agents and validates changes with regression evidence. CX Codex +1 ★ 328repo stars data-specialist data-specialist — a subagent for exploratory data analysis, machine learning workflows, and SQL query tuning across PostgreSQL, MySQL, SQL Server, and Oracle. CX Codex ★ 328repo stars media-use media-use is a skill for HyperFrames projects that finds music, sound effects, icons and logos, creates voiceover, and edits existing footage. CX Codex +1 ★ 328repo stars pmstudio-sync The pmstudio-sync skill turns changes in source files into proposed updates for linked PRDs, decks, and notes. It waits for approval before editing. CX Codex +1 ★ 328repo stars agent-lightning A reference skill for Microsoft's Agent Lightning: instrument an agent, collect traces, then run reinforcement learning or prompt tuning on top of them. CX Codex +1 ★ 328repo stars sync-init sync-init automates project background sync every 2 hours: monitors Outlook emails, checks watched folders for changes, and refreshes documents via Claude CLI. CX Codex +1 ★ 328repo stars test Runs the complete test cycle: coverage analysis, test generation, and regression validation. Call it to fill coverage gaps or verify the test suite runs end-to-end. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open