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
-
Your agent
- Each turn appends messages, updates state
- Prompt builder pins, recent turns, recalled facts
- session calls, put_doc
-
Space sp_support
- Session ses_… messages, data, pins; sliding TTL
- Fact documents record mode: embedded on write
- embed facts, sweep
-
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.
-
Create a space with a memory policy
Optional, needs setupThe
embeddingpolicy turns the space into a record-mode database: documents with afactfield get a vector, kept in step with every update and delete. Session messages carry nofactfield, so they are not embedded.{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}}). -
Open a session for the conversation
A session is a document with a sliding expiry: every change pushes it back by
ttlseconds.{ok, Sid} = barrel_session:create(Space, #{agent => <<"support">>, ttl => 3600}).{"jsonrpc":"2.0","id":5,"method":"tools/call", "params":{"name":"session_create", "arguments":{"space":"sp_…","agent":"support", "ttl":3600}}} -
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">>}).{"jsonrpc":"2.0","id":6,"method":"tools/call", "params":{"name":"session_add_message", "arguments":{"space":"sp_…","session":"ses_…", "role":"user", "content":"I am locked out"}}} -
Keep working state and pinned context
set_dataholds 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).curl -X PUT \ localhost:8080/spaces/sp_…/sessions/ses_…/data/ticket \ -H 'authorization: Bearer bsp_…' \ -H 'content-type: application/json' \ -d '{"value":"T-311"}' -
Read the recent turns back
Newest first with
order => desc;sinceandbeforetake unix milliseconds.{ok, Recent} = barrel_session:get_messages(Space, Sid, #{limit => 20, order => desc}).{"jsonrpc":"2.0","id":7,"method":"tools/call", "params":{"name":"session_get_messages", "arguments":{"space":"sp_…","session":"ses_…", "limit":20,"order":"desc"}}} -
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.
{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}). -
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 => infinitymakes a durable session that never expires.{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).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_dataandget_dataare on REST only. Use the Erlang API for pins. - Over REST and MCP,
ttlmust 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_requiredorembedder_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.