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.
Add it to your rebar.config
{deps, [{barrel, "~> 1.14"}]}. 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.
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). Read the use case Uses barrel_spaces, barrel_server
Write on every node
The problem
Sites, devices and regions each need their data locally, plus a central copy, over links that come and go.
With Barrel
Embed Barrel on each node and run a continuous replication task to the hub. Filters and channels decide what goes where.
Edge node continuous push Hub barrel_server pull to others Other nodes
{ok, TaskId} = barrel_rep_tasks:start_task(#{
source => <<"inventory">>,
target => <<"http://hub.example:8080/db/inventory">>,
mode => continuous,
direction => push,
filter => #{channel => <<"mobile">>}}). Read the use case Uses barrel_docdb, barrel_server
A database per customer
The problem
Customer data mixed in shared tables needs a filter on every query, and deleting a customer means hunting rows.
With Barrel
One space per customer, encrypted under its own key. Offboarding drops the space and revokes every token issued for it.
Your SaaS backend one per customer Space sp_acme own key Key provider
Enc = #{provider => tenant_keys},
{ok, #{id := Acme}} = barrel_spaces:create_space(#{
label => <<"acme">>,
encryption => Enc}),
%% offboarding: the data and every grant go
ok = barrel_spaces:drop_space(Acme, #{encryption => Enc}). Read the use case Uses barrel_spaces, barrel_crypto
Memory for agents
The problem
An agent forgets between turns unless you keep the conversation, its notes and what matters, and can find them again later.
With Barrel
Sessions hold messages and scratch data with a sliding expiry, pinned notes stay in front, and record mode makes stored documents searchable by meaning.
Support agent each turn Session in a space expires after ttl Searchable documents
{ok, Sid} = barrel_session:create(Space,
#{agent => <<"support">>, ttl => 3600}),
{ok, _} = barrel_session:add_message(Space, Sid,
#{role => <<"user">>, content => <<"I am locked out">>}),
{ok, _} = barrel_session:pin_context(Space, Sid,
#{content => <<"enterprise plan">>, priority => 0}),
{ok, Recent} = barrel_session:get_messages(Space, Sid,
#{limit => 20}). Read the use case Uses barrel_spaces, barrel
Private knowledge search
The problem
Retrieval usually means a document store, a vector database and an embedding service kept in step, with your data leaving your network.
With Barrel
Write documents. Barrel embeds them with a local model, searches by meaning and keyword together, and can rerank the top hits. You hand the hits to your model.
Documents embedded on write barrel, record mode hybrid search Reranker top hits Your LLM call
{ok, Db} = barrel:open(kb, #{embedding => #{
fields => [<<"title">>, <<"body">>],
embedder => {local, #{}}}}),
{ok, Hits} = barrel:search_hybrid(Db,
<<"customer cannot log in">>, #{k => 20}),
%% optional: barrel_rerank:rerank(Pid, Query, Texts)
%% then pass the best hits to your model Read the use case Uses barrel, barrel_embed, barrel_rerank
Code search for coding agents
The problem
A coding agent needs exact matches (an error code, a symbol, a pattern) as much as answers by meaning.
With Barrel
A trigram index answers substring and regex queries over the fields you pick; hybrid search answers by meaning. Both are MCP tools.
Coding agent ngram_search, search barrel_server MCP Code chunks trigram index
ok = barrel_ngram:open(<<"src_idx">>,
#{db => <<"code">>, fields => [<<"text">>]}),
barrel_ngram:search(<<"src_idx">>, <<"ERR_CONN_TIMEOUT">>),
barrel_ngram:regex(<<"src_idx">>, <<"\\w+_timeout">>). Read the use case Uses barrel_ngram, barrel_server
A branch per agent run
The problem
Letting an agent edit live data is risky, and copying a database to test on is slow.
With Barrel
Fork in constant time, let the agent work on the copy, inspect what changed, then merge it or throw it away. Fork at a past instant to recover.
main Agent run on a branch review merge or delete
{ok, Run} = barrel:branch(Db, run_42,
#{vectordb => #{db_path => "data/run_42_vec"}}),
%% the agent writes to Run, you review it
{ok, _Report} = barrel:merge(Run),
ok = barrel:delete(Run). Read the use case Uses barrel, barrel_docdb
Offline-first apps
The problem
A field app has to keep working without a connection and catch up later without losing edits.
With Barrel
barrel-lite keeps a copy in the browser, reads and writes locally, and syncs both ways when the connection returns.
Web app local reads and writes barrel-lite (OPFS) /db/:db/_sync barrel_server
const db = await Database.open("visits", {
remote: { url: "https://hub.example:8080",
db: "visits", token },
});
await db.put({ id: "v-311", site: "Lyon 2" });
const live = db.liveSync(); // sync while online Read the use case Uses barrel-lite, barrel_server
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.
- Your applicationagents, workers, OTP processes
calls the barrel API
- barrelrecords, search, branches
stores in
- 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.
Server
One node many clients share: agents over MCP, services over REST, other nodes over the sync wire.
- Agents and servicesMCP clients, curl, your backend
MCP at /mcp, REST at /db
- barrel_serverauth, capability tokens, spaces
calls
- 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.
Browser
A local copy in a web app. Reads and writes keep working offline.
- Your web appTypeScript
reads and writes locally
- barrel-litestores in the browser (OPFS)
syncs over /db/:db/_sync
- 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.
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'">>). curl -X PUT localhost:8080/db/kb
curl -X PUT localhost:8080/db/kb/doc/kb-142 \
-H 'content-type: application/json' \
-d '{"title":"Reset a locked account"}'
curl -X POST localhost:8080/db/kb/query \
-H 'content-type: text/plain' \
--data-binary "SELECT id, title FROM kb WHERE id = 'kb-142'" import { Database } from "barrel-lite";
const db = await Database.open("kb", {
remote: { url: "http://localhost:8080", db: "kb", token },
});
await db.put({ id: "kb-142", title: "Reset a locked account" });
await db.sync(); // push local writes, then pull 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