Memory
Durable personal facts that follow a user across sessions, with HTTP management and model tools for explicit remember/update/forget requests.
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.
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.
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
| 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)
and accept an optional ?organization_id= to select the active organization.
Every response carries Cache-Control: private, no-store.
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
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
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 misspellingremeberis also accepted.Update memory <id>: <body>.Forget memory <id>orForget: <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
- API reference — the full endpoint table alongside every other resource.
- Sessions & events — how a durable
session and its events relate to memory's
source.user_request.