how a folder gets its voice · ← concepts
A persona is a PERSONA.md file in a group folder that shapes how the agent speaks for that folder. The file’s YAML frontmatter feeds structured fields like the TTS voice and a short re-anchor block; the body is the long-form register the agent reads on demand.
One file per group, at <data-dir>/groups/<folder>/PERSONA.md. The operator edits it directly — via WebDAV, an editor on the host, or the dashboard. There is no persona table; the file is the source of truth.
Standard YAML frontmatter, delimited by ---:
---
name: Atlas
summary: Direct, no preamble. Defaults to short answers. Lowercase info, capitalized errors.
voice: nova
---
# full persona
Long-form description of register, tone, taboo words, in-jokes,
worked examples, … loaded on demand by the /persona skill.
name — display name used in the per-turn <persona name=...> envelope. Defaults to the folder path when omitted.summary — one-paragraph re-anchor injected on every turn. Keeps register stable across long sessions.voice — TTS voice id read by send_voice when no voice argument is passed. Falls back to the instance-wide TTS_VOICE env.On every inbound turn, gateway.personaBlock(folder) reads the file, parses the frontmatter, and emits:
<persona name="Atlas">
Direct, no preamble. Defaults to short answers. Lowercase info, capitalized errors.
(For full register: /persona)
</persona>
The block sits next to the autocalls envelope inside the user message, so the agent re-anchors its voice even when the system prompt has drifted out of focus after many turns. The body of PERSONA.md is not injected per turn — the agent invokes the /persona skill when it wants the full register.
If PERSONA.md is missing, has no frontmatter, has no summary field, or the summary is empty, personaBlock returns "". No fallback to body text, no guessing from the folder name, no inheritance from a parent folder’s persona. The agent simply runs in its default register.
This is deliberate. A magical fallback would mean “the persona block sometimes contains operator data, sometimes contains a guess” — the agent could not tell which. Strict-or-empty keeps the contract sharp.
Personas live with the group, not with the agent image. Edits to PERSONA.md take effect on the next turn — no migration, no rebuild. The agent image ships skills and base prompts; the group ships voice. Releases bump MIGRATION_VERSION for skill changes, never for persona edits.
Canonical spec: specs/4/P. The TTS path that reads the voice field: voice. How groups, folders, and per-folder files compose: scopes.