Skip to main content
POST
cURL
Extract and store memories from a conversation using the V3 additive pipeline. The endpoint uses single-pass ADD-only extraction: one LLM call, no UPDATE/DELETE. Memories accumulate over time; nothing is overwritten.

Endpoint

  • Method: POST
  • URL: /v3/memories/add/
  • Content-Type: application/json
Processing is asynchronous. The response returns an event_id you can poll via GET /v1/event/{event_id}/.

Required headers

Request body

Provide conversation messages for Mem0 to extract memories from. At least one entity ID (user_id, agent_id, app_id, or run_id) is required so the memory is scoped to a session. Entity IDs are accepted at the top level.

Common fields

* At least one entity ID (user_id, agent_id, app_id, or run_id) is required.
Need more details? See all request parameters below for complete field descriptions, types, and constraints.

Response

The request is queued for background processing. The response contains an event_id for tracking status.
Poll the event status via GET /v1/event/{event_id}/. Status will be SUCCEEDED or FAILED once processing completes.
Memories with expiration_date remain stored after they expire. Search and get-all hide them by default; pass show_expired: true to include them.
Python uses expiration_date; TypeScript uses expirationDate.

Body

application/json
messages
object[]
required

Conversation messages to extract memories from.

user_id
string

Scope memories to this user.

agent_id
string

Scope memories to this agent.

run_id
string

Scope memories to this session / run.

metadata
object

User-supplied metadata to attach to each extracted memory.

expiration_date
string<date> | null

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_instructions
string

Project-level instructions that guide extraction for this call.

agent_custom_instructions
string

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_categories
object[]

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.

infer
boolean
default:true

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

app_id
string

Scope memories to this app.

immutable
boolean
default:false

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

includes
string

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

excludes
string

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

enable_graph
boolean

Enable graph memory extraction for this call.

structured_data_schema
object | null

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

output_format
string | null

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

prompt_profile_id
string | null

ID of a saved prompt profile to use for extraction.

temporal_reasoning
boolean

Enable temporal reasoning during extraction.

timezone
string

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

observation_datetime
string<date-time>

ISO 8601 datetime the conversation was observed.

observation_date
string<date>

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

timestamp
integer

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}/.

message
string

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

status
enum<string>
Available options:
PENDING,
SUCCEEDED,
FAILED
event_id
string<uuid>
results
object[]

Only present when infer is false, where processing is synchronous and memories are stored verbatim without extraction.