---
title: "Add memories (V3)"
method: POST
path: "/v3/memories/add/"
tags: ["memories"]
---

# Add memories (V3)

`POST /v3/memories/add/`

Extract and store memories from a conversation using the V3 additive pipeline. Entity IDs (`user_id` / `agent_id` / `run_id`) are accepted at the top level. At least one entity ID is required so the memory is scoped to a session.

## Request body

- object
  - `messages` object[], required — Conversation messages to extract memories from.
    - `role` 'user' | 'assistant' | 'system', required
    - `content` string, required
  - `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, nullable — 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 — When `false`, stores each message verbatim without running the extraction LLM.
  - `app_id` string — Scope memories to this app.
  - `immutable` boolean — 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, nullable — Optional schema constraining structured extraction. Exact shape not fully characterized; observed only as null in captured traffic.
  - `output_format` string, nullable — Response envelope version, e.g. "v1.1". Full set of accepted values not confirmed.
  - `prompt_profile_id` string, nullable — 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 `200`

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

- object
  - `message` string — Only present when `infer` is `false`, where processing is synchronous.
  - `status` '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.
    - `id` string, uuid
    - `data` object
      - `memory` string
    - `event` string

## Other responses

- `400` — Validation error, e.g. missing `messages` or no entity ID supplied.
- `401` — Unauthorized: missing or invalid API key.

---

[API](https://skmtc.net/mem0/apis/mem0-api-docs.md) · [All operations](https://skmtc.net/mem0/apis/mem0-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mem0/mem0-api-docs/revisions/c86fe9831e7e/schema)