Barrel
FR GitHub

Memory for agents

Keep what an agent needs between turns and between runs: the conversation, its working state, the notes that must stay in front, and facts it can find again by meaning.

Built from barrel_spaces sessions and a record-mode space. Sessions are also reachable over REST and MCP.

The problem

An agent forgets between turns unless something keeps the conversation, its notes and what matters. Keeping that in a cache loses it on restart; keeping it in a plain table leaves you to expire it, order it and search it yourself.

How it fits together

  1. Your agent

    • Each turn appends messages, updates state
    • Prompt builder pins, recent turns, recalled facts
  2. session calls, put_doc
  3. Space sp_support

    • Session ses_… messages, data, pins; sliding TTL
    • Fact documents record mode: embedded on write
  4. embed facts, sweep
  5. On the same node

    • Embedder a barrel_embed provider, Ollama here
    • TTL sweeper tombstones expired sessions

Short-term memory is the session: messages, data and pins, gone when the TTL runs out. Long-term memory is ordinary documents in the same space, embedded by the space’s policy and searched with search, search_hybrid or BQL.

Build it

Seven steps. Step 1 needs an embedding provider; this page uses Ollama with nomic-embed-text. Steps 2 to 7 work the same on a space without a policy, minus the search.

  1. Create a space with a memory policy

    Optional, needs setup

    The embedding policy turns the space into a record-mode database: documents with a fact field get a vector, kept in step with every update and delete. Session messages carry no fact field, so they are not embedded.

    Erlang
    {ok, _} = application:ensure_all_started(barrel_spaces),
    Embedder = {ollama, #{model => <<"nomic-embed-text">>}},
    {ok, #{id := SpaceId, db := Db} = Space} =
        barrel_spaces:create_space(#{
            label => <<"support memory">>,
            embedding => #{fields => [<<"fact">>],
                           mode => sync,
                           embedder => Embedder}}).
  2. Open a session for the conversation

    A session is a document with a sliding expiry: every change pushes it back by ttl seconds.

    {ok, Sid} = barrel_session:create(Space,
        #{agent => <<"support">>, ttl => 3600}).
  3. Append each turn

    Messages are separate documents whose ids sort by time, so reading the last twenty is a short range scan.

    {ok, _} = barrel_session:add_message(Space, Sid,
        #{role => <<"user">>,
          content => <<"I am locked out">>}).
  4. Keep working state and pinned context

    set_data holds structured state under a key. Pins are notes that stay in front of every prompt, ordered by priority.

    {ok, _} = barrel_session:set_data(Space, Sid,
        <<"ticket">>, <<"T-311">>),
    {ok, _PinId} = barrel_session:pin_context(Space, Sid,
        #{content => <<"enterprise plan">>, priority => 0}),
    {ok, Pinned} = barrel_session:list_pinned(Space, Sid).
  5. Read the recent turns back

    Newest first with order => desc; since and before take unix milliseconds.

    {ok, Recent} = barrel_session:get_messages(Space, Sid,
        #{limit => 20, order => desc}).
  6. Store facts and recall them by meaning

    When your agent decides something is worth keeping beyond the session, write it as a document. It is embedded on write and found later by meaning, keyword or both.

    Erlang
    {ok, _} = barrel:put_doc(Db, #{
        <<"id">> => <<"fact:acme-sso">>,
        <<"customer">> => <<"acme">>,
        <<"fact">> => <<"Acme signs in through Okta SSO">>}),
    {ok, Hits} = barrel:search_hybrid(Db,
        <<"how does acme log in">>, #{k => 5}).
  7. Let sessions expire, or keep one for good

    An expired session reads as not found at once and is swept later with its messages. ttl => infinity makes a durable session that never expires.

    Erlang
    {ok, Tmp} = barrel_session:create(Space, #{ttl => 1}),
    timer:sleep(1500),
    {error, not_found} = barrel_session:get(Space, Tmp),
    {ok, Rec} = barrel_session:create(Space,
        #{agent => <<"support">>, ttl => infinity}),
    {ok, 0} = barrel_session:touch(Space, Rec).
    From a recorded run
    ttl => 1 session read 1.5 s later: {error,not_found}
    touch on a ttl => infinity session: {ok,0}

What Barrel does

  • Stores messages as documents in time order, per session
  • Slides the session TTL on every change and sweeps expired sessions and their messages
  • Keeps structured data and pins per session
  • Embeds fact documents on write and searches them by meaning and keyword
  • Keeps spaces, grants and durable sessions across restarts

What your application does

  • Decides what is a fact worth keeping, often with a model call
  • Builds the prompt from pins, recent turns and recalled facts
  • Calls the model
  • Chooses TTLs and when a session becomes durable

Limits

  • Pins have no REST route or MCP tool yet; set_data and get_data are on REST only. Use the Erlang API for pins.
  • Over REST and MCP, ttl must be a positive number of seconds; durable sessions are Erlang only.
  • The vector store is per node and does not replicate. Every node that opens the space needs the same embedder configured, or the open fails with embedder_required or embedder_mismatch.
  • Changing the policy later applies to new writes only; existing documents are not re-embedded.
  • Calls inside your Erlang node take no token. Tokens apply on REST and MCP.

Go further

Up and down to moveEnter to open