Branches
Isolated, copy-on-write forks of the graph — and why every agent session gets one.
A branch is an isolated fork of the cognition graph with copy-on-write
semantics. Like git for knowledge: you branch off a parent (usually main),
accumulate claims in isolation, and merge back under a policy you choose.
Each branch has a name, a slug, a status, and a merge policy.
Streaming session branches
The behaviour that makes branches matter for agents is automatic. With
streams.auto_session_branch enabled (the default), every MCP session gets
its own branch named stream/{session_id}, created with merge policy
AutoOnSessionEnd. While the session runs, anything the agent contributes lands
on that branch — isolated from main and from other sessions. When the session
ends, the branch auto-merges back.
Why this is a big deal
Concurrent agents never clobber each other's knowledge, a misbehaving session
can't corrupt main, and every session's contribution is an auditable,
revertible unit. You get this for free — it ships in the open-source engine; the
cloud does not re-implement it.
Working with branches
The engine exposes the full lifecycle over REST (and the Console's Branches tab visualises it as a live git-graph):
| Operation | Endpoint |
|---|---|
| List / create | GET / POST /api/v1/branches |
| Diff against parent | GET /api/v1/branches/{branch}/diff |
| Merge into main | POST /api/v1/branches/{branch}/merge |
| Merge into another branch | POST /api/v1/branches/{source}/merge-into/{target} |
| Rebase | POST /api/v1/branches/{branch}/rebase |
| Rollback a merge | POST /api/v1/branches/{branch}/rollback |
| Checkout as main | POST /api/v1/branches/{branch}/checkout |
| Delete | DELETE /api/v1/branches/{branch} |
| Lineage (DAG) | GET /api/v1/branches/lineage |
| Stats | GET /api/v1/branches/{branch}/stats |
Merges are guarded: by default a merge is blocked if it would introduce contradictions or drop health beyond a configured threshold (see health & verification).
Merge safety
Because merges run through the same admission checks as compilation, merging a
branch can't smuggle ungrounded or contradictory claims into main. A merge
that would degrade the graph is rejected, not silently applied — and you can
roll back a merge that turned out wrong.