Brain
Brain
The project brain is one shared memory per project: what the project is for, what has been decided and why, and what is true about it (module brain, called "Project brain" in the module list). Every agent and connected app is handed it before it starts work on the project, so nobody, person or agent, has to argue a decision again or find a fact out twice.
In the sidebar under Projects → Brain. Needs: Projects and Tasks. Facts are kept by Knowledge (agent memory); without it, facts show as unavailable.
What the brain holds
| Part | What it is | How it changes |
|---|---|---|
| Core | A short markdown text: what the project is for, who it serves, the rules every agent keeps. Every version is kept. | A person in the web app changes it directly. An agent, a connected app, an API key or a chat can only propose a change, which a person accepts or rejects. |
| Decisions | Numbered D-001, D-002 and so on. Each has a title, what was decided, why, and what follows from it. | Recorded directly by anyone with write access. Never edited: a decision is replaced by a new one, or withdrawn with a reason. |
| Facts | One statement each, which can stop being true on a date. | Added directly by a person in the web app. From an agent, app, key or scheduled run, a fact is a proposal an editor accepts first. Never edited: replaced or retired. |
Every write is stamped with who made it and through what: the web app, one of the workspace's agents, a connected app, an API key or a chat.
What you see
Open Brain and choose a project from Choose a project…. With no project chosen, you see every project that has a brain: its core version, how many decisions are in force, how many proposals are Waiting for you, and its last change. Click one to open it.
A project's brain has six tabs.
Core
Proposed changes first, each with a diff and Accept, Accept with edits and Reject. Then the current core, with Edit (or Write the core if there is none yet), and every past version, each with Restore.
Decisions
The decisions in force, which agents work within. Show history adds replaced and withdrawn ones. A Who menu filters by where a decision came from: people in the web app, the workspace's agents, connected apps, API keys or chat.
Facts
Proposed facts first, with Accept and Reject. Then the current facts, each with Replace and Retire. Show history adds replaced and retired facts, and the same Who menu filters them.
What happened
What happened on the project, written as it happens: tasks done, costs logged, deploys, renewals, monitors going down and coming back, shop changes, each with who did it. Lines about a cost or a private domain you may not open are left out.
Weekly review
Once a week, what happened on each busy project is read, and the project's editors get one card with at most five things to decide: facts to add, facts that are out of date, or decisions that may need a new one. Each has Accept and Skip. Nothing in the brain changes until somebody presses Accept. Something skipped twice is not proposed again.
The tab shows when the review runs, and a table of past weeks: Week of, Came to (for example "Card sent", "Quiet week", "Nothing to ask", "Not reviewed: over the weekly limit", "Not reviewed: no AI connection may write") and The week. Review now runs the review for this project at once.
Brain changes
Every write to this brain, newest first, with who made it and through what.
What you can do
Write or change the core
- Open the project's Core tab.
- Press Write the core or Edit.
- Write the whole core in markdown and save. It becomes a new version.
The core has a length limit, 8,000 characters unless your administrator changes it. To go back, press Restore on an older version: it becomes the newest version.
Review what agents proposed
- Open the Core or Facts tab.
- For a core proposal, read the diff and press Accept, Accept with edits or Reject. A proposal written against an older core is marked, and needs the merged text before it can be accepted.
- For a proposed fact, press Accept or Reject. No agent is handed a fact until it is accepted.
Only a person in the web app can accept or reject. Agents and apps are refused.
Record a decision
- On Decisions, press Record a decision.
- Fill in Title, What was decided, and optionally Why it had to be decided and What follows from it.
- Save. It gets the next number.
To change a decision, press Supersede and record the new one in its place. To take it out of force without a replacement, press Withdraw and say why.
Add, replace or retire a fact
- On Facts, press Add a fact.
- Write one statement in Fact, and set Stops being true on if it expires.
- Save. Use Replace to record a new version of a fact, or Retire to take one out of use. Both keep the old fact in history.
Change when the weekly review runs
Administrators press When it runs on the Weekly review tab. You can switch the review off (then no card is sent, though Review now still works on one project), and set the day, the hour, the time zone and how many projects at most are reviewed each week, busiest first. It starts on, on Mondays at 09:00, for at most 40 projects. The time zone starts as the first administrator's notification time zone.
Undo a fact an agent just proposed
When an agent saves a fact from something you said, the proposal is made at once and you get an Undo. Undo withdraws the proposal, unless an editor has already accepted or rejected it.
Erase a secret that got in
Text that looks like a credential is refused when it is saved. If one still gets in, Erase blanks the text of that core version, decision or fact for good. Who erased it, when and why are kept. The button shows to administrators, and the server allows it to managers of the project.
Who can do what
| Permission | Label | Lets you |
|---|---|---|
brain:read | Read project brains | Open Brain and read the core, decisions, facts, what happened, past reviews and brain changes of projects you can see |
brain:write | Record decisions, facts and core changes | Change the core, record and withdraw decisions, add and retire facts, accept or reject proposals, and run Review now |
Your level on the project also counts: viewer to read its brain, editor to write to it, manager to erase. An archived project's brain cannot be written to. The brain's limits (core length, context size) and the weekly review's timing are changed by workspace administrators only. See People, roles and permissions.
What runs on its own
| Job | When | What it does |
|---|---|---|
brain-review-tick | Every 15 minutes (*/15 * * * *) | Checks whether it is the workspace's review day and hour. When it is, it runs the weekly review once that week: each busy project's editors get one card to accept or skip. Quiet projects are passed over. |
sweep | Every day at 03:30 UTC (30 3 * * *) | Removes brain rows left behind by projects that were deleted. A deleted project's brain normally goes at once; this catches anything that did not. |
The review needs an AI connection that may write; without one the week shows "Not reviewed: no AI connection may write".
For agents
The brain is written for agents. brain.context is the one call to make first: it returns the core, the decisions in force, the current facts, the open tasks most likely next (those in the running sprint first) and the project's recent log, sized to a budget, about 24,000 characters by default. The core and decisions are never cut; facts, tasks and the log are trimmed in that order, and anything left out is named with how to fetch it. A private task is named only to its creator or assignee. MCP clients are told to call it first, and the workspace's own agents get it automatically when a run starts on a project.
An agent's core changes and facts become proposals for a person. Decisions an agent records take effect directly. Erasing is classed as destructive: under the default approval policy a person is asked first. See Agents and approvals.
Read (read-only): brain.context, brain.core, brain.coreVersions, brain.proposals, brain.decisions, brain.decision, brain.facts, brain.factProposals, brain.activity, brain.reviews, brain.reviewSettings, brain.settings.
Core and decisions: brain.setCore, brain.restoreCore, brain.decideProposal, brain.decide, brain.withdraw.
Facts: brain.remember, brain.undo (withdraws a fact the agent just proposed), brain.acceptFact, brain.rejectFact, brain.retireFact.
Weekly review: brain.reviewNow, brain.setReviewSettings (administrators only).
Settings and clean-up: brain.setSettings, brain.erase (destructive).
brain.decideProposal, brain.acceptFact and brain.rejectFact refuse agents and apps: only a person in the web app may use them. Use brain.remember, not a personal memory, for anything lasting about a project.
Over MCP the same tools are named brain__context, brain__decide and so on. See API keys and MCP access.