Agent memory
Give an agent plain-file memory that it reads and edits, keep one private folder per end user, and manage files, versions, forgets and dreams from the API, SDK or CLI.
Memory lets an agent carry what it learns from one conversation to the next. It is plain files that the agent reads and edits with its ordinary file tools. There is no separate memory database to learn.
Two folders
Paths are relative to the agent’s working directory: memories/user/notes.md, not /memories/user/notes.md.
Each folder can hold a MEMORY.md index. At the start of every turn the agent sees the shared index first, then the user’s. Each index is shown up to 7,500 characters; a longer one is cut and says so. Every other file loads only when the agent opens it, so keep MEMORY.md short and point it at the detail files.
Draft runs have their own memory. Staging and production share the published memory. Copies the agent writes elsewhere in its workspace are ordinary session files, not memory.
Who gets user memory
A run gets memories/user/ only when it identifies one end user:
- a signed-in user;
- a person on a personal channel;
- the
tenant_idanduser_idyour product passes with a project API key.
Shared channels, such as a Slack room, and schedules that run without a creator do not identify a user. Those runs get only memories/agent/.
Runs excluded from learning, such as evaluations, can read the user’s memory but cannot change it.
Turn memory on or off
Memory is on by default. Set it in the agent document with tools.memory:
Your project’s capability ceiling can also turn memory off. When memory is off, no folder is mounted and no dream runs, and a memories/ path is ordinary session content. Memory settings are always set by you; automatic improvement never changes them.
Saving and refusals
The agent’s memory changes are saved after every step, not only at the end of the run. Each step’s change to a folder is saved whole or not at all. When a change is refused, the folder goes back to its last saved state and the agent sees why before its next step. A refused write is never reported to the user as remembered.
Versions and rollback
Each run that changed a folder adds one version of it. Your own edits through the API add a version too. The 50 newest versions are kept.
Rolling back makes an older version current again and saves that as a new version, so you can undo a rollback. Branching or restoring a session never changes memory; the next turn sees the latest memory.
Forget and remember
The agent has a forget action and a remember action. It uses them only when the request is in the user’s own words, in their message or a steering message. Text from documents, tool results or quoted history cannot start or undo a forget. A forget target is 3 to 500 characters, and only a user folder can be forgotten from.
As soon as a forget is requested:
- memory changes that contain the text are refused;
- past-session search stops returning it;
- running dreams on the agent are cancelled, and no new dream starts until the forget ends.
A background run then removes the text from the user’s folder and any matching lines from the shared folder. When it finishes:
- the text is gone from current memory;
- conversations that contained it are dropped from past-session search and are not used by future dreams;
- older memory versions that mention it are removed, so rollback cannot bring it back.
Your product’s own conversation history and retained traces are unchanged.
Forget status shows counts and times, never the forgotten text.
Remember undoes the blocking of a finished or failed forget. Future conversations about the topic can be searched and dreamt over again. Removed history does not come back. Remember is refused while that forget is still pending.
Dreaming
While a user is away, the agent dreams. It reads that user’s recent conversations with the agent, fixes errors in their notes, merges duplicates, repairs links and keeps MEMORY.md current. After a user’s dream, the shared folder dreams on its own and reorganizes itself without reading anyone’s conversations.
Two agent settings control automatic dreaming:
Dream now starts a dream without waiting for idle time, even with automatic dreaming off.
Anything a dream adds to the shared folder passes a privacy review first. Lines with a user’s IDs, email addresses, secrets, links the user did not write, text copied from their notes, details about a specific person or organization, or standing instructions to contact someone or use a credential are refused. If the review cannot run, nothing is added.
Manage memory from your application
Each operation selects one folder: --directory agent (the default), or --directory user with --tenant-id and --user-id. Add --environment draft for draft memory; the default is published.
Writes, moves and deletes name the base head they were made from: the head value that list_files or read_file returned. If another writer changed the same file since, the request returns 409: read again and retry. Pass null as the base for an empty folder.
The other operations are move_file, delete_file, list_forgets and remember. In Python they are the same names on client.memory:
Access
Memory of agents with private conversations is narrower:
- A personal agent’s memory opens only to its owner, signed in, and only their own user folder.
- An agent created with
endUserCellsopens its memory only to a project API key, never a signed-in user token. Deleting one of its end users deletes their memory folder and its history.
End users change memory only through the agent, or through your product calling forget for them.
