Brain — git-versioned agent memory

The brain is the framework's own version control for memory, kept separate from your code's git history: a private git repo where sessions are branches, wrap-up is a merge, and main is the consolidated truth every agent boots from.

For the two-minute intro see Concepts → Memory tiers. This page is the deeper reference: the data model, the CLI, and how a returning agent boots cheaply.

Mental model

A real git repo, separate from your project's git. myai brain init

creates it (default ~/.myai/brain, overridable via MYAI_BRAIN_DIR).

Atoms — small, immutable, content-addressed commits. An agent appends a

session summary, a decision, or an idea; because atoms are append-only and named by content hash, merges across concurrent agents/machines are conflict-free by construction.

Namespaces — repos/<repo-name>/… for per-project atoms (sessions,

handoffs), memory/ for cross-repo facts.

Branches — session/<slug> while an agent works, idea/<slug> for

longer-lived parallel threads. main only receives merges.

The distiller — after every merge into main, three compiled views

regenerate automatically, zero interactive tokens:

brief.md (~150 tokens) — the cheapest possible boot
working.md (~2k tokens) — current working context
rollup.md — longer-horizon summary

Reading vs. writing

Reading the brain needs no server — it's git pull + read brief.md/ working.md on main. Writing (append an atom, merge, distill) goes through the gateway's brain_* MCP tools so concurrent agents don't race the same git repo directly.

CLI

myai brain init                 # create the brain repo
myai brain status               # branch, atom counts, open session/idea branches, stashes
myai brain write <kind> <note>  # append an atom on the current branch
myai brain session              # start/resume a session branch
myai brain idea <slug>          # start/resume an idea branch
myai brain log [n]              # commit history, scopable by ref/path

The matching MCP tools (what agents actually call) — full parameter list in the MCP tool reference:

Tool	Purpose
`brain_status`	Location, branch, namespaces, atom counts, open branches, stashes
`brain_commit`	Append one atom on the current branch (idempotent — identical re-writes no-op)
`brain_stash` / `brain_pop`	Freeze working context to `main` and resume it from any later session
`brain_branch`	Create/resume an `idea/<slug>` branch
`brain_checkout`	Switch to `main`, `session/<…>`, or `idea/<…>`
`brain_merge`	Merge the current branch into `main` (what `wrap up` calls); auto-runs the distiller
`brain_log` / `brain_diff`	History and pending-changes inspection
`brain_delta`	Diff-only catch-up since a given SHA — what a returning agent boots with
`brain_revert`	Undo a commit with an inverse commit; history is never rewritten

The boot-cheap loop

A session starts. If the agent has a last-seen brain main SHA (recorded

as Brain: <sha> in the previous handoff), it calls brain_delta(since=sha) — a ~300–800-token diff of what changed, instead of re-reading state files. No SHA yet → it gets the ~150-token brief.md.

The agent works, appending atoms as it goes (brain_commit) or freezing

context with brain_stash if it needs to hand off mid-task.

At session close, brain_merge folds the session branch into main and

the distiller recompiles the three views. The new main SHA becomes the next session's anchor.

Health is tracked as a composite 0–100 score (freshness, coverage gaps, contradictions, recall hit-rate) — myai brain status / brain health surfaces it with a trend line.

Try it hands-on

Try the Brain in ~5 minutes walks the full loop by hand against a throwaway brain — init → work → stash → pop from a second "agent" → merge → diff — no gateway, no Docker, no API key.

Syncing across machines

The brain is just git — point it at a remote and it syncs like any repo:

myai brain init --remote git@yourhost:you/brain.git

Multiple machines pushing sessions concurrently is the normal case, not a special one: atoms are content-addressed, so the same session summary committed twice from two machines collapses to one atom instead of a conflict.