Omar SobhandClaude Opus 5
4358964c05
55 of 85 role skill bindings pointed at skills that were never authored,
so 10 of 11 team templates bound a smaller context bundle than their role
prompts assumed. Three roles bound nothing at all (gpu.bench_engineer,
threejs.shader_author, threejs.perf_engineer) while their prompts described
procedures they had no way to read.
The loader comment at team_template_loader.rs:167 already diagnosed this —
snake_case slugs in TOML against kebab-case skill files — and it was
half-fixed: the kebab names were corrected, the snake_case ones left.
It was invisible because both existing tests assert authored ⊆ referenced
(30/30, green) and the second explicitly declines to check the other
direction. So the failing half was the half nobody asserted.
Resolved every name by one of three explicit choices:
- 23 skills authored where the role genuinely needed the procedure
(gpu, threejs, research, analysis, frontend, mobile, backend, platform)
- renames onto authored skills where one existed in substance, including
the four-near-duplicate cases that collapse onto one real skill
- 22 aspirational references deleted — a binding an agent cannot read is
a promise, not a capability
Two tests now hold it. The unit test checks referenced ⊆ authored against
the files. The new integration test runs both loaders in boot order and
asserts the bindings survive the trip through the database, which is a
different question: resolution goes through skills_catalog rows, so a skill
file that exists but fails to ingest still leaves the role empty.
Negative controls: the unit test failed naming all 55; the integration test
fails naming the exact role when one name is reverted.
threejs.shader_author and .perf_engineer gained a second and third skill
after the collapse — pin_in_context pins idx < 2, so a role left with one
skill silently pins less than the policy intends.
Co-Authored-By: Claude Opus 5 <[email protected]>
54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
---
|
|
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.
|