cerebra-brain

name	cerebra-brain
description	Read and write this repository's persistent memory under Codex. Use at the start of any non-trivial task to recall prior decisions, project facts, database shape, and what other sub-agents are doing.

cerebra brain (Codex)

This repository has a persistent memory at .cerebra/brain/. It survives across sessions. cerebra owns it; you read from it and cerebra writes to it on your behalf.

Codex has no hook surface, so cerebra cannot record your tool calls automatically the way it does under Claude Code. That makes the discipline below more important, not less — see docs/codex-parity.md for the full gap list.

Before you start work

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

# 2. What is durably known
cat .cerebra/brain/semantic/facts/*.json 2>/dev/null | head -50

# 3. Database shape, if any
cat .cerebra/brain/semantic/world_model/db_state.md 2>/dev/null

# 4. What other agents hold
cat .cerebra/brain/working/claims.jsonl 2>/dev/null

Or have cerebra rank facts for you:

cerebra recall "how does auth work"

Do not write to memory yourself

Never edit anything under .cerebra/brain/ directly, with the single exception of working/scratch/.

Under Codex the daemon polls the worklog to decide whether the session is still active. Writing to it by hand resets that idle timer and suppresses the consolidation that would otherwise turn your session into durable memory.

Facts are extracted by you, through codex exec — cerebra hands you a diff or a worklog chunk and asks for a JSON array of durable statements. That is the only path by which memory is written.

If memory is halted

Memory is off by default. When .cerebra/brain/ does not exist, or brain.toml says memory = "halted", nothing is recorded and the reads above return nothing. Do not create the directory yourself; tell the user:

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

Dispatching sub-agents

Codex has no Task tool. Use the shim:

cerebra spawn-subagent <role> <task_id> --intent "<one line>"

Roles: planner, coder, tester, consolidator.

Each call acquires a governor slot, claims the task, creates a git worktree, runs codex inside it with memory-assembled context, then distils the resulting diff into facts. Exit code 2 means the governor is at capacity — queue the work and retry after a sub-agent finishes.

Sub-agents under Codex run sequentially, one at a time.

Claim before you act

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

An entry with "status":"claimed" and no later "status":"done" means the task is owned. Pick different work.

cerebra spawn-subagent claims for you. Only claim manually when you do work without dispatching — and Codex has no PreToolUse hook to catch a mistake, so check first.

What belongs in memory

• ✅ the auth route is at /api/v1/auth and expects a bearer token
• ✅ users are soft-deleted; queries must filter deleted_at IS NULL
• ❌ changed 3 files, fixed the bug, ran the tests

Layout reference

.cerebra/brain/
  brain.toml                        config; its existence = memory is on
  worklog.md                        episodic — do not hand-edit
  working/
    claims.jsonl                    task coordination
    active_agents.json              governor slots (max 3)
    scratch/                        yours to write freely
  semantic/
    facts/<id>.json                 one fact per file
    world_model/db_state.md         compressed database digest
  roles/                            sub-agent role briefs