Barrel
FR GitHub

Agent memory across restarts

This project keeps an agent's memory in a Barrel space: a session with its messages, pinned context and working data, plus long-term facts stored as documents that are embedded when they are written (record mode) and recalled by search. A first node writes the memory and stops; a second node opens the same data and recalls it. Use it as a starting point when an agent must remember across runs and crashes.

Prerequisites

  • Erlang/OTP 26 or later (this run used OTP 29) and rebar3.
  • A C compiler and CMake for the native dependencies (first compile takes a few minutes).
  • No model and no network: the embedder is hash_embed, below.

Run

./run.sh

run.sh compiles the project, deletes ./data, then starts two separate nodes on the same data directory: agent_memory:main(write) and agent_memory:main(recall).

What it shows

  • barrel_spaces:create_space/1 with an embedding policy: every document with a content field, messages included, is embedded in the same write.
  • barrel_session: create/2 with ttl => infinity, add_message/3, pin_context/3 (lower priority comes first), set_data/4.
  • On the second node, barrel_spaces:open_space/1 reopens the space in record mode with the embedder from config/sys.config ({barrel_spaces, [{embedder, ...}]}), and messages, pins, data and the vector index are all there.
  • barrel:search/3 over facts and messages together; type in the metadata tells them apart.

About the embedder

hash_embed is a small deterministic provider written for this example: it hashes words into 64 dimensions, so it matches shared words and does not understand meaning. It keeps the run offline and the output stable. Its scores are not a measure of search quality. For real recall, use a model: set the space's embedder (and the barrel_spaces env) to {ollama, #{url => ..., model => ...}} or {local, #{}}, with the matching dimensions. See choose an embedding provider.

Expected output

Node 1 prints the session id and the first search; node 2 prints the messages, pins and data it read back and two searches. The output of a real run is in expected.txt; the session id differs on every run.

Download The folder on GitHub, with every file below.

Source

src/agent_memory.erl
%% An agent's memory in a Barrel space. main(write) runs on a first
%% node; main(recall) runs on a second node over the same data.
-module(agent_memory).
-export([main/1, write/0, recall/0]).

-define(LABEL, <<"assistant memory">>).

main(Phase) ->
    try
        {ok, _} = application:ensure_all_started(barrel_spaces),
        ok = ?MODULE:Phase(),
        halt(0)
    catch C:R:S ->
        io:format(standard_error, "~p:~p~n~p~n", [C, R, S]),
        halt(1)
    end.

%% Record mode: every document with a "content" field is embedded
%% in the same write. hash_embed is a stand-in for a real model.
policy() ->
    #{fields => [<<"content">>], mode => sync,
      embedder => {hash_embed, #{}}, dimensions => 64,
      metadata_fields => [<<"type">>]}.

write() ->
    io:format("== node 1: write~n"),
    {ok, Space} = barrel_spaces:create_space(
        #{label => ?LABEL, owner => <<"assistant">>,
          embedding => policy()}),
    Db = maps:get(db, Space),

    %% A session with no expiry, and the conversation so far.
    {ok, Sid} = barrel_session:create(
        Space, #{agent => <<"assistant">>, ttl => infinity}),
    io:format("session ~s~n", [Sid]),
    Turns = [
        {<<"user">>, <<"Our staging database runs on host db2">>},
        {<<"assistant">>, <<"Noted: staging is on db2">>},
        {<<"user">>, <<"Never deploy to production on Friday">>}
    ],
    [{ok, _} = barrel_session:add_message(
                 Space, Sid, #{role => R, content => C})
     || {R, C} <- Turns],
    io:format("messages added: ~b~n", [length(Turns)]),

    %% Pinned context comes back first, by priority.
    {ok, _} = barrel_session:pin_context(
        Space, Sid, #{content => <<"Reply in short sentences">>,
                      priority => 0}),
    {ok, _} = barrel_session:pin_context(
        Space, Sid, #{content => <<"Project codename: Atlas">>,
                      priority => 1}),

    %% Working state, keyed.
    {ok, _} = barrel_session:set_data(
        Space, Sid, <<"current_task">>, <<"upgrade billing">>),

    %% Long-term facts: plain documents, embedded on write.
    Facts = [
        <<"The billing service is written in Erlang">>,
        <<"Backups of db2 run every night at 02:00">>,
        <<"Production deploys need a review from Sam">>
    ],
    [{ok, _} = barrel:put_doc(Db, #{
         <<"id">> => <<"fact:", (integer_to_binary(N))/binary>>,
         <<"type">> => <<"fact">>, <<"content">> => F})
     || {N, F} <- lists:zip(lists:seq(1, length(Facts)), Facts)],
    io:format("facts written: ~b~n", [length(Facts)]),

    recall(Db, <<"when can I deploy to production">>),
    ok = barrel_spaces:close_space(maps:get(id, Space)),
    ok.

recall() ->
    io:format("== node 2: recall after a restart~n"),
    {ok, Spaces} = barrel_spaces:list_spaces(),
    [Id] = [maps:get(<<"space">>, S) || S <- Spaces,
            maps:get(<<"label">>, S) =:= ?LABEL],
    %% Reopens in record mode with the embedder from sys.config.
    {ok, Space} = barrel_spaces:open_space(Id),
    {ok, [Session]} = barrel_session:list(Space),
    Sid = maps:get(<<"session">>, Session),
    io:format("session ~s (agent ~s)~n",
              [Sid, maps:get(<<"agent">>, Session)]),

    {ok, Msgs} = barrel_session:get_messages(Space, Sid),
    io:format("messages:~n"),
    [io:format("  ~s: ~s~n", [maps:get(<<"role">>, M),
                              maps:get(<<"content">>, M)])
     || M <- Msgs],

    {ok, Pins} = barrel_session:list_pinned(Space, Sid),
    io:format("pinned:~n"),
    [io:format("  ~b ~s~n", [maps:get(<<"priority">>, P),
                             maps:get(<<"content">>, P)])
     || P <- Pins],

    {ok, Task} = barrel_session:get_data(
        Space, Sid, <<"current_task">>),
    io:format("current_task: ~s~n", [Task]),

    Db = maps:get(db, Space),
    recall(Db, <<"when can I deploy to production">>),
    recall(Db, <<"where is the staging database">>),
    ok = barrel_spaces:close_space(Id),
    ok.

%% Top 3 by vector search; scores come from hash_embed, so they
%% measure shared words, not meaning.
recall(Db, Question) ->
    {ok, Hits} = barrel:search(Db, Question,
                               #{k => 3, include_text => true}),
    io:format("search \"~s\":~n", [Question]),
    [io:format("  ~.3f ~s ~s~n",
               [S, maps:get(<<"type">>, M, <<"?">>), T])
     || #{score := S, metadata := M, text := T} <- Hits],
    ok.
src/hash_embed.erl
%% A deterministic, offline embedding provider for examples and tests:
%% 64-dimension feature hashing of the words. It matches shared words,
%% it does not understand meaning. Use a real model in production.
-module(hash_embed).
-behaviour(barrel_embed_provider).
-export([name/0, dimension/1, embed/2, embed_batch/2,
         model_info/1]).

-define(DIM, 64).

name() -> hash_embed.
dimension(_Config) -> ?DIM.
model_info(_Config) -> #{model => <<"hash-64">>}.

embed(Text, _Config) -> {ok, vec(Text)}.
embed_batch(Texts, _Config) -> {ok, [vec(T) || T <- Texts]}.

vec(Text) ->
    Words = string:lexemes(string:lowercase(Text),
                           " \n\t.,;:!?()'\""),
    Zero = erlang:make_tuple(?DIM, 0.0),
    Counts = lists:foldl(
        fun(W, Acc) ->
            I = erlang:phash2(W, ?DIM) + 1,
            setelement(I, Acc, element(I, Acc) + 1.0)
        end, Zero, Words),
    L = tuple_to_list(Counts),
    case math:sqrt(lists:sum([X * X || X <- L])) of
        +0.0 -> L;
        N -> [X / N || X <- L]
    end.
rebar.config
{erl_opts, [debug_info]}.
{deps, [{barrel, "~> 1.12"},
        {barrel_spaces, "~> 1.3"}]}.
config/sys.config
%% Data under ./data, logs on stderr so stdout is the example output.
%% barrel_spaces reopens a record-mode space with this embedder.
[{barrel_docdb, [{data_dir, "data/docdb"}]},
 {barrel_spaces, [{embedder, {hash_embed, #{}}}]},
 {kernel, [{logger_level, warning},
           {logger, [{handler, default, logger_std_h,
                      #{config => #{type => standard_error}}}]}]}].
run.sh
#!/bin/sh
# Build, then run two separate nodes on the same data directory:
# the first writes the memory, the second recalls it.
set -e
cd "$(dirname "$0")"
rebar3 compile >&2
rm -rf data
for phase in write recall; do
  erl -noshell -config config/sys \
    -pa _build/default/lib/*/ebin _build/default/checkouts/*/ebin \
    -eval "agent_memory:main($phase)"
done

Expected output

The expected.txt of the example, from a real run. Revisions, ids, tokens and timestamps differ on every run; scripts/verify-examples.sh masks them before it compares.

expected.txt
== node 1: write
session ses_vl6c7rwng4nw4ayc
messages added: 3
facts written: 3
search "when can I deploy to production":
  0.667 message Never deploy to production on Friday
  0.463 fact Production deploys need a review from Sam
  0.309 message Our staging database runs on host db2
== node 2: recall after a restart
session ses_vl6c7rwng4nw4ayc (agent assistant)
messages:
  user: Our staging database runs on host db2
  assistant: Noted: staging is on db2
  user: Never deploy to production on Friday
pinned:
  0 Reply in short sentences
  1 Project codename: Atlas
current_task: upgrade billing
search "when can I deploy to production":
  0.667 message Never deploy to production on Friday
  0.463 fact Production deploys need a review from Sam
  0.309 message Our staging database runs on host db2
search "where is the staging database":
  0.507 message Our staging database runs on host db2
  0.448 fact The billing service is written in Erlang
  0.400 message Noted: staging is on db2

Up and down to moveEnter to open