# Barrel > Barrel is an open source database for agents, written in Erlang/OTP. A record keeps a JSON document, its attachments and its vector under one id. It offers vector, BM25, hybrid and regex search, BQL queries, versions and branches, active-active replication, encryption at rest, and spaces with capability tokens for agents. It runs embedded in an Erlang application, as a server with REST and MCP (barrel_server), or in the browser (barrel-lite). Use the exact function names, routes and MCP tool names from these pages; generated reference pages are built from the source. ## Get started - [Overview for developers](https://barrel-db.eu/docs/start/what-is-barrel.md): Barrel is an open source database for agents and edge apps. It keeps a document, its files and its vector under one id, searches them, and replicates them between copies that all take writes. - [Install](https://barrel-db.eu/docs/start/install.md): Add Barrel to an Erlang project from Hex, run the server from its Docker image or a release, build it from the umbrella, or build barrel-lite for the browser. - [Quickstart: embedded](https://barrel-db.eu/docs/start/quickstart-embedded.md): Add Barrel to an Erlang application, store support articles, query them with BQL, then search them by meaning. - [Quickstart: server](https://barrel-db.eu/docs/start/quickstart-server.md): Build and start barrel_server, create a database, write and read documents, run a BQL query, and call a tool over MCP. - [Quickstart: browser](https://barrel-db.eu/docs/start/quickstart-browser.md): Build barrel-lite, open a local database in a web app, write and read documents, sync them with barrel_server, and resolve a conflict. - [Choose a deployment](https://barrel-db.eu/docs/start/choose-deployment.md): Decide between embedding Barrel in an Erlang release, running barrel_server, and keeping a copy in the browser with barrel-lite. ## Concepts - [The record](https://barrel-db.eu/docs/concepts/record.md): What Barrel stores under one id - a JSON document, its attachments and its vector - and which fields Barrel adds or reserves. - [Versions, conflicts, convergence](https://barrel-db.eu/docs/concepts/versions.md): How Barrel names every write with a version token, keeps concurrent edits as siblings, picks the same winner on every copy, and lets you resolve with _observed. - [Spaces and capabilities](https://barrel-db.eu/docs/concepts/spaces.md): How a space, a capability token, a session and a handoff fit together, the read, write and admin rights, and which checks happen in process and which only in barrel_server. - [Contexts and working sets](https://barrel-db.eu/docs/concepts/contexts.md): What a context, a context query and a working set are, what is implemented today, and what is planned. - [Glossary](https://barrel-db.eu/docs/concepts/glossary.md): The terms used across the Barrel docs, each in plain words, with a link to the page that covers it. ## Store and query - [Embed barrel in an Erlang app](https://barrel-db.eu/docs/guides/embedding.md): barrel is the embeddable edge database. It composes the document layer (barrel_docdb) and the vector layer (barrel_vectordb) behind one API, where a document, its attachments (blobs), and its vector share a single id. - [Record mode](https://barrel-db.eu/docs/guides/record-mode.md): Record mode makes a document and its vector one unit: you write documents, and barrel keeps the vector index in sync with them, driven by a per-database embedding policy. The vector store holds only vectors and indexes; search results read text and metadata from the current documents. - [Query with BQL](https://barrel-db.eu/docs/guides/query-bql.md): BQL is barrel's query language, a PartiQL (SQL for JSON) dialect: one SELECT statement queries documents, vector search, and keyword search, with live subscriptions. - [Attachments](https://barrel-db.eu/docs/store/attachments.md): Store files with a document, read them back whole or as a stream, keep them in S3, and know how they replicate. ## Search - [Vector, keyword and hybrid](https://barrel-db.eu/docs/search/hybrid.md): Search documents by meaning, by keyword with BM25, or both fused, from Erlang, BQL, REST and MCP, and know the limits of filters and scores. - [Substring and regex](https://barrel-db.eu/docs/search/substring-regex.md): Find exact strings and regular expressions in documents with barrel_ngram, a trigram index kept live from the changes feed, from Erlang or over MCP. - [Reranking](https://barrel-db.eu/docs/search/reranking.md): Reorder search results with a cross-encoder through barrel_rerank, a second stage you run after vector, keyword or hybrid search. - [Choose an embedding provider](https://barrel-db.eu/docs/search/embedding-providers.md): Pick the provider that turns your text into vectors, local or cloud, configure it, chain a fallback, run offline, or write your own. ## Replicate - [Synchronization](https://barrel-db.eu/docs/guides/synchronization.md): Barrel replicates documents between databases with a version-vector protocol: causal ordering from a hybrid logical clock (HLC), deterministic winners, idempotent delivery, and checkpoints for resumption. Replication runs in the same VM or over HTTP against a barrel_server. - [Conflicts](https://barrel-db.eu/docs/replicate/conflicts.md): Find documents in conflict after replication, read every version, resolve them from Erlang, REST or barrel-lite, or let the database resolve them for you. - [Upgrade from 2.0](https://barrel-db.eu/docs/replicate/upgrade-from-2-0.md): Move replicas from barrel_docdb 2.0.0 to 2.1.0, what the first run after the upgrade does on its own, and how to repair a damaged replica once with reconcile. - [Upgrade to docdb 3 and spaces 2](https://barrel-db.eu/docs/replicate/upgrade-to-3.md): Move a mesh to barrel_docdb 3.1 and barrel_spaces 2.0, in the order that keeps every node correct, what changes in your metrics and stored data, and why there is no way back. ## Agents - [Spaces, sessions, handoffs](https://barrel-db.eu/docs/guides/spaces.md): The agent layer: a space is a barrel database created through barrel_spaces, shared by holding a capability token for it. Sessions give agents a working context with a sliding TTL inside a space; a handoff transfers work to another agent as a token whose possession is the right to accept. - [MCP endpoint](https://barrel-db.eu/docs/guides/mcp.md): barrel_server mounts an MCP endpoint (Streamable HTTP) at /mcp: tools for databases, documents, BQL, search, the timeline, the agent layer, and contexts, plus resources with live-query subscriptions. - [Audit and provenance](https://barrel-db.eu/docs/guides/audit-provenance.md): Every applied write leaves an entry in the retained history log, and a write can carry provenance: who (actor), in what session, through which surface (source). Together they answer "what did the agent know when" at the database level. - [Index a codebase](https://barrel-db.eu/docs/guides/code-indexing.md): Build a search index an AI coding agent queries by meaning and by keyword. Barrel keeps one record per chunk, embeds it for you, and answers keyword, semantic and hybrid queries from one BQL call. ## Timeline - [Branch, merge, recover](https://barrel-db.eu/docs/guides/timeline.md): Barrel can branch a database: fork it instantly (at now, or rewound to a past instant), work on the branch in complete isolation, and merge the branch's edits back through the same version-vector machinery replication uses. ## Contexts - [Query several datasets](https://barrel-db.eu/docs/guides/contexts.md): A context is a named dataset (one Barrel database today) that you query together with other contexts, wherever they live: on this node or on other barrel_server nodes. You register one card per context on the node your agent talks to, then run one BQL statement over several contexts by name. ## Browser - [barrel-lite](https://barrel-db.eu/docs/guides/barrel-lite.md): barrel-lite is a TypeScript client that keeps an offline-first local document store in the browser and syncs it to a barrel_server over the /db/:db/_sync/* wire. It is a protocol client, not a WASM port. ## Security - [Encryption at rest](https://barrel-db.eu/docs/guides/encryption.md): Barrel can encrypt a whole logical database at rest under one per-database key: the document and attachment stores, the vector store, and the disk index files (BM25, DiskANN). - [Authentication](https://barrel-db.eu/docs/security/authentication.md): Lock barrel_server with bearer tokens, capability tokens, Ed25519 signed requests or mTLS, and give replication clients their credentials through the app env. ## Operate - [Run the server](https://barrel-db.eu/docs/guides/rest-server.md): barrel_server exposes the barrel database as a REST/JSON API using livery. By default it serves cleartext HTTP/1.1; HTTP/2 and HTTP/3 (over TLS) are opt-in via the listeners config (see synchronization). It holds no database logic. - [Run in Docker](https://barrel-db.eu/docs/guides/docker.md): The barrel-server image runs barrel_server, the barrel HTTP node, with the filesystem and S3 attachment backends. Use it when you want a barrel node on a server or in a cluster without installing Erlang. - [Releases](https://barrel-db.eu/docs/guides/releases.md): Barrel is released as a bundle: one dated snapshot of the whole repository, cut each time apps are bumped and released, with every app at the version it carries at that commit. - [Embed the server in an app](https://barrel-db.eu/docs/guides/embedding-barrel-server.md): barrel_server_api exposes barrel's REST/sync routes as a plain livery route list so another Erlang application can serve them from its **own** livery service, optionally under a sub-path, with its own authentication. - [Monitoring](https://barrel-db.eu/docs/operate/monitoring.md): What Barrel measures, how to read the metrics, how to send them to a collector, and how to watch replication tasks and health. - [Troubleshooting](https://barrel-db.eu/docs/operate/troubleshooting.md): Symptoms you may see with Barrel, what causes them and how to fix them, grouped by area. - [Backups and recovery](https://barrel-db.eu/docs/operate/backups.md): How to keep a copy of your Barrel data and get it back, what each method covers, and what is not supported yet. ## Reference - [Barrel API](https://barrel-db.eu/docs/reference/barrel-api.md): The barrel module, the entry point to the embedded database, grouped by area, with the other modules you call next to it. - [BQL](https://barrel-db.eu/docs/reference/bql.md): The BQL grammar Barrel implements, the search table functions, parameters, SUBSCRIBE, and the statements the compiler refuses. - [REST API](https://barrel-db.eu/docs/reference/rest-api.md): Every barrel_server HTTP route with its method, path, auth class, request, response and errors, checked against the route table and a running server. - [MCP tools](https://barrel-db.eu/docs/reference/mcp-tools.md): every tool barrel_server registers on /mcp, with its arguments, generated from tools/list - [Configuration](https://barrel-db.eu/docs/reference/configuration.md): The options you pass when you open a database, and the application environment keys of each Barrel app with their defaults. - [Error codes](https://barrel-db.eu/docs/reference/errors.md): The errors Barrel returns over REST, MCP and the Erlang API, what each one means and what to do about it. - [Libraries](https://barrel-db.eu/docs/reference/libraries.md): The independent libraries that make up Barrel, their versions and build profiles, and where to find each one's generated reference. ## Architecture - [Overview](https://barrel-db.eu/docs/architecture/overview.md): This note describes how the Barrel umbrella is split today and where it is headed. Read it when you need to know which application owns a responsibility, or before adding a new application to the umbrella. - [Feature status](https://barrel-db.eu/docs/features.md): What Barrel does today and what is planned, by capability. Read this to see which features are usable now, which are opt-in, and which are still ahead. Each row links to a guide where one exists. - [Replication proofs](https://barrel-db.eu/docs/architecture/replication-proofs.md): This page states the properties the document replication protocol relies on and argues why each holds. It covers the per-document state in barrel_live (apps/barrel_docdb/src/barrel_live.erl) and the rules around it. - [Contexts design](https://barrel-db.eu/docs/architecture/contexts.md): A context is a named, owned, bounded dataset (one Barrel database today) that an agent discovers, attaches, and queries together with other contexts, on this node or on other barrel_server nodes. This page describes the design as it ships in barrel 1.10.0 and barrel_server 1.10.0. - [Vision](https://barrel-db.eu/docs/architecture/vision.md): This note defines what the barrel application becomes: not a wrapper over barrel_docdb and barrel_vectordb, but the layer that makes them one database, positioned for agent workloads. Read it before working on any layer feature; the decision log at the end records what is settled and why. ## Contribute - [Build and test](https://barrel-db.eu/docs/contribute/build-and-test.md): Build the Barrel umbrella with rebar3 and its profiles, run the eunit and Common Test suites, the end-to-end scripts and the package check, as CI does. - [End-to-end tests](https://barrel-db.eu/docs/contribute/end-to-end-tests.md): Tests that run the real release across separate processes, not in one VM. - [Write a provider](https://barrel-db.eu/docs/contribute/write-a-provider.md): Implement the barrel_embed_provider behaviour to plug your own embedding model into Barrel, with a minimal provider module you can compile and run. - [Distribute the apps](https://barrel-db.eu/docs/guides/distributing-apps.md): The umbrella is the source of truth: you develop every app in one tree so cross-app changes stay atomic. This guide is for when you need to hand an individual app to someone outside the umbrella. There are three ways, and you can use all of them at once. ## Libraries - barrel 1.14.0: Records: document, files and vector under one id. https://barrel-db.eu/product/barrel - barrel_docdb 3.1.0: Documents, versions, queries, replication. https://barrel-db.eu/product/docdb - barrel_vectordb 2.5.4: Vector index, BM25, hybrid search. https://barrel-db.eu/product/vectordb - barrel_ngram 0.11.5: Substring and regex search. https://barrel-db.eu/product/ngram - barrel_embed 2.6.1: Embedding providers, local or cloud. https://barrel-db.eu/product/embed - barrel_rerank 1.0.3: Rerank search results. https://barrel-db.eu/product/rerank - barrel_spaces 2.0.0: Spaces, tokens, sessions, handoffs. https://barrel-db.eu/product/spaces - barrel_server 1.15.1: REST and MCP over HTTP. https://barrel-db.eu/product/server - barrel-lite 0.1.0: A copy in the browser, synced. https://barrel-db.eu/product/lite - barrel_crypto 1.0.0: Encryption keys and ciphers. https://barrel-db.eu/product/crypto - barrel_att_s3 0.2.2: Attachments in S3-compatible storage. https://barrel-db.eu/product/att-s3 - barrel_faiss 1.0.1: FAISS index backend. https://barrel-db.eu/product/faiss ## Optional - [Everything in one file](https://barrel-db.eu/llms-full.txt) - [MCP tools as JSON](https://barrel-db.eu/docs/reference/mcp-tools.json)