# a guide for backend authors
wire any backend
as a brain.
The brain.aide file is a plugin interface. It tells AIDE how to launch your storage backend over MCP and how to talk to it once it's live. Bundled today: an Obsidian default. This page walks you through wiring that default, then shows you how to author your own — a Notion brain, a flat-filesystem brain, anything that can speak MCP.
[ ✓ ]5-step walkthrough[ ✓ ]3 worked examples[ ✓ ]live skeleton generator
§01install + scaffold the default
# the cli writes .aide/config/brain.aide pre-filled with the obsidian template.
Run this in any project root. It creates .aide/ with the methodology docs, scaffolds .aide/config/brain.aide using the bundled Obsidian template, and stops. The file lands with YAML null at the unwired arg slot — that's the signal that you still need to point it at a vault.
# alternative: --brain <integration> selects a different
# bundled template at install time.
# bundled template at install time.
.aide/config/brain.aide (just-scaffolded)
---
name: obsidian
mcpServerConfig:
command: npx
args:
- "@bitbonsai/mcpvault"
- # ← YAML null. unwired.
---
<!-- aide-orientation-start -->
Your brain is an Obsidian-backed knowledge store.
Use mcp__brain__read_note to open files...
<!-- aide-orientation-end -->
<!-- aide-config-start -->
You are completing the wiring of an Obsidian brain.
The required value is the absolute path to the
user's Obsidian vault...
<!-- aide-config-end -->
(...four seed sections...)§02wire it: /aide:brain config
# the config flow has two paths. the one that runs depends on what's in args.
Run /aide:brain config from inside Claude Code. The command reads the aide-config body section, which is integration-specific prose that knows how to handle the unwired slots for this backend. Click the buttons below to see what fires when:
WIRING flow · runs
1read brain.aide → quote last args entry
2YAML null detected — ask user for value
3edit brain.aide → land resolved value
4run npx @aidemd-mcp/server@latest sync
STOPemit "restart Claude Code" message and end
SEEDING flow · skipped
1read brain.aide → string detected, brain wired
2verify mcp__brain__* tools loaded in session
3for each: presence-check via list tool
4if missing → write_note from seed-section bytes
5emit completion summary; brain ready
WHY THE STOP
The brain's MCP server is registered at session start. The just-wired brain isn't loaded in the running session — sync wrote the entry but Claude Code didn't see it boot. So the wiring flow stops, you restart, and the second run of /aide:brain config takes the seeding path.
§03seed the entry-point artifacts
# the four seed sections in brain.aide become four files inside your brain.
On the second run, the integration's aide-config prose calls the brain's own MCP write tool to create:
◆
coding-playbook/coding-playbook.md<!-- aide-playbook-index-* -->
◆coding-playbook/coding-playbook.md←<!-- aide-playbook-index-* -->
◆
coding-playbook/study-playbook.md<!-- aide-study-playbook-* -->
◆coding-playbook/study-playbook.md←<!-- aide-study-playbook-* -->
◆
coding-playbook/update-playbook.md<!-- aide-update-playbook-* -->
◆coding-playbook/update-playbook.md←<!-- aide-update-playbook-* -->
◆
research/research.md<!-- aide-research-index-* -->
◆research/research.md←<!-- aide-research-index-* -->
Each is presence-checked first; existing files are left alone. After the first seed pass, the seed bytes in brain.aide go dormant — the brain owns those files now, and humans edit them in the brain UI.
seed write call (obsidian)
mcp__brain__write_note({
path: "coding-playbook/coding-playbook.md",
content: "<verbatim bytes from aide-playbook-index section>"
})
→ ✓ wrote
→ ✓ wrote coding-playbook/study-playbook.md
→ ✓ wrote coding-playbook/update-playbook.md
→ ✓ wrote research/research.md
✓ seeding complete. you can now run /aide.§04verify with the boot reporter
# at session start the orchestrator checks brain.aide vs .mcp.json. four states.
●ok
brain.aide + .mcp.json agree.
fix: pipeline proceeds.
●no-brain-aide
.aide/config/brain.aide is missing.
fix: npx @aidemd-mcp/server@latest init
●no-mcp-entry
.mcp.json has no brain entry, or args still have null.
fix: /aide:brain config → npx @aidemd-mcp/server@latest sync → restart
●mcp-drift
brain.aide and .mcp.json disagree.
fix: npx @aidemd-mcp/server@latest sync → restart
§05build your own backend
# everything above worked with bundled obsidian. now write one for your storage.
Authoring a custom brain is three artifacts: an MCP server that exposes the right tools, a brain.aide file with frontmatter that launches it, and the body sections (orientation + aide-config + the four seeds) that teach AIDE how to use it.
A · what your MCP server must expose
req
mcp__brain__read_<unit>
load a single artifact by relative identifier (path, page id, slug). Used everywhere — every reference walk starts here.
req
mcp__brain__list_<unit>
enumerate the contents of a folder/page. Used for presence-checks during seeding and for browsing.
req
mcp__brain__write_<unit>
create or overwrite an artifact body. The integration's aide-config prose calls this during seeding.
opt
mcp__brain__search
full-text or keyword query across the brain. Strongly recommended; the strategist falls back to walking link graphs without it.
opt
mcp__brain__delete_<unit>
remove an artifact. Optional — humans usually do this in the brain UI.
B · the body sections you author
<!-- aide-orientation-* -->
aide_brain at runtime
A runtime briefing the agent reads at the start of every brain-touching task. Name your MCP tools, list your entry-point artifacts, set scope rules.
<!-- aide-config-* -->
/aide:brain config
The wiring + seeding script. Documents which arg slots are unwired, how to resolve them, what to do after sync, and how to seed the four artifacts.
<!-- aide-playbook-index-* -->
seed → coding-playbook/coding-playbook.md
Root hub for the coding playbook. The user's conventions, top-level navigation table.
<!-- aide-study-playbook-* -->
seed → coding-playbook/study-playbook.md
Navigation methodology. How agents traverse the playbook hub → section → child note hierarchy.
<!-- aide-update-playbook-* -->
seed → coding-playbook/update-playbook.md
Maintenance methodology. How to add, edit, rename, or remove playbook entries safely.
<!-- aide-research-index-* -->
seed → research/research.md
Root hub for research notes. Domain index, navigation guidance.
C · worked examples
A flat folder of markdown files. The simplest brain you can build — useful as a learning reference and for solo developers who don't want a separate app.
MCP TOOLS EXPOSED
mcp__brain__read_file · mcp__brain__list_dir · mcp__brain__write_file · mcp__brain__grep
frontmatter args
args: - "@example/fs-brain-mcp" - # ← brain root path
aide-orientation (excerpt)
Your brain is a plain-markdown folder. Use mcp__brain__read_file to open files by path relative to the brain root. Entry-point artifacts: coding-playbook/coding-playbook.md coding-playbook/study-playbook.md coding-playbook/update-playbook.md research/research.md
aide-config (excerpt)
Required value: absolute path to the brain root folder. WIRING: ask user (offer to mkdir), edit args[1], sync, STOP. SEEDING: write each artifact via mcp__brain__write_file from the seed bytes.
D · live skeleton generator
# pick a preset, name it, optionally override orientation. copy the result into .aide/config/brain.aide.
SKELETON GENERATOR · live
backend
name (label)
.aide/config/brain.aide
---
name: obsidian
mcpServerConfig:
command: npx
args:
- "@bitbonsai/mcpvault"
- // ← absolute path to your vault
---
<!-- aide-orientation-start -->
Your brain is an Obsidian-backed knowledge store. Use `mcp__brain__read_note`
to open files by their brain-relative path. Use `mcp__brain__search_notes`
for keyword queries across every note in the store.
The store has four entry-point artifacts:
- `coding-playbook/coding-playbook.md`
- `coding-playbook/study-playbook.md`
- `coding-playbook/update-playbook.md`
- `research/research.md`
Start from the relevant entry-point for your task, follow references it lists
to deepen context, and stay in scope.
<!-- aide-orientation-end -->
<!-- aide-config-start -->
You are completing the wiring of an Obsidian brain. The required value is
the absolute path to the user's Obsidian vault, to be placed at the last
entry of `mcpServerConfig.args`.
Steps:
1. Read brain.aide and quote the last entry of args.
2. If YAML null → WIRING flow: ask for vault path, edit brain.aide, run sync, STOP.
3. If string path → SEEDING flow: write each entry-point artifact via
`mcp__brain__write_note` from the seed-section bytes.
<!-- aide-config-end -->
<!-- aide-playbook-index-start -->
# Coding Playbook
<!-- (your playbook root hub goes here) -->
<!-- aide-playbook-index-end -->
<!-- aide-study-playbook-start -->
# Study Playbook
<!-- (your navigation methodology goes here) -->
<!-- aide-study-playbook-end -->
<!-- aide-update-playbook-start -->
# Update Playbook
<!-- (your maintenance methodology goes here) -->
<!-- aide-update-playbook-end -->
<!-- aide-research-index-start -->
# Research
<!-- (your research index goes here) -->
<!-- aide-research-index-end -->