Barrel
FR GitHub

Private knowledge search

Search your own documents by meaning and by keyword on machines you run, then give the best passages to the model you choose. Barrel stores, embeds and searches; your application makes the model call.

Built from barrel record mode, barrel_embed and, if you want it, barrel_rerank. One Erlang node, no separate vector database.

The problem

Retrieval usually means a document store, a vector database and an embedding service kept in step by your code, with your documents sent to a third party to be embedded. Every update risks a vector that no longer matches its text.

How it fits together

  1. Your application

    • Ingest writes documents
    • Answer prompt and LLM call: your code
  2. put_docs, query
  3. Barrel, on your node

    • kb, record mode documents with their vectors
    • Hybrid search vector and BM25, fused
  4. embed on write and query
  5. Models on your machines

    • Embedder barrel_embed: Ollama or local
    • Reranker barrel_rerank, optional

The document and its vector live under one id, so an update or delete changes both. Embedding and reranking run on models you host. The only call that leaves Barrel for an LLM is the one your application makes in step 6.

Build it

Six steps in an Erlang application. Steps 1 and 5 need setup outside Barrel.

  1. Run an embedding model locally

    Optional, needs setup

    Ollama keeps the model on your machine. The local provider (sentence-transformers in a managed Python virtualenv) works too; it installs packages and downloads the model on first use.

    Shell
    ollama pull nomic-embed-text
    ollama serve
  2. Open a record-mode database

    The policy names the fields to embed and the fields to return as metadata. mode => sync embeds before the write returns. Set db_path so the vector store does not land in the current directory.

    Erlang
    {ok, _} = application:ensure_all_started(barrel),
    {ok, Db} = barrel:open(kb, #{
        embedding => #{
            fields => [<<"title">>, <<"body">>],
            mode => sync,
            dimensions => 768,
            embedder => {ollama,
                #{model => <<"nomic-embed-text">>}},
            metadata_fields => [<<"product">>, <<"status">>]},
        vectordb => #{db_path => "data/kb_vec"}}).
  3. Write your documents

    Write plain documents. Updates re-embed; deletes remove the vector.

    Erlang
    barrel:put_docs(Db, [
      #{<<"id">> => <<"kb:101">>,
        <<"title">> => <<"Reset a forgotten password">>,
        <<"body">> => <<"Open the login page and choose "
                        "forgot password to receive a link">>,
        <<"product">> => <<"portal">>,
        <<"status">> => <<"published">>},
      #{<<"id">> => <<"kb:201">>,
        <<"title">> => <<"Export invoices">>,
        <<"body">> => <<"Billing admins can export invoices "
                        "as CSV from the reports tab">>,
        <<"product">> => <<"billing">>,
        <<"status">> => <<"published">>}]).
  4. Search by meaning and keyword together

    hybrid_top_k runs vector and BM25 search and fuses the two rankings. A WHERE on metadata filters in the same query.

    Erlang
    {ok, Rows, _} = barrel:query(Db,
        <<"SELECT h.id, h._score, title "
          "FROM hybrid_top_k('login reset', k => 3) AS h "
          "WHERE h.status = 'published'">>).
    From a recorded run that used an offline test embedder in place of Ollama (trimmed)
    {ok,[#{<<"_score">> => 0.01639344262295082,
            <<"id">> => <<"kb:101">>,
            <<"title">> => <<"Reset a forgotten password">>},
          #{<<"_score">> => 0.008408206049715483,
            <<"id">> => <<"kb:201">>,
            <<"title">> => <<"Export invoices">>}], ...}
  5. Rerank the top hits

    Optional, needs setup

    A cross-encoder reads the query and each passage together and orders them again. It returns {Index, Score} pairs, best first, where the index points into the list you passed. Set venv_path after loading the app and before starting it.

    Erlang
    ok = application:load(barrel_rerank),
    ok = application:set_env(barrel_rerank, venv_path,
                             "/opt/barrel/venv"),
    {ok, _} = application:ensure_all_started(barrel_rerank),
    {ok, R} = barrel_rerank:start_link(#{}),
    {ok, Hits} = barrel:search_hybrid(Db, Question, #{k => 20}),
    Texts = [maps:get(text, H) || H <- Hits],
    {ok, Ranked} = barrel_rerank:rerank(R, Question, Texts,
                                        #{top_k => 5}).
    Result shape, from a recorded run on three passages
    {ok,[{0,9.581769943237305},
         {2,-5.255744457244873},
         {1,-9.625640869140625}]}
  6. Hand the passages to your model

    This step is your application, not Barrel. Barrel never calls an LLM. If the model you call is a cloud API, this is where your data leaves your network.

    Erlang, your code
    Context = [lists:nth(I + 1, Texts) || {I, _} <- Ranked],
    Prompt = my_app:build_prompt(Question, Context),
    %% your LLM client, local or remote
    {ok, Answer} = my_llm:complete(Prompt).

What Barrel does

  • Stores the documents and keeps one vector per document in step with it
  • Calls the embedding provider you configure, on write and for each query
  • Answers vector, keyword (BM25) and hybrid queries, with metadata filters
  • Runs the reranker model process when you use barrel_rerank

What your application does

  • Chooses and runs the embedding model
  • Splits large documents into passages before writing them
  • Builds the prompt and calls the LLM
  • Decides which passages a user may see before they reach the prompt

Limits

  • Hybrid scores come from rank fusion (about 0.016 for a first place); compare them within one query only.
  • Reranker scores are raw cross-encoder logits, not values between 0 and 1.
  • Changing the policy applies to new writes only; existing documents are not re-embedded.
  • Vector indexes do not replicate; each node rebuilds its own from the documents.
  • Pass dimensions to match your model; the provider’s own size is not read back.
  • Contexts can query several knowledge bases at once, but they do not merge BM25 or hybrid scores across them.

Go further

Up and down to moveEnter to open