Brain

The Brain is what your project knows, kept beside its code: readable pages about the product and its architecture, a map of the code, and a record of who taught it what. Agents read it before they plan; you read it, approve its updates and, in an organisation, discuss it.

Open it from the rail, or press g b.

What you see

The page has three tabs, each with its own address:

• Knowledge base: the curated pages, read as documents (Docs) or drawn as a map (Map).
• Code graph: an index of the code and the parts of the system an update described.
• Updates: everything that waits on the brain, and its history. The tab shows a count when something needs your attention.

Above the tabs, the bar shows the branch the brain follows, a status dot and the kebab menu (Copy link copies a link to the view on screen). The footer says where this copy stands: Draft, the branch, and, in an organisation project, whether your draft is the published one.

Screenshot to come/assets/docs/brain-knowledge-base.webp

One draft per branch

The brain is not committed to Git. Each branch has its own local draft under .invariant/brain, and the Brain page always shows the draft of the branch your folder has checked out. Switch branch and you read that branch's draft. The first time a branch is seen, it starts from the draft you were on, else from the published brain, else empty.

The states you meet

You see	What it means
Create brain	The project has no brain yet.
Getting your team's brain…	The machine has no pages of its own, and your organisation has published a brain: it is being downloaded.
Brain setup is in progress / Your brain setup plan is ready.	The first update is open. Continue it, or review its plan.
Brain outdated · 3 updates waiting	Session notes wait to be turned into pages.
Update INV-190 is planned.	An update is open on this branch. The banner is orange while its plan waits on your approval.
No machine has published this brain yet.	On the web: nobody in the organisation has published it.

Create the brain

1. Open the Brain page of a project that has none.
2. Click Create brain (b).
3. Invariant enables the brain and opens its first update, a session that reads your executed sessions and source documents.
4. Review and approve the plan on the session page, as you would any plan. When the agent has applied the update, the pages appear.

If your organisation already published a brain, a machine with no pages of its own takes the published one instead. You can still choose Create brain if that download fails.

Read the knowledge base

The index on the left lists the Overview, then one group per domain (its own page first, then its features), then Decisions. A page that needs corrections carries a warning mark and a figure. A superseded decision reads quieter than an active one.

Each page shows a breadcrumb, its category, its title and summary, and a meta line such as Draft · main · 6 min read. Beside it, the side panel has two tabs:

• Contents (⇧ O): On this page, Connected knowledge, In the code (the parts of the code the page is about; click one to open it in the Code graph) and Evidence (View sources).
• Comments (x): the conversations on this page. See Comment on a page.

On a narrow window, the index and the side panel become drawers.

Find in the brain

Press ⌘ F or / on the Knowledge base to open the find bar over the page you are reading. It lists two groups:

• On this page: each match under its section. Enter and ⇧ Enter step through them.
• Other pages: matches elsewhere in the brain. Pick one to open that page at its section; its matches become the ones you step through.

The find bar keeps your text while you move from page to page.

The map view

Press m, or click Map in the Docs | Map switch, to see the same pages drawn as a map. The page you were reading comes with you.

• Categories are frames; pages are nodes; arrows are relations such as "explains", "governs" or "depends on". Legend explains the marks.
• Select a page to preview it, with its contents, related pages and code areas. Open it to see its neighbourhood.
• ⇧ F finds a page on the map; l switches between the map and a list; ⌫ goes up a level.
• +, − and 0 zoom in, zoom out and fit.

Screenshot to come/assets/docs/brain-knowledge-map.webp

Explore the code graph

The Code graph tab is the project's code map. It needs the project's files, so it is only on a machine that holds the project; on the web it says so.

1. Click Scan project (s) the first time. Scan options (o) narrows the scope. A scan runs in the background; Cancel stops it.
2. Pick a mode:
   • Architecture (a): the parts of the system and how they relate, as the last brain update described them. Before any update has, the mode says to update the brain.
   • Modules (m): the modules, folders and files of the scan.
   • Symbols (y): the declarations in the selection, as a list.
3. Switch between Structure (t, what lives inside) and Dependencies (d, what the selection imports and what imports it). [ and ] cycle Imports, Imported by and Both.
4. Select a node to inspect it. View source (v) shows the code; Read documentation (r) opens the brain page that covers it.

Imports on the graph are observed by the scan, never written by hand.

Update the brain

An update is a session that turns what waits into pages. What waits: notes from your sessions, your team's feedback, and what the code scan found. An agent plans the update, you approve the plan, and the agent applies it in one step. Your pages stay readable while it works.

1. Click Update brain (c). It is the main button while updates wait, and a quiet one otherwise. If nothing waits, the page says "Your brain is up to date."
2. Invariant opens the update and takes you to its session. Hand it to an agent from there.
3. Approve the plan when it is ready. An update asks only a few questions, for example when two notes contradict each other, and has no human plan.
4. When the agent has applied it, the pages change.

There is one open update per branch. While one is open, the button reads Continue update and takes you back to it. An update open on another branch neither shows nor blocks yours.

In an organisation project, an update also reads your team's comments. If they cannot be read, the page offers Open without team feedback.

How session notes feed the brain

Before an agent marks a plan session executed, it records what the session learned: a short note on the product, the technical side and what it learned. The note lands in the draft of the branch the session works on, and waits there. A session's page shows "What this session learned is waiting for the brain", with Update brain beside it.

You never write pages yourself. Agents teach the brain through notes and source documents; only an approved update changes the pages people read.

The Updates tab

Updates lists what waits on the brain, grouped by state:

Group	What it holds
New feedback	Comments on published pages no update has read yet.
Waiting for an update	Session notes, changed sources and code the pages do not cover yet.
Needs review	Outdated pages, page problems, and conversations an update could not settle.
Update in progress	The open update and the step it is on.
Ready to publish	Your draft differs from the published brain.
Published	Recent revisions, and the feedback each one answered.

Each row opens its page, conversation, source or session. History at the bottom folds the timeline of what happened to the brain.

Screenshot to come/assets/docs/brain-updates.webp

Publish to your organisation

In a project shared with an organisation, publishing is how your team gets the brain. Your draft stays local until you publish it.

1. Look at the footer. It says "Your draft is published r42", "Your draft differs from published r42", or "Not published yet".
2. Click Publish (p) in the footer. The draft becomes the organisation's next revision, and "Published. This is now the online brain." confirms it.
3. If the online brain is not in your draft's history (a teammate published from another branch), a dialog says who published it, when and from where. Merge or rebase that branch first, or choose Publish anyway to replace it.

Every member's machine then keeps a copy of the published revision; the footer says whether it is current, downloading or offline. A download never overwrites a draft that holds work. To take the published version anyway, open the footer's menu and choose Use published version. Your current draft is kept as a recovery copy.

On the web workspace, the Brain shows the published revision: the footer says "Published r42 · by Ana · 2h ago". Creating, updating and publishing happen on a machine.

Comment on a page

Members of an organisation discuss the published brain. The next update reads every comment and says what it did with it.

1. Open a page and press x, or select some text and click Comment. Each section heading also carries a marker to comment on that section. With the Comments panel open, c starts a comment on the whole page.
2. Optionally pick what kind of feedback it is: Missing context, Naming, Incorrect, Outdated or Question.
3. Send it. Teammates you mention get a notification.

When an update handles your comment, the conversation shows its outcome (incorporated, needs clarification or not applied) and later "published in r43". Only people resolve a conversation, with r. [ and ] switch between open and resolved conversations.

Comments are about the published revision, so a page must be published before anyone can discuss it. On a This machine project, the Comments entry points open the Pro page instead.

Shortcuts

Keys	Action
g b	Go to the Brain
c	Update brain, or continue the open update
p	Publish the brain
⌘ F or /	Find in the brain
m	Docs / Map
⇧ O	Contents
x	Comments, or comment on the selected text
g c	Go to the code map

Press ? on the page for the full list.

From the terminal

Your agents use the brain through the CLI: invariant brain context to read what it knows, invariant session contribute to leave a note, and invariant brain doc to write source documents. You can also open an update with invariant brain consolidate, publish with invariant brain publish, and fetch the published copy with invariant brain fetch. See Commands your agent runs and the CLI overview.