Brain as Code

A repository’s own brain folder, synced with a space.

Context that describes a codebase belongs next to it. Brain as Code binds a repository to a space: the folder tree in the repo is the page tree in the app.

brain/knowledge/
├── index.md                 the space's own front page
├── engineering/
│   ├── index.md             the page for "engineering"
│   └── coding-style.md      a child of that page
└── decisions/
    └── 000042-a-claim.md    one hard-to-reverse call

<area>/index.md is the page for that area, and a leaf file beside it is that page’s child. Frontmatter carries title, icon and, for decisions, status.

Which direction writes go

A repo-backed page syncs one way, from the repo into the app. That is on purpose: a file rides a pull request and gets reviewed, while a write straight from an agent lands on the default branch and skips review.

In a repo that has a local brain/ folder, an agent should write a markdown file rather than calling upsert_page. The file is the reviewable artifact. The MCP write is for repos that have no brain folder of their own.

Setting it up

Register a GitHub App in server settings, install it on the account that owns the repositories, then connect a repo from the app. Connecting opens a setup pull request rather than committing to your default branch.

Gotchas

• The repo picker is keyed to one GitHub owner per organisation. Disconnect the old owner’s repositories before switching accounts.
• Transferring a connected repo to another GitHub owner deletes its installation. An installation is scoped to one account, so the repo leaving that account revokes it. The binding then goes stale silently: nothing errors, and the setup card stays green. Repointing is install on the new owner, then disconnect and re-add.
• contents: write does not cover .github/workflows/. That is a separate app permission, and granting it takes two steps: flip it on the app, then have each installing organisation accept the request. Nothing takes effect until that accept, and a run already in flight keeps its old token.