A branch is an isolated namespace for data. Every value in StrataDB lives inside a branch, and every capability — KV, JSON, event log, vectors, graphs — is branch-aware. Branches are how you keep one agent session, experiment, or tenant from seeing another’s data, without copying the whole database.

A database always has a default branch. You never create it; it is there the moment the database exists.

Forking a branch

branch fork creates a new branch from an existing one. The fork starts as a copy-on-write view of its parent — you see the parent’s data, but your writes go only to your branch.

strata ./db kv put city london
strata ./db branch fork default experiment
strata ./db kv put city tokyo --branch experiment

Reading each branch shows the isolation:

$ strata ./db kv get city --branch experiment
tokyo
$ strata ./db kv get city
london

The write on experiment never touched default. Forking is cheap because nothing is copied up front; the branch records its parent and the commit version it forked from:

$ strata ./db branch get experiment
{
  "branch_id": "1a29fdd4-745b-5b66-ad18-75b3cf51cef6",
  "created_at": 3,
  "deleted_at": null,
  "generation": 1,
  "name": "experiment",
  "parent": {
    "branch_id": "00000000-0000-0000-0000-000000000000",
    "fork_timestamp": null,
    "fork_version": 3,
    "generation": 1,
    "name": "default"
  },
  "state_revision": 0,
  "status": "active"
}

The parent block names the branch you forked from and the fork_version you forked at; default always has the all-zero branch_id.

Empty branches

branch create makes a fresh root branch with no parent and no data — useful when you want a clean namespace rather than a fork of existing state.

$ strata ./db branch create fresh
$ strata ./db kv get city --branch fresh
(nil)

Listing and inspecting

strata ./db branch list            # every branch, one per line
strata ./db branch get experiment  # one branch's metadata
strata ./db branch delete fresh    # remove a branch and its data

Branch generations are monotonic per name: delete a branch and create it again, and the new one has a higher generation, so stale references never silently resolve to fresh data.

Forking a point in time

A fork does not have to start from the tip. Pass --version or --timestamp to fork from a retained point in the source branch’s history:

strata ./db branch fork default older --version 3

The new branch sees the source exactly as it stood at that version, while the source keeps moving forward:

$ strata ./db kv get x --branch older
v1
$ strata ./db kv get x
v2

Safety rules

• The default branch cannot be deleted. Attempting it fails with invalid_argument.engine.branch_delete.
• Cross-branch references are rejected — you cannot point an operation at data in a branch other than the one it targets.
• There is no merge command in this release. Branches diverge freely; to bring work from one branch onto another, re-apply (replay) the writes you want on the target. This release ships forking, isolated writes, and deletion, and leaves merge to a future surface.

Choosing a branch per command

One-shot commands take --branch <name>; without it they target default. This is the clearest way to script against a specific branch, because each process is independent:

strata ./db kv put status ready --branch session-42
strata ./db kv get status --branch session-42

In the interactive REPL (strata ./db with no command), the branch is sticky: use <branch> — or passing --branch on any line — switches the current branch for the lines that follow, and the prompt reflects it.

strata:default/default> use experiment
strata:experiment/default>

When to use branches

Scenario	Pattern
Each agent session gets its own state	One branch per session id
A/B testing two strategies	One branch per variant, compare, keep the winner
Safe experiments	Fork, try changes, delete the branch if it goes wrong
Multi-tenant isolation	One branch per tenant
Reproducible snapshots	Fork at a known point and read it later

Next

• Commits — how writes on a branch become versioned and durable
• Branch Management Guide — the full branch API
• A/B Testing with Branches and Multi-Agent Coordination — worked patterns