Barrel
FR GitHub

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

  1. Your orchestrator

    • Before the run branch/3, a constant-time fork
    • The agent writes to the branch only
  2. branch/3
  3. Barrel

    • main live data, untouched by the run
    • run_42 the branch: a normal database
  4. changes, then merge
  5. 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.

  1. 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"}}).
    REST response, from a recorded run
    HTTP/1.1 201 Created
    {"ok":true,"parent":"demo","fork_hlc":"AAABobh22gAAAAAA",
     "branch":"demo-exp"}
  2. Let the agent write to the branch

    The branch takes reads, writes, queries and search like any database. Point the agent at its name; main does not change.

    {ok, D} = barrel:get_doc(Run, <<"kb:201">>),
    {ok, _} = barrel:put_doc(Run,
        D#{<<"title">> => <<"Export invoices and credit notes">>}).
  3. Review what the run changed

    Read the branch’s changes since its fork instant. fork_hlc is a changes cursor.

    {ok, #{fork_hlc := Fork}} = barrel:info(Run),
    {ok, Changed, _Last} = barrel:changes(Run, Fork).
  4. Merge it, or throw it away

    A merge ships only the documents the branch changed. Edits made on main meanwhile on the same documents become ordinary conflicts. Merging again later is incremental.

    {ok, _Report} = barrel:merge(Run),
    ok = barrel:delete(Run).
    REST merge response, from a recorded run (trimmed)
    {"failed":[],"last_merged":"AAABobh224EAAAAA",
     "docs_read":1,"docs_written":1,"doc_write_failures":0,
     "att_sync":{"atts_written":0, …}, …}
  5. Recover a state from before the run

    Keep a changes cursor before each run. Branching at that 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_time also 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"}}).

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 main back 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_resolver applies. A capability token cannot reach a branch of its space; branch_create and merge need admin rights.

Go further

Up and down to moveEnter to open