---
title: Add Memories
description: "Add facts, messages, or metadata to a user memory store with async processing and event tracking via the V3 additive pipeline."
openapi: post /v3/memories/add/
---

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.

<CodeGroup>
```json Basic request
{
  "user_id": "alice",
  "messages": [
    { "role": "user", "content": "I moved to Austin last month." }
  ],
  "metadata": {
    "source": "onboarding_form"
  }
}
```
</CodeGroup>

### 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. |
| `expiration_date` | string | Optional | Date in `YYYY-MM-DD` format. The memory is visible through this date and hidden by default after it passes. |

> \* At least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`) is required.

<Tip>
  Need more details? See [all request parameters](#body-messages) below for complete field descriptions, types, and constraints.
</Tip>

## Response

The request is queued for background processing. The response contains an `event_id` for tracking status.

<CodeGroup>
```json 200 response
{
  "message": "Memory processing has been queued for background execution",
  "status": "PENDING",
  "event_id": "evt-uuid"
}
```

```json 400 response
{
  "error": "400 Bad Request",
  "details": {
    "message": "Invalid input data. Please refer to the memory creation documentation at https://docs.mem0.ai/platform/quickstart#4-1-create-memories for correct formatting and required fields."
  }
}
```
</CodeGroup>

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

<Info>
Memories with `expiration_date` remain stored after they expire. Search and get-all hide them by default; pass `show_expired: true` to include them.
</Info>

<Info>
Python uses `expiration_date`; TypeScript uses `expirationDate`.
</Info>