cerebra-brain

name

cerebra-brain

description

Read and write this repository's persistent memory. Use at the START of any non-trivial task to recall what is already known, and whenever you need project-specific facts, prior decisions, database shape, or what other sub-agents are doing. Triggers on "what do we know about", "have we done this before", "check memory", "why was this built this way", or any task touching code you have not read this session.

cerebra brain

This repository has a persistent memory at .cerebra/brain/. It survives across sessions. You are running inside cerebra, which owns that memory — you read from it directly, and cerebra writes to it on your behalf.

Before you start work

Read memory before acting on any non-trivial goal. It is cheap and it stops you re-deriving things the project already settled.

# 1. What happened recently
tail -n 30 .cerebra/brain/worklog.md

# 2. What is durably known (one JSON file per fact)
cat .cerebra/brain/semantic/facts/*.json 2>/dev/null | head -50

# 3. What the database looks like, if this project has one
cat .cerebra/brain/semantic/world_model/db_state.md 2>/dev/null

# 4. What other agents are working on right now
cat .cerebra/brain/working/claims.jsonl 2>/dev/null

Or let cerebra rank facts for you against a question:

cerebra recall "how does auth work"

Do not write to memory yourself

Never edit anything under .cerebra/brain/ directly. Not the worklog, not the facts, not the claims file.

cerebra records automatically:

What	When
worklog line	every tool call, via the PostToolUse hook
durable facts	when a sub-agent finishes, distilled from its diff
durable facts	at session end, distilled from the worklog
world model	at consolidation, from .cerebra/brain/schema.sql

Facts are extracted by you — cerebra calls claude -p with the diff or worklog and asks for a JSON array of durable statements. That is the only way memory is written. cerebra has no model of its own.

Manual writes corrupt the consolidation offset and collide with the hooks.

If memory is halted

Memory is off by default in a repository. When .cerebra/brain/ does not exist, or brain.toml says memory = "halted", nothing is recorded and the read commands above return nothing.

That is a valid state, not an error. Do not try to create the directory yourself. If the user wants memory on, tell them:

cerebra brain init      # create the brain, start recording
cerebra brain resume    # un-halt an existing brain
cerebra brain status    # check which state you are in

What belongs in memory

When cerebra asks you to extract facts, a good fact is a standalone statement that stays true after the current change lands:

• ✅ the auth route is at /api/v1/auth and expects a bearer token
• ✅ users are soft-deleted; queries must filter deleted_at IS NULL
• ✅ tests run against sqlite in-memory, not the dev postgres
• ❌ changed 3 files — not durable
• ❌ fixed the bug — not specific
• ❌ I ran pytest and it passed — an event, not a fact

Claim before you act

Concurrent sub-agents coordinate through .cerebra/brain/working/claims.jsonl. Before starting a task, check whether its task_id already has an open claim:

grep '"task_id":"<id>"' .cerebra/brain/working/claims.jsonl

An entry with "status":"claimed" and no later "status":"done" means someone else owns it. Pick different work. The PreToolUse hook also enforces this and will block the call with a reason.

Layout reference

.cerebra/brain/
  brain.toml                        config; its existence = memory is on
  worklog.md                        episodic — every tool call
  working/                          cleared between sessions
    claims.jsonl                    task coordination
    active_agents.json              governor slots (max 3)
    scratch/                        your ephemeral notes — writing here IS allowed
  semantic/                         durable
    facts/<id>.json                 one fact per file
    vectors/<id>.npy                only in vector retrieval mode
    world_model/db_state.md         compressed database digest

working/scratch/ is the one place you may write freely — it is yours, and it is cleared at session end.