# Brain

a body of knowledge in its own git repo, owned by one account inside one tenant, readable and writable by whoever the owner grants. The only kind of second brain Tonoman supports.

**Has:** one tenant · one owner (an account) · a name · one repo · many grants (to an account or an agent; read or write) · an index state (last refreshed, from which revision, fresh | stale | failed). Every membership has one **personal** brain; anyone allowed may create more (a department's, a project's).

## Who can reach it

- A brain belongs to one tenant. Nothing in it is visible outside that tenant.
- Every membership has one personal brain. Its owner reads and writes it; nobody else reaches it until the owner grants it.
- Only the owner grants and revokes. A grant is read or write (write includes read), to an account, an agent, or everyone in the tenant — now and later. A grantee must be of the same tenant.
  - e.g. a grant to an account of another tenant → refused.
- An operator can make a brain from a repo that already exists — its address, branch and folder — owned by a member of the tenant; Tonoman does not create or seed it, and grants it to nobody but its owner until the owner does.
- A brain can be kept as it is: Tonoman writes only what is asked — no `BRAIN.md`, no line in `log.md`, no map under `.tonoman/` — and it is never refreshed: no page of it is read by the local model, no graph is published, and a refresh already queued for it is dropped. It is the exception to [BRAIN-LOG](https://tonoman.com/docs/brain#brain-log), [BRAIN-BACKGROUND-REFRESH](https://tonoman.com/docs/brain#brain-background-refresh) and seeding. A records repo (finances) stays exactly in its own layout.
- A question one page answers costs the index and that page, not the brain: on a brain of thousands of pages, a few tens of thousands of tokens and a handful of calls.
- A person may create more brains, owns what they create, and grants each one to any mix of accounts and agents.
  - e.g. Engineering granted to agents X, Y, Z → those three use it; a fourth agent cannot.
- Every read, search and write is checked against the registry at the moment it happens: a current membership, a brain that is active (or its owner's first use of one not created yet), and ownership or a grant. The git host is storage, and its credential never enters an agent's workspace.
- Every agent can use brains; nothing is switched on per agent. Being able to use brains grants access to none.
- In a conversation the agent reaches the brains the person speaking owns or is granted. Two people talking to one agent reach different brains.
- With nobody speaking (a scheduled run), the agent reaches the brains granted to the agent and those of the person the run is for.
- Brain content reaches only people allowed to read that brain — not through thread history, a shared channel reply, a cache or a later run.
- Before anything is posted, the worker knows who will see it: the speaker in their own DM; every member of a private channel or group DM, counted in full; the whole workspace for a public channel. Anyone Tonoman does not know counts as unable to read any brain. If the audience cannot be counted, it is treated as unable.
- A brain counts as used by a conversation once anything from it reached the agent — a listing, an index, a search hit, a page — or was written. It stays used for the rest of that person's history of the conversation, since the agent can repeat it without looking again.
- Outside the speaker's own DM, nothing of an answer — text, progress, tool details — is shown until the worker has decided where it goes. If the audience cannot read every brain used, the answer goes to the speaker as a DM that first says why, and the thread gets one line with no content in it. If the DM fails, nothing is posted in the thread but that it failed.
  - e.g. Ana asks in #eng about her private note → DM: "Answering here because part of this comes from your personal brain, which not everyone in #eng can read." Thread: "I've sent you that privately."
  - e.g. the answer used only Engineering, and every member of the private #eng can read it → posted in the thread as usual.
- A write confirmation or a skill announcement follows the same rule; a page's path alone can say too much. The thread gets "Done — details sent to you privately."
- Reach is decided when a turn starts and checked again before anything is pushed. A revoke stops new reads and writes; it cannot recall what was already said.
- When a membership ends, that person's brains are archived. Inviting them again restores the brains, and the grants to anyone still in the tenant.
  - e.g. a brain never created, owner leaves and returns → still *not created yet*.

## In a conversation

- A turn reaches brains only through `tonoman brain` (`cli.md`; an MCP tool until [CLI-ONE-COMMAND](https://tonoman.com/docs/cli#cli-one-command)), which offers the brains that turn can reach at their latest pushed state, read-only or writable as granted. The agent's own file tools cannot open brains ( for the rest).
- The agent reads a brain's `index.md`, follows its hubs, then searches. `BRAIN.md` tells it how that brain is organised.
- Everything a turn reads from brains — lists, indexes, search hits, pages — shares one budget per turn. Past it, the tool says what was left out, and so does the agent.
- Asked to remember something, with write access → the agent writes it, it is committed and pushed, and the reply names the brain and the path. It confirms only after the push succeeds.
  - e.g. the push fails → "I could not save that", never a false yes.
- A write caught by a restart between commit and push is pushed afterwards, or the person is told it was not saved.
- With no brain named, the agent picks the best-fitting writable brain and page — updating an existing page rather than making a duplicate — and says what it chose. If two fit equally, it asks.
- Asked to write where it may only read → it says so, names a brain it can write to if one fits, and otherwise offers the text.
- Every write adds a dated line to the brain's `log.md`: what, where, for whom.
- Two turns writing to one brain at once: both are kept. On the same page the later is retried on top of the earlier; if it still conflicts, that person is told and their text is kept for them.
- A page or a file in a brain can be changed in place, by whoever can write that brain: the agent gives the words to find and the words to put there. They must be found exactly once — not at all, or more than once, and nothing is written and the agent is told which — and everything else in the file stays byte for byte as it was; it is one commit. So a file too long to read whole, like a ledger, can still be corrected, and no skill needs a command of its own for changing what it filed.
  - e.g. one row of a 300-row ledger gains a note → that row changes, the other 299 do not.

## The repo

- On first use Tonoman creates the repo — `brain-<tenant>-<name>`, ending `-dev` in dev — seeded with `BRAIN.md`, `index.md` and `log.md`. Trying again reuses the same repo.
- A skill that files pages files into the personal brain of the person the run is for, unless its settings name another. The run must be able to write there, or it fails saying which brain and why.

## Staying organised

- After a push, the index, hubs and graph are refreshed in the background; no conversation waits for it. The Hub shows each brain as fresh, stale or failed, and failures are retried.
- The refresh's own files never trigger another refresh; only a change to a page does.
- The refresh finds pages that belong together even when nothing links them, and records the connection in the hubs and the graph. It never rewrites what a page says.
- Each refresh updates `index.md`, the hubs and the list of orphan pages, and logs what it did — so an agent follows the connections by reading files.
- The refresh runs on the local model. If it is unavailable the refresh waits; brain content is never sent to another provider instead.

## In the Hub

- Brains lists the brains a person can reach, with state and freshness. An owner creates brains and manages grants there. A brain they cannot reach is not listed.
- Each brain opens as an explorable graph: search a page, switch hierarchy and links, show orphans, click a page for its neighbours and open it.
- Each tenant's current second brain becomes a brain owned by a tenant owner, granted read to every member — those invited later too — and write to the agents filing into it today. Skills filing there keep filing there.
- A tenant's second brain is a list of git repos, each with a branch, a folder and a read-only switch; their credentials are never returned.
- In a conversation the agent can read and search the second brain and cannot write to it; only a skill files pages.
- Each tenant has one published graph; publishing needs the system token and replaces the last one; before the first, reading says there is none.
- Someone who reaches every brain it became, or an operator, opens Second brain and explores the tenant's graph: search, hierarchy and links, orphans and stubs, a page's neighbours, open the page. Nobody else can fetch it; revoking any of those brains revokes this view, since the graph is drawn from all of them.
- Reindexing reads the committed pages, changes none of them, and writes the graph, index and log under `.tonoman/`; only that folder is ever committed.