Mémoire d’agent qui survit aux redémarrages
Ce projet conserve la mémoire d’un agent dans un espace Barrel : une session avec ses messages, son contexte épinglé et ses données de travail, plus des faits à long terme stockés comme documents, convertis en embeddings à l’écriture (mode enregistrement) et retrouvés par recherche. Un premier nœud écrit la mémoire et s’arrête ; un second nœud ouvre les mêmes données et les retrouve. Partez de cet exemple quand un agent doit se souvenir d’une exécution à l’autre et après un plantage.
Prérequis
- Erlang/OTP 26 ou plus récent (cette exécution a utilisé OTP 29) et rebar3.
- Un compilateur C et CMake pour les dépendances natives (la première compilation prend quelques minutes).
- Ni modèle ni réseau : l’embedder est
hash_embed, décrit plus bas.
Exécuter
./run.sh
run.sh compile le projet, supprime ./data, puis lance deux nœuds
distincts sur le même répertoire de données : agent_memory:main(write)
et agent_memory:main(recall).
Ce que montre l’exemple
barrel_spaces:create_space/1avec une politiqueembedding: chaque document qui a un champcontent, messages compris, reçoit son embedding dans la même écriture.barrel_session:create/2avecttl => infinity,add_message/3,pin_context/3(la priorité la plus basse passe en premier),set_data/4.- Sur le second nœud,
barrel_spaces:open_space/1rouvre l’espace en mode enregistrement avec l’embedder deconfig/sys.config({barrel_spaces, [{embedder, ...}]}), et messages, épingles, données et index vectoriel sont tous là. barrel:search/3sur les faits et les messages ensemble ;typedans les métadonnées permet de les distinguer.
À propos de l’embedder
hash_embed est un petit fournisseur déterministe écrit pour cet
exemple : il hache les mots sur 64 dimensions, il retrouve donc les mots
communs mais ne comprend pas le sens. Il permet une exécution hors ligne
et une sortie stable. Ses scores ne mesurent pas la qualité de la
recherche. Pour un vrai rappel, utilisez un modèle : réglez l’embedder
de l’espace (et l’environnement de barrel_spaces) sur
{ollama, #{url => ..., model => ...}} ou {local, #{}}, avec les
dimensions correspondantes. Voir
choisir un fournisseur d’embeddings.
Sortie attendue
Le nœud 1 affiche l’identifiant de session et la première recherche ; le
nœud 2 affiche les messages, les épingles et les données qu’il a relus,
et deux recherches. La sortie d’une exécution réelle se trouve dans
expected.txt ; l’identifiant de session change à chaque exécution.
Télécharger Le dossier sur GitHub, avec tous les fichiers ci-dessous.
Code 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 Sortie attendue
Le fichier expected.txt de l’exemple, issu d’une exécution réelle. Les révisions, identifiants, jetons et horodatages changent à chaque exécution ; scripts/verify-examples.sh les masque avant de comparer.
== 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