04 — brain-config.yaml
What you will have at the end: a brain that declares its agents and wakes them when something happens in it.
What you need: tutorial 02 finished, and the agent runner from tutorial 03 if you want the triggers to actually fire.
What the file is
brain-config.yaml sits at the root of a brain and declares two things: the agents the brain expects, and what wakes them. A third key, sessions-per-hour, is where a brain lowers what any one of its agents may cost; it may only lower the runner's own ceiling of ten, never raise it. A fourth, timezone, is the brain's own clock, which a schedule written as a cron: is read in.
It is the only file in a brain that is neither markdown nor an image. The name is exact and it only works at the root. Create it from the actions palette with Ctrl+Shift+P: New Brain Configuration is offered while the file is absent and you can edit the brain, and it writes a commented example.
An agent can use this file like any other only as a brain keeper, which the brain's owner makes it in brain settings; a brain can have more than one. A brain keeper can read it and change it; every other agent, whatever its role, cannot see it at all. People are unaffected: a person editor or admin changes it, and a person viewer reads it. Tutorial 05 lays out every level. Its save takes effect at once, exactly as yours does: the triggers it writes are armed the moment it saves, and it is told which ones did not arm and why. That is what lets you ask an agent to design a brain for you and have it run.
The file is validated as you type. A mistake in the file is marked on the line that caused it. A folder the brain does not have, or a trigger naming an agent the file never declares, is reported by the badge on the file's row in the explorer; hover it to read what is wrong. Either way, a broken config is visible without opening it. An agent declared under agents: that this brain does not have is reported the same way: the badge on the file's row names it, and it is underlined on its own line when you open the file. It is not an error in the file, since a brain can be copied before its agents arrive, and the triggers that name it simply have nobody to wake until it exists.
The roster
version: 1
agents:
note-taker-bot: brain_keeper
assessor-bot: editor
dev-bot: editor
review-bot: editor
version is required and is 1 today.
agents maps an agent's name to the role it holds here. The role is viewer, editor or brain_keeper, and there is no default. admin is refused, and only the brain's owner can set up an agent declared brain_keeper.
The roster is what a brain declares about itself, and it travels when the brain is copied. On a fresh copy, the file's row is marked, and each declared agent the brain lacks is underlined in the open file, until it exists, and right-clicking the file offers Set up this brain's N agents… (or Set up and the agent's name, when only one is missing), which creates them and grants the role in one step. That is the fastest route to a working brain, and it is easier than creating each agent by hand in organization settings.
Once the file has an agents roster, a trigger may only name an agent on it.
Triggers
Each trigger says what happened, who to wake, and what to tell them.
Three keys are common to all of them. kind is what happened. agent is who gets woken. prompt is what that agent is told to do when it wakes. There is also an optional label, which is for you rather than for the agent. It also names the trigger: two triggers that wake the same agent for the same folder are told apart by their labels, and changing a label makes it a different trigger, so anything it had not yet picked up is dropped.
Every trigger is scoped to something named: a folder, a file, an agent or the clock. There is no wildcard over the whole brain.
A file arrives in a folder
triggers:
- kind: file-arrived
label: An idea arrives and is assessed
folder: 01-ideas
agent: assessor-bot
prompt: Assess the idea that just arrived at {path} (id {id}). Ground it in the
actual code, cite the files and lines you mean, and lay out the options
worth choosing between. Do not pick one.
file-arrived takes a folder. A file created in it or moved into it counts, at any depth. Each arrival is handed over on its own, once that file has gone a minute without being written to.
A named file changes
- kind: file-changed
label: Work is queued for review
file: review-bot-todo.md
agent: review-bot
prompt: Read `review-bot-todo.md` at {path} (id {id}) and work every item that is
not struck through, oldest first.
file-changed takes a file, which is one named path from the root of the brain rather than a folder, and it must be a markdown document. A burst of edits to that file is gathered into one waking rather than one per keystroke.
This is the kind that carries handoffs. Nothing in a brain can see your repository, so when an agent finishes work outside the brain it writes a line into a file, and that file changing is what wakes the next agent.
An agent is mentioned
- kind: agent-mentioned
label: answer my mentions
agent: review-bot
prompt: You were mentioned. Read what mentions you and answer it.
agent-mentioned takes neither a folder nor a file. It watches an agent, and it fires when that agent is @mentioned anywhere in the brain.
It wakes the agent once per thread. Mentions on one thread within a minute or so of each other are one waking, so an ask and its correction arrive together; mentions on two threads are two wakings, each about its own thread. A mention written into a document is a waking for that document. A mention that arrives after its thread's waking has been taken starts a new one.
On a clock
timezone: Europe/Madrid
triggers:
- kind: schedule
label: The weekly round
cron: "0 9 * * MON"
agent: review-bot
prompt: Check in, read your brief, then do your rounds. This round was due at {due}.
schedule takes neither a folder nor a file. It fires because time passed rather than because anything was written, and it takes exactly one of every and cron. every: 4h fires four hours after the last firing, in whole hours, days or weeks (4h, 1d, 2w). cron: is five fields, minute, hour, day of month, month and day of week, read in the brain's timezone, which the file must then name at its top as a zone name like Europe/Madrid or UTC. Quote every cron string: a value that starts with * is not read at all when it is written bare. The fastest either form can fire is once an hour.
every: 1d is not "daily at nine". Twenty-four hours is fixed, so a 1d schedule drifts an hour when the clocks change, and cron: "0 9 * * *" is the form for a time of day.
Saving a schedule does not fire it: every: first fires one full interval after the save, and cron: at its first occurrence after it. A schedule fires at most once per occurrence, on the first runner poll after it is due, which in a quiet brain can be up to 45 minutes late, and a runner that was off fires a missed schedule once rather than once for each occurrence it missed.
Every firing is a session, whether or not there is anything to do: an hourly schedule is 168 sessions a week, so start weekly. Give each schedule a label. Two schedules for one agent without one are told apart by their order, so reordering them swaps their memories of when each last fired.
Writing prompts
The prompt is the whole point of a trigger. Nothing else says what the session is for.
{path} and {id} are replaced with the file that caused the trigger, on the two kinds where a file caused it. On a schedule, {due} is replaced with the moment the firing was due, so a prompt can decide for itself whether a late one still matters; that needs mdbrain 0.8.0 or later. On agent-mentioned, {mentions} is replaced with a sentence naming the thread and the comments, or the document, this waking is for, such as 3 mentions on thread …: comments …, … and ….; that needs mdbrain 0.9.0 or later.
Prompts can be long. YAML continues a value across lines as long as the continuation is indented further than the key, so a prompt can be a paragraph:
prompt: Build the spec that just arrived at {path} (id {id}) in the repository.
Match the spec in the code, implement every one of its scenarios as a
unit test, and open a pull request. Build what the spec says and no
more; anything the spec did not ask for goes on a comment thread, not
into the branch.
Two habits worth copying from the software engineer brain.
Start the prompt by telling the agent to check in and read its own brief. The prompt is a nudge; WHOAMI.md carries the real instructions, and a prompt that repeats them is a second place to keep them current.
End it by telling the agent to notify you. An agent that finishes silently in a brain nobody is watching has done nothing. Where the agent genuinely cannot continue without a decision, have it notify with agent_blocked rather than agent_finished, which distinguishes "here is a thing, look when you like" from "I am stopped until you choose".
A pool of agents
A list in agent is a pool rather than a broadcast, on every kind but agent-mentioned:
- kind: file-arrived
label: A review lands and whoever is free takes it
folder: 04-reviews
agent: [dev-bot, review-bot]
prompt: Read the review and act on what it asks of you.
Each arrival, and each firing of a schedule, is one piece of work, and whichever member is free takes it. Forty files arriving at once are split across the pool.
agent-mentioned is the exception and is refused a list: a mention names one handle, and an agent reads only its own mentions, so there is no queue for a pool to share.
Two separate triggers naming two agents is the other thing: both are woken for every arrival.
Adding brackets around a name that had none makes it a different trigger, so anything it had not yet picked up is dropped. Write a pool as a list from the start if it might grow.
What you have now
A brain that declares who works in it and what wakes them. With the runner from tutorial 03 listening, dropping a file into a folder is enough to start work.