Sign in

v3

latestOpenAPI 3.0.1Apache 2.02026-08-065516357.9 KB
memories

Add memories.

post/v1/memories/

Request body

messagesobject[]

An array of message objects representing the content of the memory. Each message object typically contains 'role' and 'content' fields, where 'role' indicates the sender either 'user' or 'assistant' and 'content' contains the actual message text. This structure allows for the representation of conversations or multi-part memories.

agent_idstring nullable

The unique identifier of the agent associated with this memory.

user_idstring nullable

The unique identifier of the user associated with this memory.

app_idstring nullable

The unique identifier of the application associated with this memory.

run_idstring nullable

The unique identifier of the run associated with this memory.

metadataobject nullable

Additional metadata associated with the memory, which can be used to store any additional information or context about the memory. Best practice for incorporating additional information is through metadata (e.g. location, time, ids, etc.). During retrieval, you can either use these metadata alongside the query to fetch relevant memories or retrieve memories based on the query first and then refine the results using metadata during post-processing.

includesstring nullable

String to include the specific preferences in the memory.

excludesstring nullable

String to exclude the specific preferences in the memory.

inferboolean

Whether to infer the memories or directly store the messages.

output_formatstring nullable

Controls the response format structure. v1.0 (default) returns a direct array of memory objects: [{...}, {...}]. v1.1 returns an object with a 'results' key containing the array: {"results": [...]}.

custom_categoriesobject nullable

A list of categories with category name and its description.

custom_instructionsstring nullable

Defines project-specific guidelines for handling and organizing memories. When set at the project level, they apply to all new memories in that project.

agent_custom_instructionsstring nullable

Extraction instructions that apply only to agent-scoped memories. Used when agent_id is sent without user_id; when both are sent it governs the assistant-attributed memories while custom_instructions governs the rest. Falls back to custom_instructions when unset.

immutableboolean

Whether the memory is immutable.

async_modeboolean

Whether to add the memory completely asynchronously.

timestampinteger nullable

The timestamp of the memory. Format: Unix timestamp

expiration_datestring date nullable

The date when the memory will expire. Format: YYYY-MM-DD

org_idstring nullable

The unique identifier of the organization associated with this memory.

project_idstring nullable

The unique identifier of the project associated with this memory.

versionstring nullable

The version of the memory to use. The default version is v1, which is deprecated. We recommend using v2 for new applications.

Response

Memory processing has been queued for background (async) execution. The response reports queueing status, not the final memory content; poll GET /v1/event/{event_id}/ with the returned event_id to see the processed result. By default (or with version=v1 / output_format=v1.0) the response is a bare array. When both output_format=v1.1 and version=v2 are requested, the response is an object wrapping the same array under results.

OR

Example response

[
  {
    "message": "Memory processing has been queued for background execution",
    "status": "PENDING"
  }
]