Give an agent memory
Someone tells your agent on Monday that they manage the EU region and prefer short answers. On Thursday they come back, and the agent has no idea who they are. Memory is what closes that gap: preferences, constraints, decisions, and task state saved during one conversation and recalled in later ones.
Turn it on by granting the capability in agent.toml:
toolsets = ["memory"]That is the whole setup. The agent can now save and recall memories on its own.
Two scopes
session memories belong to one conversation. user memories follow the signed-in user
across sessions. The agent picks per save; default_scope decides when it does not say.
session scope expires on its type's TTL like anything else. It scopes who sees it.
What the agent does on its own
The agent decides what is worth keeping, and saving is a tool call. If you would rather approve
that, gate it in intent.toml:
[autonomy]
"save_memory" = "require_approval"Memory reaches the model as fenced content in the system prompt, so a saved note cannot smuggle instructions into a later turn.
Tuning recall
user_prompt_max = 15 # user memories injected per prompt (0 disables)
session_prompt_max = 20 # session memories injected per prompt (0 disables)
[ttl] # days before a memory expires; 0 = never
decision = 90 # design and architecture choices
constraint = 180 # rules and limits
preference = 365 # user habits and likes
fact = 180 # reference knowledge
task_state = 30 # in-progress work status
[search] # the three weights must sum to 1.0
semantic_weight = 0.55 # meaning similarity
keyword_weight = 0.35 # exact word overlap
recency_weight = 0.10 # how recently it was saved
recency_half_life_days = 90.0 # days for the recency boost to halve
[recall] # drop weak matches before they reach the model
min_score_semantic = 0.20
min_score_keyword = 0.35
min_score_hybrid = 0.30
score_ratio = 0.50 # keep hits scoring this fraction of the top hit
[save_defaults] # used when the agent saves without saying
default_confidence = 0.8
default_scope = "session"Favour keyword_weight for exact-term domains and semantic_weight for conversational ones.
When recall is noisy, score_ratio and min_score_hybrid are the two that tighten it most.
Two habits keep memory useful over time: do not store secrets or fast-changing facts as durable memory, and when recall feels noisy, look at what was actually saved before you start adjusting search weights. Ask the agent to recall with no search term and it lists what is in scope, which is usually enough to see whether the problem is storage or retrieval. It is generally the writing.
Memory, context, and RAG are different tools
They all put information in front of the model.
| Holds | Scoped to | Reach for it when | |
|---|---|---|---|
| Memory | Facts learned during conversations | A user or a session | The agent should remember something a person told it |
| Context files | Stable instructions and background | Every run | The information is small and always relevant |
| RAG | Your document corpus | Searched per question | The answer is somewhere in a body of documents |
A support agent uses all three at once: RAG for the product documentation, a context file for tone, memory for this customer's account details.
Next
- Add RAG - ground answers in documents rather than recollection.
- Manage long conversations - what happens when a session outgrows the context window.
- - scopes, types, defaults, and search controls.