Memory

Memory lets an agent remember things between sessions. Unlike a knowledge base, which holds documents you curate, memory is self-authored: the agent picks up facts from its own conversations and is reminded of the relevant ones the next time they matter.

Turn it on for agents that benefit from continuity: an assistant that should remember how you like things done, a support agent that should recall a customer's history, a research agent that should build on earlier findings.

Why this matters

By default, every session starts blank. The agent has no idea what happened last time. Memory closes that gap: facts worth keeping are stored when a session ends, and in later sessions the ones relevant to the conversation are added to the agent's context automatically.

This is different from a knowledge base in a way that matters:

• A knowledge base is what you told the agent: authoritative reference you curate.
• Memory is what the agent learned: facts it picked up from its own conversations.

Use memory for "I prefer concise answers" or "this customer moved to the annual plan in March", not as a place to store documents.

The four tiers

Memory is organised into four tiers. You don't move memories between tiers by hand; the platform does it as described below.

Tier	What it holds	How it gets there	How it leaves
Working	Notes the agent saves during a session	The agent's remember tool	Folded into the session's facts when it ends; the note itself expires after 24 hours
Episodic	Individual facts from one past session	Extracted when a session ends	Distilled into a semantic fact, or archived when old and unused
Semantic	Durable facts that several sessions agree on	Distilled from episodic facts	Replaced by a newer fact, or merged with a near-duplicate
Procedural	Repeated "how to" patterns in the agent's behaviour	Detected during consolidation	Replaced by a newer pattern

How memory is written

When a session ends: fact extraction

When a chat session with a memory-enabled agent ends, the platform reads the conversation once and extracts a short list of facts worth keeping. Each fact is stored as its own episodic memory and labelled with a kind:

Kind	Example
Preference	"Prefers summaries as bullet points"
Decision	"Chose the annual billing plan"
Environment	"The staging database is hosted in Sydney"
Outcome	"The March invoice dispute was resolved with a credit note"
Open question	"Still waiting on legal sign-off for the new contract"

The same step checks the memories that were used in that session:

• a memory the conversation confirmed is marked as used, which keeps it ranked highly;
• a memory the conversation contradicted is replaced by the new fact, so the agent stops being told something that is no longer true.

A session with nothing worth keeping stores nothing. If the extraction step fails (for example, the model is briefly unavailable), nothing is stored for that session and it is retried later; the platform never stores a raw chunk of conversation in place of a fact.

Distillation into semantic facts

When several episodic facts say the same thing, they are distilled into a single semantic fact. A group is ready when three or more similar facts agree, or when facts from two or more sessions agree and at least one has been used. Distillation:

• writes one semantic fact that lists its sources, so you can always see which episodes it came from;
• marks the source facts as replaced by the new one, rather than deleting them;
• merges semantic facts that are near-duplicates of each other the same way.

Distillation never creates a fact from a single source. It runs at the end of each session and when you choose Consolidate now on the agent's Memory tab.

The agent's own remember and recall tools

A memory-enabled agent also gets two built-in tools it can use during a conversation:

• remember saves one fact the agent wants to keep, for example when you say "remember that I prefer…". It is stored as a working note, read alongside the transcript when the session's facts are extracted, and expires after 24 hours. A note can be up to 4,000 characters.
• recall searches the agent's memory on purpose, mid-conversation, when the agent decides it needs something it was not already given. A memory the agent recalls this way counts as used.

The agent cannot choose whose memory it reads or writes: that always comes from the session it is running in.

How memory is used

When a memory-enabled agent is in a conversation, the platform searches its memory for what is relevant and adds the best matches to the agent's context. The search:

• never returns memories that have expired, been archived, or been replaced by a newer fact;
• never returns another person's private memories (see Who can see a memory);
• ranks results by relevance, then weighs in how important and how recent each memory is, with semantic and procedural facts ahead of individual episodes;
• stays within the token budget of the agent's memory policy, and leaves out memories below the platform's minimum relevance score.

The same step searches the knowledge bases attached on the agent's Memory tab, so an agent is only given knowledge-base content when its memory is on.

Memories used in a chat

In a chat, open the menu in the chat header and choose Memories used to see the memories that were added to the agent's context in that session. If one is wrong or out of date, choose Forget this to delete it on the spot.

Keeping memory small: the nightly sweep

Every night a sweep tidies each memory-enabled agent's memory under that agent's own policy. It is entirely rule-based: it makes no model calls and never invents, rewrites or promotes a fact. In order, it:

1. deletes working notes that have expired;
2. archives episodic facts that are older than the policy's retention period and have been used fewer times than the policy requires;
3. lowers the importance of memories that are old or rarely used;
4. archives the lowest-ranked memories in any tier that is over the policy's cap;
5. permanently deletes memories that have been archived for longer than the archive window;
6. applies your organisation's data retention rules.

Agents with memory turned off are skipped.

note

The sweep is introduced in a reporting mode first: it records what it would do for each agent without changing anything. Your administrator switches it to live once its reports have been reviewed.

Archive, restore and permanent deletion

Removal is gradual. A memory that is archived (by the sweep, or because the agent's cap was reached) is no longer used in conversations, but it still appears in the archived view of the Memory tab, where you can restore it. Archived memories are permanently deleted after 90 days (the Compliance policy keeps them far longer), or sooner if your organisation's retention period is shorter.

Memories that were replaced by a newer fact are kept as the sources of that fact, so a distilled fact can always be traced back to what it was built from.

Memory policies

How much an agent keeps and how much it is given in each conversation is set by its memory policy. The agent's own policy is applied by distillation, by Consolidate now, by the nightly sweep and by every memory search.

You choose it with the Memory Policy setting on the agent:

Memory Policy option	Behaviour
Platform Default	Uses the platform default, which is Knowledge Worker
Off	No memory captured or recalled
Conversational (short retention)	Episodic facts kept 14 days, small caps (100 episodic, 50 semantic facts), a 1,500-token budget; no procedural patterns
Knowledge Worker (durable)	Episodic facts kept 90 days, caps of 500 episodic and 200 semantic facts, a 3,000-token budget
Compliance (curated)	Ten-year retention, no caps, nothing archived for being unused, a 2,000-token budget

A policy sets how long each tier is kept, the cap on each tier, whether unused facts are archived, and the token budget for memories added to a conversation. Your organisation's retention period always applies on top; nothing is kept longer than it.

Who can see a memory

By default a memory is private to the person whose session produced it. If Alex and Sam both chat with the same agent, Alex's preferences are only ever brought into Alex's conversations.

Some agents are meant to learn as a team, such as an agent that supports a whole department. For those, set Memory sharing on the agent's Memory tab to Shared across users: every memory the agent records is then available in every user's conversations with it. Changing it needs the Editor role.

Memory sharing	Who a new memory is used for
Private to each user (default)	Only the person whose session produced it
Shared across users	Everyone who chats with the agent

Memories recorded before per-user privacy was introduced have no owner and are treated as shared. Distillation never mixes people: one person's private facts are only ever distilled with that same person's facts.

Memory is also scoped to the agent. Each agent keeps its own memory; nothing one agent learns is given to another.

Enabling memory for an agent

1. Open the agent under Build → Agents.
2. Tick the Memory checkbox.
3. (Optional) choose a Memory Policy other than Platform Default.
4. Save the agent.
5. (Optional) on the agent's Memory tab, set Memory sharing to Shared across users if the agent should learn across users.

Memory needs a Default Embedding Model (to search by meaning) and a Crystallization Model (to extract and distil facts). Platform administrators set both under Settings. The readiness line at the top of the Memory tab summarises the agent's memory (on or off, policy, sharing, and whether each model is configured), and a Memory is not fully working for this agent panel lists anything wrong, such as a missing model, memories that are not yet searchable by meaning, or a nightly sweep that has not run recently.

Turning memory on also gives the agent the remember and recall tools, and is what lets it use any knowledge bases attached on its Memory tab.

Turning memory off stops capture and recall; the agent's existing memories are kept until you clear them.

Reviewing and correcting memory

The agent's Memory tab lets you:

• attach and detach knowledge bases under Attached Knowledge Bases;
• Search memories, and filter by Kind and Tier;
• see each memory's importance, how often it has been used, when it was last used, and its age;
• open a semantic fact to see the sources it was distilled from, and see which fact replaced an older one;
• switch between Active and Archived memories, and Restore an archived one;
• Edit or Delete a memory, Delete selected memories, or Clear all memories (or all of the selected tier);
• run Consolidate now, which distils and tidies this agent's memory immediately under its own policy and reports what changed;
• open the Audit log.

The memory list shows only memories you are allowed to see: your own private memories and any shared ones.

Deleting (forgetting) a memory also deletes any semantic or procedural fact that was distilled from it, so a fact you have removed does not live on in a summary.

The audit trail

Audit log on the Memory tab records what happened to the agent's memory:

Action	Recorded when
inject	Memories were added to a conversation, with which ones
search	The agent recalled, or someone searched, the agent's memory
consolidate	Memory was consolidated, by Consolidate now or by the live nightly sweep
forget	One or more memories were deleted
restore	An archived memory was restored

Cost

Extracting facts at the end of a session and distilling them use your organisation's memory model, and that usage shows up in your usage reports like any other model use. A daily memory budget per organisation caps it: once the day's budget is spent, distillation waits until the next day. The nightly sweep makes no model calls and costs nothing.

Tips

• Memory is not a document store. For curated reference material, use a Knowledge Base. For exact rules and config, use a Manifest.
• Start with the default policy. Knowledge Worker suits most agents; only switch if you need lighter chat retention or longer, uncapped retention.
• Keep memory private unless the agent serves a team. Shared memory is useful for a team assistant and surprising for a personal one.
• Correct it when it is wrong. Forgetting an out-of-date memory from the Memories used panel is the fastest way to stop an agent repeating it.
• Turn it off when continuity doesn't help. A stateless agent that should treat every request identically is better off without memory.

Through the API

Memory is also available through the platform API under /episodic-memories and the platform tools (list_memories, search_memories, observe_memory, consolidate_memories, update_memory, delete_memory, clear_memories). Through the API you can also set a per-agent retention period, which can only shorten the policy's.

Related

• Choosing How to Add Knowledge: when to use memory versus the alternatives
• Knowledge Bases: curated documents, not self-learned facts
• Agents: enable memory per agent