Skip to main content
POST
/
v3
/
memories
/
add
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"
  }'
{
  "message": "Memory processing has been queued for background execution",
  "status": "PENDING",
  "event_id": "2c4d1f44-4f7b-4b2f-9f6e-7b5b4f5a1234"
}

Documentation Index

Fetch the complete documentation index at: https://docs.mem0.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

HeaderRequiredDescription
Authorization: Token <MEM0_API_KEY>YesAPI key scoped to your workspace.
Accept: application/jsonYesEnsures 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. 
{
  "user_id": "alice",
  "messages": [
    { "role": "user", "content": "I moved to Austin last month." }
  ],
  "metadata": {
    "source": "onboarding_form"
  }
}

​
Common fields

FieldTypeRequiredDescription
messagesarrayYesConversation turns for Mem0 to extract memories from. Each object should include role and content.
user_idstringNo*Associates the memory with a user.
agent_idstringNo*Associates the memory with an agent.
run_idstringNo*Associates the memory with a run.
app_idstringNo*Associates the memory with an app.
metadataobjectOptionalCustom key/value metadata (e.g., {"topic": "preferences"}).
inferboolean (default true)OptionalSet 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. 
{
  "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.

​
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

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>