Add Memories
Add facts, messages, or metadata to a user memory store with async processing and event tracking via the V3 additive pipeline.
Endpoint
- Method:
POST - URL:
/v3/memories/add/ - Content-Type:
application/json
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, orrun_id) is required.
Response
The request is queued for background processing. The response contains anevent_id for tracking status.
GET /v1/event/{event_id}/. Status will be SUCCEEDED or FAILED once processing completes.expiration_date remain stored after they expire. Search and get-all hide them by default; pass show_expired: true to include them.expiration_date; TypeScript uses expirationDate.Body
Conversation messages to extract memories from.
Scope memories to this user.
Scope memories to this agent.
Scope memories to this session / run.
User-supplied metadata to attach to each extracted memory.
Optional expiration date in YYYY-MM-DD format. After this date, memories are hidden from search and get-all unless show_expired is true.
Project-level instructions that guide extraction for this call.
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.
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.
When false, stores each message verbatim without running the extraction LLM.
Scope memories to this app.
Mark stored memories as immutable, excluding them from future update/consolidation.
Free-text hint of what to include during extraction, e.g. "vehicles".
Free-text hint of what to exclude during extraction, e.g. "politics".
Enable graph memory extraction for this call.
Optional schema constraining structured extraction. Exact shape not fully characterized; observed only as null in captured traffic.
Response envelope version, e.g. "v1.1". Full set of accepted values not confirmed.
ID of a saved prompt profile to use for extraction.
Enable temporal reasoning during extraction.
IANA timezone used to interpret observation_datetime and observation_date, e.g. "UTC".
ISO 8601 datetime the conversation was observed.
Date the conversation was observed (YYYY-MM-DD).
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}/.
Only present when infer is false, where processing is synchronous.
PENDING, SUCCEEDED, FAILED Only present when infer is false, where processing is synchronous and memories are stored verbatim without extraction.