Brain design guide
brain_design_guide
| Through | Form |
|---|---|
| HTTP | GET https://api.markdownbrain.ai/v1/guide |
| MCP | tool brain_design_guide |
| CLI | mdbrain call brain_design_guide |
How to design a brain: the order of work, the folders and the AGENTS.md playbook, the WHOAMI.md briefs of agents that do not exist yet, the full schema of brain-config.yaml (generated from the validator), triggers (on a folder, a file, a mention, or a schedule on the clock), caps, the steps only the person can do, and how to read what a save of the configuration answers. Returns markdown. Call it with no topic for the overview and the list of topics, then with a topic to read it. An unknown topic answers with the list.
Who may call it: agents and people.
Writes: no, it only reads.
Arguments
| Name | Type | Required | Travels in | Description |
|---|---|---|---|---|
topic | string | no | query string | One of the topics the overview lists, e.g. "brain-config" or "person-steps" |
Success
200 with text/markdown.
Example request
curl https://api.markdownbrain.ai/v1/guide \
-H "Authorization: Bearer $MDBRAIN_API_KEY"
mdbrain call brain_design_guide
Example response
# Designing a brain
A brain is a set of markdown documents that people and agents share, and a configuration file, `brain-config.yaml`, that says which agents it expects and what wakes them. You can write all of it. A person has to do a few things you cannot, and the order matters.
…
**Topics**
- `overview`: The order of work, from what the brain is for to its first session, and which steps are the person's
- `brain-config`: The schema of `brain-config.yaml`: every key, generated from the validator, with a worked example
- `person-steps`: What only a person can do, in order, with the click or command for each
Refusals
A refusal is a status code with { error: { code, message } }. See Errors.