Create a memory entry
Create a memory entry. Requires permission memory:write.
v2 compatibility notes
Appends one memory entry for an agent. The body’slayer picks the tier: channel stores a channel summary, longterm stores an embedded long-term entry.
memory:write. A successful write answers 200 with { "data": { "id": "<memoryId>", "layer": "channel" | "longterm" } }. The entry’s org unit is always the authenticated caller’s.
A channel memory is one entry per agent and channel: a create for an existing pair replaces its summary and answers the same id.
Fields
The route reads only these fields of the body’slayer and ignores any other field (an orgUnitId, an embedding or a companies list in the body has no effect):
layer: "channel": requiredagentId,channelId,summary,summaryTokenCount(a non-negative integer); optionalmaxSummaryTokens(a non-negative integer) andprojectId.layer: "longterm": requiredagentId,content(at most 8,192 bytes of UTF-8),memoryType(semanticorepisodic),sourceType(session_eviction,session_close, orchannel_eviction); optionalsourceChannelId,sourceSessionId,summary,tags(at most 20 strings of at most 64 characters) andprojectId.
Retries
Send anIdempotency-Key header to make a retry safe. A repeat with the same key and body within 24 hours never writes twice: it returns the stored 200 with Idempotency-Replayed: true while you still hold memory:write and memory:read and may read and write the memory, and otherwise 403 for a missing permission or 409 idempotency_result_unavailable. See Memory write replay.
Project authority
A memory stored in a project is later promoted into that project’s knowledge scope, where the project’s readers see it. So the route checks every project the body names against the projects the caller may write knowledge into:- the
projectId, when present; - the project of the named channel:
channelIdfor a channel memory,sourceChannelIdfor a long-term memory. A channel that doesn’t exist, or isn’t in a project, names no project.
Errors
400 bad_request
400 bad_request
layer, names an unsupported layer (layer_not_supported), has long-term content over 8,192 bytes (content_too_large), has a documented field of the wrong type (Invalid <field>), or names a channelId, sourceChannelId, projectId or sourceSessionId that is not an id of its kind (Invalid <field>). The id check runs after the agent check below.403 forbidden: agentId not in caller's owner-scope chain
403 forbidden: agentId not in caller's owner-scope chain
agentId isn’t in its owner-scope chain. This check runs before the project check.403 permission_denied: agentId's home does not grant this credential memory:write
403 permission_denied: agentId's home does not grant this credential memory:write
memory:write at the agent’s home org unit, or the agent has no home. This check runs before the project check.403 forbidden: projectId or channel not in a project the caller may write
403 forbidden: projectId or channel not in a project the caller may write
projectId, or the project of the named channel, isn’t one the caller may write knowledge into. A platform key or a factory-owned app gets this answer for any body that names a project.Authorizations
Headers
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.
1 - 255
