Sign in

v3

latestOpenAPI 3.0.1Apache 2.02026-08-065516357.9 KB
memories

Add memories (V3)

Extract and store memories from a conversation using the V3 additive pipeline. Entity IDs (user_id / agent_id / run_id) are accepted at the top level. At least one entity ID is required so the memory is scoped to a session.

post/v3/memories/add/

Request body

user_idstring

Scope memories to this user.

agent_idstring

Scope memories to this agent.

run_idstring

Scope memories to this session / run.

metadataobject

User-supplied metadata to attach to each extracted memory.

expiration_datestring date nullable

Optional expiration date in YYYY-MM-DD format. After this date, memories are hidden from search and get-all unless show_expired is true.

custom_instructionsstring

Project-level instructions that guide extraction for this call.

agent_custom_instructionsstring

Extraction instructions for agent-scoped memories, overriding the project-level setting for this call. Applied when agent_id is sent without user_id; when both are sent it governs the assistant-attributed memories while custom_instructions governs the rest.

custom_categoriesobject[]

Category catalog for this call. Replaces the project-level list rather than merging with it. Omit to fall back to the project list, then the default catalog.

inferboolean

When false, stores each message verbatim without running the extraction LLM.

app_idstring

Scope memories to this app.

immutableboolean

Mark stored memories as immutable, excluding them from future update/consolidation.

includesstring

Free-text hint of what to include during extraction, e.g. "vehicles".

excludesstring

Free-text hint of what to exclude during extraction, e.g. "politics".

enable_graphboolean

Enable graph memory extraction for this call.

structured_data_schemaobject nullable

Optional schema constraining structured extraction. Exact shape not fully characterized; observed only as null in captured traffic.

output_formatstring nullable

Response envelope version, e.g. "v1.1". Full set of accepted values not confirmed.

prompt_profile_idstring nullable

ID of a saved prompt profile to use for extraction.

temporal_reasoningboolean

Enable temporal reasoning during extraction.

timezonestring

IANA timezone used to interpret observation_datetime and observation_date, e.g. "UTC".

observation_datetimestring date-time

ISO 8601 datetime the conversation was observed.

observation_datestring date

Date the conversation was observed (YYYY-MM-DD).

timestampinteger

Unix epoch seconds used to backdate created_at on the stored memories. Not echoed back in the event payload but confirmed applied.

Response

Memory addition queued; returns an event identifier clients can poll via GET /v1/event/{event_id}/.

messagestring

Only present when infer is false, where processing is synchronous.

status'PENDING' | 'SUCCEEDED' | 'FAILED'
event_idstring uuid

Example response

{
  "results": [
    {
      "event": "ADD"
    }
  ]
}