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
npx skills add coco-research/coco --skill brain:init -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/brain-init/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/brain-init/
1Skills CLI (Vercel)
npx skills add coco-research/coco --skill brain:init -a codex2Manually: put the files in place
.agents/skills/brain-init/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add coco-research/coco --skill brain:init -a cursor2Manually: put the files in place
.cursor/skills/brain-init/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install coco-research/coco systems/brain/skills/brain-init2Manually: put the files in place
.github/skills/brain-init/SKILL.md1Skills CLI (Vercel)
npx skills add coco-research/coco --skill brain:init -a gemini-cli2Platform CLI
gemini skills install https://github.com/coco-research/coco --path systems/brain/skills/brain-initManually: put the files in place
.devin/skills/brain-init/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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