Branches
Branches let you work on isolated copies of the knowledge graph — making changes, reviewing them, and merging back — without affecting the main graph until you’re ready.
Think of it like git branches, but for your knowledge graph.
When to use branches
Section titled “When to use branches”- Reviewing AI-extracted content before it enters the main graph
- Exploratory work — adding objects and relationships you may want to roll back
- Parallel editing — multiple people working on separate sets of changes
- Staged imports — loading a new data source into a branch, validating, then merging
Creating a Branch
Section titled “Creating a Branch”POST /api/graph/branchesContent-Type: application/json
{ "name": "q4-planning-review", "project_id": "proj_xyz789"}Response:
{ "id": "branch_abc123", "name": "q4-planning-review", "project_id": "proj_xyz789", "parent_branch_id": null, "created_at": "2026-03-08T10:00:00Z"}Branch from an existing branch
Section titled “Branch from an existing branch”POST /api/graph/branchesContent-Type: application/json
{ "name": "sub-feature", "project_id": "proj_xyz789", "parent_branch_id": "branch_abc123"}Working on a Branch
Section titled “Working on a Branch”Pass branch_id in the request body when creating objects or relationships on a branch:
POST /api/graph/objectsContent-Type: application/json
{ "type": "Decision", "branch_id": "branch_abc123", "properties": { "title": "Adopt event sourcing" }}For list/get requests, pass branch_id as a query parameter:
GET /api/graph/objects?branch_id=branch_abc123Objects created on a branch are isolated — they are not visible in the main graph until you merge.
Bulk importing a dump into a branch
Section titled “Bulk importing a dump into a branch”memory blueprints dump <dir> exports the graph as JSONL seed files
(seed/objects/<Type>.jsonl and seed/relationships/<Type>.jsonl). To stage a
migration on a branch, edit the dump and import it in one call:
memory blueprints dump ./migration# review/edit ./migration/seed/objects/*.jsonl and seed/relationships/*.jsonlmemory graph objects create-batch --file ./migration --branch migration-reviewThe importer:
- accepts a dump root, a
seed/directory, or a single.jsonlfile; - upserts objects by
key(so re-running is safe) and reads_untyped.jsonlback as typeUntyped; - resolves relationship
srcKey/dstKeyafter the objects are written; - reports each unreadable row (bad JSON, missing type, unresolved key, server rejection) and continues, then exits non-zero if anything failed.
Everything lands on the named branch; the main graph is untouched until you merge.
Both batch commands take the same flag:
# objects (and optionally relationships) from a JSON/subgraph filememory graph objects create-batch --file subgraph.json --branch migration-review
# relationships only, by existing entity IDsmemory graph relationships create-batch --file edges.json --branch migration-reviewFor relationships create-batch, both endpoint objects must already exist on
the same branch — the server rejects a cross-branch edge.
Listing Branches
Section titled “Listing Branches”GET /api/graph/branchesGetting a Branch
Section titled “Getting a Branch”GET /api/graph/branches/{id}Merging a Branch
Section titled “Merging a Branch”When you are ready to promote changes from a source branch into a target branch, merge it.
Direction: source → target. The source branch is read; the target branch receives the changes.
By default the merge is a dry run — it shows what would change without mutating state. Pass "execute": true to apply.
POST /api/graph/branches/main/mergeContent-Type: application/json
{ "source_branch_id": "branch_abc123"}Use main as the path segment to merge into the main graph. Use a branch UUID to merge into another branch.
Dry-run response shows each object classified as:
| Classification | Meaning |
|---|---|
added |
Exists on source only — will be created on target |
fast_forward |
Changed on source only — target will be updated |
conflict |
Changed on both branches — blocks execute until resolved |
unchanged |
Identical on both branches — nothing to do |
To execute after reviewing:
POST /api/graph/branches/main/mergeContent-Type: application/json
{ "source_branch_id": "branch_abc123", "execute": true}The merge runs in a single database transaction — it is all-or-nothing. If any conflict exists, execute is rejected until conflicts are resolved manually.
Deleting a Branch
Section titled “Deleting a Branch”DELETE /api/graph/branches/{id}Renaming a Branch
Section titled “Renaming a Branch”PATCH /api/graph/branches/{id}{ "name": "new-name" }Branch hierarchy
Section titled “Branch hierarchy”Branches can optionally record a parent_branch_id — which branch they were forked from. This is lineage metadata only and does not affect merge behavior. The merge compares object content hashes directly between source and target regardless of parentage.
A null parent_branch_id means the branch was created off the main graph.
main graph (no branch ID)├── feature-a (parent_branch_id: null)│ └── feature-a-sub (parent_branch_id: feature-a)└── feature-b (parent_branch_id: null)Letting an agent read unmerged branches
Section titled “Letting an agent read unmerged branches”By default an agent searches the main graph only — pending work sitting on an unmerged branch is invisible to it. An agent definition can opt into reading branches that have not been merged yet, narrowed by why a branch exists and by its name:
PATCH /api/projects/{projectId}/agent-definitions/{id}Content-Type: application/json
{ "branchScope": { "unmerged": true, "origins": ["extraction"], "branches": ["extraction/*"], "maxBranches": 3 }}| Field | Meaning |
|---|---|
unmerged |
true enables branch reads. Absent or false means main only. |
origins |
Only branches created by these sources: extraction, agent, manual, system. Empty/omitted allows any. |
branches |
Name globs. * is the only wildcard and it matches across /, so extraction/* covers every extraction branch. |
maxBranches |
How many branches one search may read, newest first. Default 3, maximum 20. |
When both origins and branches are set, a branch must match both.
A search under a scope reads the main graph plus each matching branch and merges
the results. Every object that exists only on a branch comes back flagged with
branch_id, branch_name, origin and origin_label, so a model can say
“on the pending extraction branch for Invoice.pdf…” rather than presenting it as
settled fact. When the cap leaves branches unread, the response metadata carries a
branch_scope_note saying so.
The boundary also follows the agent’s calls: search-knowledge runs its internal
research agent under the same boundary (it cannot be steered into reading a branch
outside it), and a read tool that names a branch outside the boundary is refused.
Edge reads are bounded the same way: a scoped run sees relationships on the main
graph and on the branches in its scope, and an agent run that declares no scope
sees main edges only. Graph traversal is not widened by a scope yet — it walks the main graph — so
a scoped agent reaches branch content through search, a branch named on a read
tool, and search-knowledge.