Skip to main content
PATCH
Update a memory entry
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

PATCH /api/v2/memory/update changes a long-term entry’s summary or tags and answers { "id": "<memoryId>" }. The body must include id and layer: "longterm". Send an Idempotency-Key header to make a retry safe; see Memory write replay.

Errors

layer is not longterm, summary is not a string, or tags is not an array of at most 20 strings of at most 64 characters.
The memory belongs to a platform agent, whose memory is read-only.
No such memory, or its agent is outside the caller’s reach (an External App’s owner-scope chain; for an API key, neither memory permission at the agent’s home) or is a Personal Agent. An API key that holds memory:read but not memory:write at the agent’s home gets 403.
The memory is forgotten. Only POST /api/v2/memory/delete acts on a forgotten memory.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

memoryId
string
required

Body

application/json
layer
enum<string>
required

Must be longterm. Any other value, or an omitted layer, answers 400.

Available options:
longterm
summary
string
tags
string[]
Maximum array length: 20
Maximum string length: 64

Response

Memory entry updated

data
object
required
meta
object
required