A branch per agent run
Fork the database before an agent run, let the agent write to the copy, review what changed, then merge it or throw it away. Fork at a past instant to get back what a run broke.
Built from the barrel timeline: barrel:branch/3, merge/1 and delete/1, the same operations over REST and as the MCP tools branch_create and merge.
The problem
Letting an agent edit live data is risky, and copying a database to give it a sandbox is slow and leaves you to work out the differences by hand. When a run goes wrong, you want the data as it was before it started.
How it fits together
-
Your orchestrator
- Before the run branch/3, a constant-time fork
- The agent writes to the branch only
- branch/3
-
Barrel
- main live data, untouched by the run
- run_42 the branch: a normal database
- changes, then merge
-
Review
- Changes since the fork what the run did
- merge/1 or delete/1 keep it or throw it away
The branch shares files with main copy-on-write until either side compacts. Its writes carry their own source id, so a merge can tell what the branch did from what it inherited.
Build it
Five steps. The REST and MCP examples use a database named demo and a branch demo-exp, as in the recorded run.
-
Fork before the run
A branch is a hard-link checkpoint of the stores, so forking costs the same whatever the size. A record-mode branch gets its own vector store, rebuilt from the embeddings already stored in the documents.
{ok, Run} = barrel:branch(Db, run_42, #{vectordb => #{db_path => "data/run_42_vec"}}).curl -X POST localhost:8080/db/demo/_timeline/branch \ -H 'content-type: application/json' \ -d '{"name":"demo-exp"}'{"jsonrpc":"2.0","id":20,"method":"tools/call", "params":{"name":"branch_create", "arguments":{"db":"demo","name":"demo-exp"}}}HTTP/1.1 201 Created {"ok":true,"parent":"demo","fork_hlc":"AAABobh22gAAAAAA", "branch":"demo-exp"} -
Let the agent write to the branch
The branch takes reads, writes, queries and search like any database. Point the agent at its name;
maindoes not change.{ok, D} = barrel:get_doc(Run, <<"kb:201">>), {ok, _} = barrel:put_doc(Run, D#{<<"title">> => <<"Export invoices and credit notes">>}).curl -X PUT localhost:8080/db/demo-exp/doc/e \ -H 'content-type: application/json' \ -d '{"kind":"note","title":"on branch"}' -
Review what the run changed
Read the branch’s changes since its fork instant.
fork_hlcis a changes cursor.{ok, #{fork_hlc := Fork}} = barrel:info(Run), {ok, Changed, _Last} = barrel:changes(Run, Fork).FORK=AAABobh22gAAAAAA # fork_hlc from step 1 curl "localhost:8080/db/demo-exp/changes?since=$FORK" -
Merge it, or throw it away
A merge ships only the documents the branch changed. Edits made on
mainmeanwhile on the same documents become ordinary conflicts. Merging again later is incremental.{ok, _Report} = barrel:merge(Run), ok = barrel:delete(Run).curl -X POST localhost:8080/db/demo-exp/_timeline/merge curl -X DELETE 'localhost:8080/db/demo-exp?purge=true'{"jsonrpc":"2.0","id":21,"method":"tools/call", "params":{"name":"merge", "arguments":{"db":"demo-exp"}}}{"failed":[],"last_merged":"AAABobh224EAAAAA", "docs_read":1,"docs_written":1,"doc_write_failures":0, "att_sync":{"atts_written":0, …}, …} -
Recover a state from before the run
Keep a changes cursor before each run. Branching
atthat cursor gives you every document as it was then, next to today’s data, as long as the instant is inside the retention window (30 days by default). Over REST,at_timealso takes an RFC 3339 time.{ok, _, Before} = barrel:changes(Db, first), %% ... the run happens ... {ok, Then} = barrel:branch(Db, before_run_42, #{at => Before, vectordb => #{db_path => "data/before_42_vec"}}).curl -X POST localhost:8080/db/demo/_timeline/branch \ -H 'content-type: application/json' \ -d '{"name":"before-run", "at_time":"2026-11-07T09:00:00Z"}'{"jsonrpc":"2.0","id":22,"method":"tools/call", "params":{"name":"branch_create", "arguments":{"db":"demo","name":"before-run", "at":"AAABobh22gAAAAAA"}}}
What Barrel does
- Forks in constant time and isolates the branch completely
- Merges only what the branch changed, through the replication machinery
- Keeps concurrent edits on both sides as conflicts
- Restores a past instant within the retention window
- Rebuilds a record-mode branch’s vectors from the stored embeddings
What your application does
- Names a branch per run and points the agent at it
- Decides what review means: a person, a test suite or another agent
- Resolves conflicts left by a merge
- Deletes branches it no longer needs
Limits
- Lineage is linear: a branch of a branch is refused with
cannot_branch_a_branch. - A past instant below the history floor fails with
pitr_window_exceeded. - A point-in-time branch is not merged back as a revert; rolling
mainback to an instant is not available yet. - Plain (not record-mode) branches start with an empty vector store.
- Attachments on a point-in-time branch are as of the fork, not as of the chosen instant.
- There is no per-merge conflict policy; the parent’s
conflict_resolverapplies. A capability token cannot reach a branch of its space;branch_createandmergeneed admin rights.