Skip to navigation

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.

View as Markdown

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

FolderWho it belongs toWho changes it
memories/agent/The agent. Everyone who talks to it shares this folder.Only background dreaming. Conversations can read it but not change it.
memories/user/One end user of the agent.That user’s conversations, dreaming, forget requests, and you through the API.

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_id and user_id your 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:

---
tools:
memory:
enabled: true
shared: true # mount memories/agent/
user: true # mount memories/user/
---
# Support guide
Keep short notes about each customer's setup in memories/user/.
FieldDefaultEffect
enabledtruefalse turns memory off.
policyallowdeny turns memory off.
sharedtrueMount the shared memories/agent/ folder.
usertrueMount the end user’s memories/user/ folder.

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.

RefusalWhen
read_onlyA conversation tries to change memories/agent/.
limitThe folder would go over its file or size limit. The agent is told to consolidate.
conflictAnother conversation changed the same files since this one read them. The agent re-reads and retries.
forgottenThe change contains text the user asked to forget.
privateA dream tried to add personal details to the shared folder.
revokedMemory was turned off, or the run’s access narrowed, after the run started.
FolderFilesTotal size
memories/user/2002 MiB
memories/agent/5004 MiB

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.

StatusMeaning
pendingThe forget is running. The text stays blocked.
completeThe text was removed.
nothing_foundThe text was not in memory.
failedRemoval did not finish after several attempts. The text stays blocked. Ask again to retry.
reversedThe user asked to remember it again.

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:

SettingDefaultEffect
memoryDreamAutotrueTurns automatic dreaming on or off.
memoryDreamIdleSeconds900 (null uses the default)Idle seconds before a dream, from 60 to 604,800.
sikaru agent managed-agents update --project-id PROJECT --agent-slug support \
--json '{"memoryDreamIdleSeconds": 3600}'

Dream now starts a dream without waiting for idle time, even with automatic dreaming off.

Dream statusMeaning
requestedWaiting to start.
runningIn progress.
completeFinished.
failedDid not finish. The next dream reads the same conversations again.
cancelledA forget arrived while it ran. The next dream reads the same conversations again.
disabledMemory is off for the agent.

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.

# List a user's memory files and the folder's current head
sikaru agent memory list_files --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7
# Read one file
sikaru agent memory read_file --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7 --path MEMORY.md
# Write a file, naming the head you read
sikaru agent memory write_file --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7 \
--path notes/setup.md --content "Uses the EU region." --base HEAD_ID

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.

# Versions and rollback
sikaru agent memory list_versions --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7
sikaru agent memory rollback --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7 --version 12
# Forget on the user's behalf, then follow it
sikaru agent memory forget --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7 --target "my home address"
sikaru agent memory get_forget --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7 --job-id JOB_ID
# Dream now, then read its status
sikaru agent memory dream --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7
sikaru agent memory get_dream --project-id PROJECT --agent-slug support \
--directory user --tenant-id customer-42 --user-id user-7

The other operations are move_file, delete_file, list_forgets and remember. In Python they are the same names on client.memory:

files = client.memory.list_files(
project_id="PROJECT", agent_slug="support",
directory="user", tenant_id="customer-42", user_id="user-7",
)
client.memory.write_file(
project_id="PROJECT", agent_slug="support",
directory="user", tenant_id="customer-42", user_id="user-7",
path="notes/setup.md", content="Uses the EU region.", base=files.head,
)

Access

ActionPermission
Read the shared folderharness:read or managed_agents:write
Change the shared folder, or read or change a user foldermanaged_agents:write

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 endUserCells opens 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.

Next steps