> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Agent memory

Facts on this page:

1. Memory is two folders in the agent's workspace: `memories/agent/` (shared, read-only in conversations, curated by dreaming) and `memories/user/` (one per identified end user). `MEMORY.md` at each root is shown to the agent at the start of every turn, up to 7,500 characters each.
2. A run gets `memories/user/` only for a signed-in user, a personal-channel user, or the `tenant_id` and `user_id` your product passes with a project key. Shared channels and schedules with no creator get only `memories/agent/`.
3. Turn it on or off in the agent document with `tools.memory`: `enabled`, `policy`, `shared`, `user`.
4. Limits: 200 files and 2 MiB per user folder; 500 files and 4 MiB for the shared folder. 50 versions are kept per folder.
5. Refusals the agent sees: `read_only`, `limit`, `conflict`, `forgotten`, `private`, `revoked`.
6. Dreaming: `memoryDreamAuto` (default true) and `memoryDreamIdleSeconds` (default 900, 60 to 604800) on the agent. Dream status: `requested`, `running`, `complete`, `failed`, `cancelled`, `disabled`.
7. Forget status: `pending`, `complete`, `nothing_found`, `failed`, `reversed`.
8. API base: `/v1/projects/{project_id}/managed-agents/{agent_slug}/memory`. Select a folder with `directory=agent`, or `directory=user` with `tenantId` and `userId`, plus `environment` (`published` or `draft`).
9. Python SDK: `client.memory.list_files`, `read_file`, `write_file`, `move_file`, `delete_file`, `list_versions`, `rollback`, `forget`, `get_forget`, `list_forgets`, `remember`, `dream`, `get_dream`. CLI: `sikaru agent memory <operation>`.

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

| Folder            | Who it belongs to                                       | Who 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](/build/personal-channels);
* 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`:

```markdown
---
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/.
```

| Field     | Default | Effect                                        |
| --------- | ------- | --------------------------------------------- |
| `enabled` | `true`  | `false` turns memory off.                     |
| `policy`  | `allow` | `deny` turns memory off.                      |
| `shared`  | `true`  | Mount the shared `memories/agent/` folder.    |
| `user`    | `true`  | Mount 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.

| Refusal     | When                                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `read_only` | A conversation tries to change `memories/agent/`.                                                     |
| `limit`     | The folder would go over its file or size limit. The agent is told to consolidate.                    |
| `conflict`  | Another conversation changed the same files since this one read them. The agent re-reads and retries. |
| `forgotten` | The change contains text the user asked to forget.                                                    |
| `private`   | A dream tried to add personal details to the shared folder.                                           |
| `revoked`   | Memory was turned off, or the run's access narrowed, after the run started.                           |

| Folder            | Files | Total size |
| ----------------- | ----- | ---------- |
| `memories/user/`  | 200   | 2 MiB      |
| `memories/agent/` | 500   | 4 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.

| Status          | Meaning                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------ |
| `pending`       | The forget is running. The text stays blocked.                                             |
| `complete`      | The text was removed.                                                                      |
| `nothing_found` | The text was not in memory.                                                                |
| `failed`        | Removal did not finish after several attempts. The text stays blocked. Ask again to retry. |
| `reversed`      | The 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:

| Setting                  | Default                       | Effect                                           |
| ------------------------ | ----------------------------- | ------------------------------------------------ |
| `memoryDreamAuto`        | `true`                        | Turns automatic dreaming on or off.              |
| `memoryDreamIdleSeconds` | `900` (null uses the default) | Idle seconds before a dream, from 60 to 604,800. |

```sh
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 status | Meaning                                                                           |
| ------------ | --------------------------------------------------------------------------------- |
| `requested`  | Waiting to start.                                                                 |
| `running`    | In progress.                                                                      |
| `complete`   | Finished.                                                                         |
| `failed`     | Did not finish. The next dream reads the same conversations again.                |
| `cancelled`  | A forget arrived while it ran. The next dream reads the same conversations again. |
| `disabled`   | Memory is off for the agent.                                                      |

> **Note**
>
> 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`.

```sh
# 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.

```sh
# 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`:

```python
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

| Action                                                    | Permission                               |
| --------------------------------------------------------- | ---------------------------------------- |
| Read the shared folder                                    | `harness:read` or `managed_agents:write` |
| Change the shared folder, or read or change a user folder | `managed_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

#### [Author and publish](/build/agents-and-releases)

Write the agent document that turns memory on.

#### [Personal channels](/build/personal-channels)

Give each person their own memory on a personal agent.