Add Memories

Add facts, messages, or metadata to a user memory store with async processing and event tracking via the V3 additive pipeline.

POST /v3/memories/add

cURL

cURL

curl -X POST https://api.mem0.ai/v3/memories/add/ \
  -H "Authorization: Token <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "I just moved to San Francisco from New York."},
      {"role": "assistant", "content": "Got it — I\u0027ll update your location."}
    ],
    "user_id": "alice"
  }'

200

{
  "message": "Memory processing has been queued for background execution",
  "status": "PENDING",
  "event_id": "2c4d1f44-4f7b-4b2f-9f6e-7b5b4f5a1234"
}

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

Header	Required	Description
Authorization: Token <MEM0_API_KEY>	Yes	API key scoped to your workspace.
Accept: application/json	Yes	Ensures a JSON response.

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.

Basic request

{
  "user_id": "alice",
  "messages": [
    { "role": "user", "content": "I moved to Austin last month." }
  ],
  "metadata": {
    "source": "onboarding_form"
  }
}

Common fields

Field	Type	Required	Description
messages	array	Yes	Conversation turns for Mem0 to extract memories from. Each object should include role and content.
user_id	string	No*	Associates the memory with a user.
agent_id	string	No*	Associates the memory with an agent.
run_id	string	No*	Associates the memory with a run.
app_id	string	No*	Associates the memory with an app.
metadata	object	Optional	Custom key/value metadata (e.g., {"topic": "preferences"}).
infer	boolean (default true)	Optional	Set to false to skip inference and store the provided text as-is.

* 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.

200 response

{
  "message": "Memory processing has been queued for background execution",
  "status": "PENDING",
  "event_id": "evt-uuid"
}

Poll the event status via GET /v1/event/{event_id}/. Status will be SUCCEEDED or FAILED once processing completes.

Body

application/json

messages · object[] · required

Conversation messages to extract memories from.

Show child attributes

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.

custom_instructions · string

Project-level instructions that guide extraction for this call.

infer · boolean · default: true

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

Response

200

application/json

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

message · string

status · enum<string>

Available options: PENDING, SUCCEEDED, FAILED

event_id · string<uuid>