Skip to content

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.


  • 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

POST /api/graph/branches
Content-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"
}
POST /api/graph/branches
Content-Type: application/json
{
"name": "sub-feature",
"project_id": "proj_xyz789",
"parent_branch_id": "branch_abc123"
}

Pass branch_id in the request body when creating objects or relationships on a branch:

POST /api/graph/objects
Content-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_abc123

Objects created on a branch are isolated — they are not visible in the main graph until you merge.

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:

Terminal window
memory blueprints dump ./migration
# review/edit ./migration/seed/objects/*.jsonl and seed/relationships/*.jsonl
memory graph objects create-batch --file ./migration --branch migration-review

The importer:

  • accepts a dump root, a seed/ directory, or a single .jsonl file;
  • upserts objects by key (so re-running is safe) and reads _untyped.jsonl back as type Untyped;
  • resolves relationship srcKey/dstKey after 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:

Terminal window
# objects (and optionally relationships) from a JSON/subgraph file
memory graph objects create-batch --file subgraph.json --branch migration-review
# relationships only, by existing entity IDs
memory graph relationships create-batch --file edges.json --branch migration-review

For relationships create-batch, both endpoint objects must already exist on the same branch — the server rejects a cross-branch edge.


GET /api/graph/branches

GET /api/graph/branches/{id}

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/merge
Content-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/merge
Content-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.


DELETE /api/graph/branches/{id}

PATCH /api/graph/branches/{id}
{ "name": "new-name" }

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)

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.