# Memory



**Memory** is a personal, actor-and-organization-scoped store of durable facts.
Records follow the same user across every session and survive VM and session
lifetime, independently of any one agent. Model access uses the same policy as
the HTTP API — there is no separate, more permissive write path.

<Callout title="Personal scope only">
  This release covers personal records only. Records are not shared with other
  agents or other users, and there's no per-agent or per-project scope yet.
</Callout>

## Records [#records]

| Field                       | Description                                                                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                        | Server-assigned, immutable.                                                                                                                                  |
| `scope`                     | Always `personal` in this release.                                                                                                                           |
| `body`                      | The remembered text, up to 4096 UTF-8 bytes.                                                                                                                 |
| `category`                  | `fact` (default) or `preference`.                                                                                                                            |
| `revision`                  | Bumps on every edit; required on `PATCH`/`DELETE` to prevent lost updates.                                                                                   |
| `source`                    | `user_management` (written via Memory settings) or `user_request` (written by the model from a chat turn, with the originating `session_id` and `event_id`). |
| `created_at` / `updated_at` | Timestamps.                                                                                                                                                  |

## HTTP API [#http-api]

| Method   | Path                  | Description                                                                                       |
| -------- | --------------------- | ------------------------------------------------------------------------------------------------- |
| `GET`    | `/v1/memories`        | List memories, newest-`after`-cursor paginated (`?after=`, `?limit=`, default page size 50).      |
| `POST`   | `/v1/memories`        | Create a memory (`body`, optional `category`, required `idempotency_key`). `201` with the record. |
| `GET`    | `/v1/memories/{id}`   | Get a memory.                                                                                     |
| `PATCH`  | `/v1/memories/{id}`   | Edit a memory's `body` (`{ "body", "revision" }`). `409` on a stale `revision`.                   |
| `DELETE` | `/v1/memories/{id}`   | Forget a memory. Requires `?revision=`; `409` on a stale value.                                   |
| `GET`    | `/v1/memory-settings` | Get the actor's memory settings.                                                                  |
| `PATCH`  | `/v1/memory-settings` | Update memory settings (`{ "use_memories": bool }`).                                              |

All endpoints require a Bearer JWT (see [API reference](/docs/agents/api-reference#authentication))
and accept an optional `?organization_id=` to select the active organization.
Every response carries `Cache-Control: private, no-store`.

```bash
curl https://agents.clusterbase.dev/v1/memories \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Prefers dark mode", "category": "preference", "idempotency_key": "settings-2024-06-01" }'
```

`idempotency_key` is caller-chosen and scoped to the actor/organization — retry
a `POST` with the same key instead of risking a duplicate on a dropped response.

## Memory settings [#memory-settings]

`use_memories` (default `true`) governs whether the model can recall or write
memories on a turn. Turning it off leaves the HTTP management endpoints
available — a user can still list, edit, and forget records through
`/v1/memories` while model access is paused.

## Chat behavior [#chat-behavior]

Runtime sessions that support memory add five tools: `memory_search`,
`memory_get`, `memory_remember`, `memory_update`, and `memory_forget`. Reads
return references only — the current, authorized body is supplied in fresh
context on the model's next step, so an edit or a forget takes effect before
that content is used again.

Writes require the user's exact wording in the same turn:

* `Remember <body>`, `Remember that <body>`, `Remember: <body>`, or
  `/remember <body>` — case-insensitive, and the common misspelling `remeber`
  is also accepted.
* `Update memory <id>: <body>`.
* `Forget memory <id>` or `Forget: <exact body>`.

The saved body must match the user's text exactly; a model cannot infer a fact
from the surrounding conversation or act on provenance/authorization claims
found in recalled content. Anything else directs the user to Memory settings
to make the change by hand. Common credential-shaped text (API keys, tokens,
passwords) is rejected as a memory body.

Guest and stateless chat sessions have no personal-memory access — recall and
the memory tools are only available on durable sessions.

## Next steps [#next-steps]

* **[API reference](/docs/agents/api-reference#memory)** — the full endpoint
  table alongside every other resource.
* **[Sessions & events](/docs/agents/sessions-and-events)** — how a durable
  session and its events relate to memory's `source.user_request`.