Memory

Memory is what an agent remembers about a person between conversations. It is a different thing from a thread, and confusing the two is the usual source of surprise.

A thread holds one conversation. Everything said in it is available to every run on it, and none of it is available anywhere else. Memory sits above that: durable facts an agent has learned, carried into new conversations that have no shared history at all.

How an agent uses it

Two tools are always available to an agent with memory enabled: search_memory and manage_memory. They are not part of the agent’s tools allowlist and cannot be granted or withheld there — memory is either on for the agent or off.

The agent is instructed to search memory early in a conversation, before asking a question the person has already answered, and to save facts that look durable rather than incidental. It is also instructed never to save credentials or secrets. That last instruction is a real constraint on behaviour, but it is an instruction to a model, not an enforcement mechanism — do not design a system whose safety depends on it.

Between runs, memory is consolidated in the background: recent observations are merged, contradictions resolved, and stale entries rewritten or expired. Consolidation is debounced, so a burst of activity produces one pass rather than one per turn, and it runs outside the run itself, so it never adds latency to an answer.

Who a memory belongs to

Memory is scoped to a tenant and a user — not to an agent and not to a thread.

Two consequences follow, and both are load-bearing.

Memories are shared across agents. What one agent learns about a person, another agent serving the same person in the same tenant can find. That is usually what you want: a user should not have to introduce themselves separately to every agent. It also means a fact saved by a casual agent is visible to a serious one, so the standard for what is worth saving should be set with the whole tenant in mind.

For an API client, the “user” is the key. When a request authenticates with a tenant API key, the identity is that key, not a human behind it. So every conversation your service has through one key accumulates into a single memory scope. If your service handles many end users, they will share one memory, which is almost certainly not what you want — give each end user their own key, or turn memory off for the agent your service calls and handle per-user state yourself.

Turning it off

Set memory: disabled in an agent’s frontmatter. This is a per-agent setting, and it removes all three parts at once: the instruction in the prompt, both tools, and background consolidation. The agent becomes genuinely stateless between threads rather than merely discouraged from remembering.

Disable it when statelessness is the requirement — a classifier, an extraction step, anything whose output should depend only on its input. Leave it enabled for anything conversational.

The default is enabled, so an agent that says nothing about memory has it.

Inspecting and deleting

The Memory screen browses long-term memory for your tenant: search it, read individual entries, and delete them per user. Deletion is real deletion, which is what makes it usable for a data-subject request.

Memory is not part of the published API. It is read and written by agents during runs, and administered through that screen.

What not to put in it

Memory is a convenience for continuity, not a store of record. It holds what a model judged worth remembering, phrased how the model chose to phrase it, and consolidation may rewrite it later. Nothing about it guarantees that a specific fact is present, unchanged, or findable.

So: no authoritative data, no audit trail, nothing you would be unable to reconstruct from a real source. Documents go in a collection. Conversation history stays in its thread. Memory is for the small durable things — a preference, a role, a constraint someone stated once and should not have to state again.

Next: Trust tiers.