---
name: brain-file-reading
description: What is actually inside a claw's .brain, which sections reach a prompt, and which are stored but never read.
when_to_use: You are inspecting an agent's brain to judge whether its definition matches what it does.
tags: [platform, brain]
---

# The brain is one HDF5 file, and most of it is not in the prompt

A `.brain` is a key/value store (`cm-brain`) holding an agent's definition. The
important thing to know before drawing conclusions from one: **stored is not the
same as used**.

## The sections

| key | reaches the model? |
|---|---|
| `identity/system_prompt` | **yes** — the system prompt |
| `identity/persona` | no |
| `identity/agent_md` | no — "how I operate", stored only |
| `identity/soul_md` | only as a fallback when `system_prompt` is empty |
| `skills/<name>` | via the role's bound skills, not from here |
| `tools/<name>` | state (`gated`/`blocked`), not prose |
| `memory/<ts_nanos>` | **yes, on the chat path** — recalled by keyword |
| `runtime/clawmates` | no — opaque JSON |
| `provenance/clawmates` | no — **a wired slot with no callers** |

`persona` and `agent_md` being stored-but-unused is deliberate and easy to
misread: an agent whose `agent_md` describes careful behaviour it does not
exhibit is not disobeying — it never saw it.

## Memory is chat-only

`remember`/`recall` are driven from the chat turn path. **Mission and phase work
never touches the brain**, so an agent that did a week of mission work has an
empty memory section. Do not conclude from that it did nothing.

Recall is BM25 keyword, not semantic: a memory phrased differently from the
query will not surface. "The agent forgot" is more often "the query did not
share words with the memory".

## Read the revisions, not just the current state

The brain is versioned (`.onion` sidecar, `commit`/`revisions`/`rollback`). The
history shows what was changed and by what — seeding, a level-up consolidation,
a human edit. A brain whose only revision is the seed has never been improved,
which is a finding about the loop, not about the agent.

## What to report

Whether the definition and the behaviour agree, and which section is responsible.
"The system prompt says X, the agent did Y" is actionable. "The brain contains
X" is not, until you have said whether X reaches the model at all.