Memories
Durable notes your agents recall on later runs — and the first place to look when one starts behaving oddly.
A memory is a short note stored on your account for agents to recall later. Beta A run is otherwise stateless: an agent starts each one with its instructions, its tools, and whatever it is handed. Memories are the exception — they are the one thing that carries from one run to the next.
Memories belong to the account, not to a single agent. Every agent in the account draws from the same pool, so a memory you save while working with one agent changes how all of them behave.
In the dashboard the account's memories are listed under Agents → Memories, and records such as customers carry a Memories card where you can add one without leaving the record.
What a memory holds
| Field | What it is |
|---|---|
| Category | How the note should be read — one of three values, below |
| Content | The note itself, in plain text, written for an agent to read |
| Importance | A weight from 0 to 1 that decides which memories survive when there are too many to recall |
| Expires at | When the note stops being used. Empty means it is kept indefinitely |
| Entity | The record the note is about — a customer, a product — or nothing, for a note about the account |
| Metadata | Free-form JSON stored alongside the note. Useful for recording where a memory came from |
The three categories
| Category | Use it for |
|---|---|
preference | How someone likes things done — a customer who always wants express shipping |
fact | A durable detail worth remembering about the account or one of its records — a customer's typical order size |
instruction | Standing guidance for agents to follow — always confirm freight before issuing an order |
Only these three are accepted. A memory saved with any other category is rejected.
The Memories card on a record offers exactly these three. The standalone create form under Agents → Memories still lists an older set of options, and only Preference on that screen maps to a category the API accepts — so save a fact or an instruction from the record card or the API instead.
The distinction matters because the category is passed to the agent verbatim, in front of the note. An agent reading [instruction] Always confirm freight before issuing an order treats it as a rule; the same sentence filed as a fact reads as background. If you want behavior changed, file it as an instruction.
Importance decides what survives
Importance runs from 0 to 1 in steps of 0.1 — the dashboard exposes it as a slider, and a value off that grid is rejected. A memory saved without an importance is stored at 0.
The weight is not a confidence score. It is a queue position: an agent takes in only a limited number of memories per run and takes the highest-importance ones first, so a 0 memory is the first to be left out once the account accumulates more notes than a run can carry. Reserve the top of the range for the handful of rules you always want honored.
Expiry
Set Expires at on anything that is only true for a while — a plant shutdown, a temporary substitution, a stand-in contact. Once that time passes:
- the memory stops being recalled by agents,
- it disappears from the memories list,
- but it is not deleted, and it is still reachable by its ID.
That last point is deliberate: an expired memory remains auditable, so you can still answer "what was the agent told last quarter?" To make a memory permanent again, clear its expiry.
What an agent actually recalls
This is the part worth being precise about, because it is not "everything you saved."
At the start of every run — every trigger type, every agent — the agent loads up to 50 of the account's memories, ordered by importance, skipping any that have expired, and appends them to its instructions under the heading Relevant memories from previous interactions. Each one arrives as its category and its content, nothing else.
The memories loaded this way are the ones scoped to the account itself — entity type account, with your own account ID () as the entity ID. In the dashboard that means setting Entity Type to Account and pasting your account ID into Entity ID.
Memories scoped to a specific record — a customer, a product — are stored, listed, filterable, and readable by an agent that holds the memory tools, but they are not part of the block loaded into every run.
So there are two distinct things you can do with a memory:
- Account-scoped — changes how agents behave on every run, silently, forever. Treat these as configuration.
- Record-scoped — context filed against a record, retrievable when an agent goes looking, and visible to your team on that record.
Memories change behavior invisibly
Nothing on a run says "this happened because of a memory." The note is folded into the agent's instructions before the model ever sees the task, so its effect shows up as the agent simply behaving differently — quoting a different lead time, refusing to issue an order, addressing a customer by a nickname nobody configured.
When an agent starts doing something you did not ask for, read the memories first. It is faster than rereading the agent's instructions, and it is the more common cause: instructions change when someone edits an agent, and memories change whenever anyone — or any agent — writes one.
Editing or deleting a memory takes effect on the next run. There is nothing to redeploy.
Agents can write their own memories
Memory operations are also available to agents as tools: create_agent_memory, list_agent_memories, retrieve_agent_memory, update_agent_memory, and delete_agent_memory, grouped under Memories when you grant tools to an agent. An agent holding those tools can write down what it learns and read it back on a later run — and can equally write down something wrong. The same scoping rule applies to what it writes: an account-scoped memory joins the block every run loads, while a record-scoped one is only found when an agent goes looking for it.
Two controls apply, and they are the same ones that govern every other tool:
- The agent's role still gates the call. Without read/create/update/delete permission on agent memories, the tool fails when it reaches the API.
- Human review can be required on any of those tools, so the run pauses and waits for you before a memory is written. The runtime does not require it unless you say so, but the dashboard tool picker switches review on automatically for the three memory-writing tools the moment you grant them — you can turn it off, but you have to choose to. See Tools & approvals.
If you would rather agents never edit the shared pool, grant them no memory tools at all. They will still recall the account's memories — recall does not need a tool.
Next: Agents in chat