| 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.
tail -n 30 .cerebra/brain/worklog.md
cat .cerebra/brain/semantic/facts/*.json 2>/dev/null | head -50
cat .cerebra/brain/semantic/world_model/db_state.md 2>/dev/null
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
cerebra brain resume
cerebra brain status
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.
