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/1with anembeddingpolicy: every document with acontentfield, messages included, is embedded in the same write.barrel_session:create/2withttl => infinity,add_message/3,pin_context/3(lower priority comes first),set_data/4.- On the second node,
barrel_spaces:open_space/1reopens the space in record mode with the embedder fromconfig/sys.config({barrel_spaces, [{embedder, ...}]}), and messages, pins, data and the vector index are all there. barrel:search/3over facts and messages together;typein 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
%% 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. %% 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. {erl_opts, [debug_info]}.
{deps, [{barrel, "~> 1.12"},
{barrel_spaces, "~> 1.3"}]}. %% 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}}}]}]}]. #!/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.
== 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