Skip to main content
POST
Create 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

Appends one memory entry for an agent. The body’s layer picks the tier: channel stores a channel summary, longterm stores an embedded long-term entry.
The route requires permission 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’s layer and ignores any other field (an orgUnitId, an embedding or a companies list in the body has no effect):
  • layer: "channel": required agentId, channelId, summary, summaryTokenCount (a non-negative integer); optional maxSummaryTokens (a non-negative integer) and projectId.
  • layer: "longterm": required agentId, content (at most 8,192 bytes of UTF-8), memoryType (semantic or episodic), sourceType (session_eviction, session_close, or channel_eviction); optional sourceChannelId, sourceSessionId, summary, tags (at most 20 strings of at most 64 characters) and projectId.

Retries

Send an Idempotency-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: channelId for a channel memory, sourceChannelId for a long-term memory. A channel that doesn’t exist, or isn’t in a project, names no project.
An External App may write into a project in its owner-scope chain. An app owned by a factory, and a platform key, have no project in scope, so they can’t write a memory that names a project. A body that names no project isn’t checked.

Errors

The body is missing a required field for its 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.
An External App’s agentId isn’t in its owner-scope chain. This check runs before the project check.
An API key’s role grants don’t hold memory:write at the agent’s home org unit, or the agent has no home. This check runs before the project check.
The 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

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

Body

application/json
layer
string
required
Allowed value: "channel"
agentId
string
required
channelId
string
required
summary
string
required
summaryTokenCount
integer
required
Required range: x >= 0
maxSummaryTokens
integer
Required range: x >= 0
projectId
string

Response

Memory entry created. A channel-layer create for an agent and channel that already have an entry replaces its summary and answers that entry's id, also with 201.

data
object
required
meta
object
required