Barrel
FR GitHub

A database for agents.

Give every agent, customer and task its own database. Barrel keeps the document, the files attached to it and its vector under one id. You search it by meaning and by keyword, keep every version, branch it to try things, sync it to other nodes and browsers, and share it through capability tokens.

You need this when agents read and write the data your application runs on: support articles, tasks, notes, code. Usually each item is split across a document store, a file store and a vector index, and your code keeps the three in step. In Barrel they form one record, so the files and the vector stay tied to the document they belong to.

Every copy takes writes, on a server, at the edge or in a browser, and replication brings them back into agreement without losing an edit. Embedded in Erlang, served over REST and MCP. Open source, Apache 2.0.

Get started What is Barrel?

Add it to your rebar.config

{deps, [{barrel, "~> 1.14"}]}.
id: kb-142 document JSON, every version kept attachments files, stored in chunks vector embedded from its fields
One id ties them together. The vector follows every edit and delete of the document, and replication carries the document and its files to other copies.

Every copy takes writes

Active-active replication means every copy of a database accepts writes. There is no leader or primary that the others must reach first, so sites, edge nodes and browsers each keep working while the network between them is down.

When they reconnect, the copies exchange their changes and converge: they end up with the same documents and agree on the same version of each one. You need this when a site, a device or a browser must keep working through a lost connection, or when people in several places edit the same data.

  • Same answer everywhere. Every copy picks the same winner for every document.
  • No lost edits. Concurrent edits stay as conflicts until you resolve them.
  • Resumes after failure. Checkpoints per batch; tested under kills and power cuts.
  • Documents and files. Attachments travel with their documents.
How replication works, and how it is tested

Two sites edit the same task

Cut the link, edit on both sides, sync. Neither edit is lost: both copies pick the same winner and keep the other edit as a conflict until someone resolves it.

The call behind your last stepDemonstration in your browser, following barrel's rules

 

What you build with it

Eight architectures Barrel is made for. Each tab starts from a problem you may already have, such as keeping agents from reading each other's data or keeping an app working offline, then shows how Barrel handles it: the pieces involved and the code. Pick the one closest to what you are building; each has its own page and a runnable example.

A database per agent

The problem

Agents that share one database see and overwrite each other’s work, and you cannot cut one agent off without the others.

With Barrel

Each agent gets a space: its own database and a token that says what it may read or write. Revoke the token and the agent is out.

Planner grants a token Space sp_research token over MCP Research agent

{ok, #{id := Sp}} = barrel_spaces:create_space(
    #{label => <<"research">>, owner => <<"planner">>}),
{ok, Token, _} = barrel_caps:grant(Sp,
    #{rights => [read, write], subject => <<"researcher">>}),

%% the agent sends Token as a bearer token to /mcp
ok = barrel_caps:revoke(Token).

Three places to run it

This is where you start. Barrel is the same database in all three places: the same record, the same replication protocol, so copies in different places can sync with each other. Pick where the database lives from what your application is written in, whether its clients reach it over the network, and whether it must work offline. The agents that use it don't change, and you can add the other places later.

Embedded

Inside your Erlang/OTP release. No network hop, no separate service to run.

  1. Your applicationagents, workers, OTP processes

    calls the barrel API

  2. barrelrecords, search, branches

    stores in

  3. RocksDB on local diskdocuments, attachments, vectors

Fits an Erlang or Elixir application that owns its data. You add barrel as a dependency and call it as a library, with the full API.

Quickstart: embedded

Server

One node many clients share: agents over MCP, services over REST, other nodes over the sync wire.

  1. Agents and servicesMCP clients, curl, your backend

    MCP at /mcp, REST at /db

  2. barrel_serverauth, capability tokens, spaces

    calls

  3. barrelthe same embedded database

Fits clients in other languages or on other machines, and AI agents that connect through MCP, the protocol agent tools use to call outside services. Start here if you do not write Erlang.

Quickstart: server

Browser

A local copy in a web app. Reads and writes keep working offline.

  1. Your web appTypeScript

    reads and writes locally

  2. barrel-litestores in the browser (OPFS)

    syncs over /db/:db/_sync

  3. barrel_serverthe copy it syncs with

Fits a web app whose users must keep working without a connection. The browser copy syncs with a barrel_server, which holds the durable copy, so you run one too.

Quickstart: browser

Not sure which one fits? Choose a deployment compares the three in one table: what each gives you and what to know before you pick.

Try it in two minutes

Each tab writes the support article kb-142 and reads it back with a query in BQL, Barrel's SQL-like query language. The Erlang tab calls the library directly and opens the database without a vector store, so it needs no embedding model. The REST tab talks to a running barrel_server with curl. The TypeScript tab writes to the browser copy, then syncs it with the server. Pick the tab that matches where you run Barrel, then follow its quickstart to set it up.

{ok, _} = application:ensure_all_started(barrel),
{ok, Db} = barrel:open(<<"kb">>, #{vectordb => none}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"kb-142">>,
    <<"title">> => <<"Reset a locked account">>}),
{ok, Rows, _} = barrel:query(Db,
    <<"SELECT id, title FROM kb WHERE id = 'kb-142'">>).

What works today, and what doesn't yet

Check a feature's mark before you plan around it. Works today means it works in the current release and is covered by the test suites. Optional means it works once you install or configure something, such as a Python virtualenv or an API key. Planned means it is not built yet, so do not depend on it. Every page carries the same three marks, and anything without a mark works today.

Works today

  • Documents, attachments, every version kept
  • Vector, keyword (BM25) and hybrid search
  • Substring and regex search
  • BQL queries and live subscriptions
  • Active-active replication: nodes and browsers
  • Branches and point-in-time recovery
  • Encryption at rest
  • Spaces, sessions, capability tokens, handoffs
  • REST and MCP server

Optional, needs setup

  • Local embeddings (Python virtualenv)
  • Cloud embedding providers (API key)
  • Reranking (Python virtualenv)
  • FAISS index backend (system FAISS)
  • S3-compatible attachment storage

Planned

  • Live federated queries across contexts
  • Rank fusion and reranking across contexts
  • Context catalog enrollment

Status of every feature

Up and down to moveEnter to open