Use cases
Eight architectures Barrel is built for. Each page shows the problem, how the pieces fit together, the code to build it in steps, what Barrel does and what your application does, and the limits.
-
A database per agent
Isolated, shared by token
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
Uses barrel_spaces, barrel_server
-
Write on every node
Active-active sites and devices
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
Uses barrel_docdb, barrel_server
-
A database per customer
One key per tenant
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
Uses barrel_spaces, barrel_crypto
-
Memory for agents
Sessions, pins, recall
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
Uses barrel_spaces, barrel
-
Private knowledge search
RAG on your own machines
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
Uses barrel, barrel_embed, barrel_rerank
-
Code search for coding agents
Exact, regex and fuzzy
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
Uses barrel_ngram, barrel_server
-
A branch per agent run
Try, review, merge
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
Uses barrel, barrel_docdb
-
Offline-first apps
A copy in the browser
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
Uses barrel-lite, barrel_server