Memory API Fresh

Complete reference for all memory CRUD operations in the Mem0 API.

Base URL: https://api.mem0.ai

Authentication: All endpoints require Authorization: Token <MEM0_API_KEY> header.

Add Memories

POST /v1/memories/

Add facts, messages, or metadata to a user memory store with support for async processing and event tracking.

Request Body

Field	Type	Required	Description
`messages`	array	Yes	Conversation turns. Each object has `role` and `content`.
`user_id`	string	Conditional	Associates memory with a user.
`agent_id`	string	Optional	Unique identifier of associated agent.
`app_id`	string	Optional	Unique identifier of associated application.
`run_id`	string	Optional	Unique identifier of run.
`metadata`	object	Optional	Custom key/value metadata (e.g., `{"topic": "preferences"}`).
`infer`	boolean	Optional	Set to `false` to skip inference and store text as-is. Default: `true`.
`async_mode`	boolean	Optional	Controls async processing. Default: `true`.
`output_format`	string	Optional	`v1.1` wraps results in a `results` array. Default: `v1.1`.
`org_id`	string	Optional	Organization identifier.
`project_id`	string	Optional	Project identifier.
`includes`	string	Optional	String to include specific preferences in memory.
`excludes`	string	Optional	String to exclude specific preferences from memory.
`custom_categories`	object	Optional	Category names with descriptions.
`custom_instructions`	string	Optional	Project-specific guidelines for handling memories.
`immutable`	boolean	Optional	Whether memory is immutable. Default: `false`.
`timestamp`	integer	Optional	Unix timestamp for the memory.
`expiration_date`	string	Optional	Expiry date in `YYYY-MM-DD` format.
`enable_graph`	boolean	Optional	Enriches knowledge graph with entity nodes and relationships.
`version`	string	Optional	Memory version. Recommend `v2` for new applications.

Code Examples

PythonJavaScriptcURL

python

from mem0 import MemoryClient

client = MemoryClient(api_key="your_api_key", org_id="your_org_id",
                      project_id="your_project_id")

messages = [
    {"role": "user", "content": "Hi, I'm Alex. I'm a vegetarian and I'm allergic to nuts."},
    {"role": "assistant", "content": "Hello Alex! I've noted that you're a vegetarian and have a nut allergy."}
]

client.add(messages, user_id="alex", version="v2")

javascript

import MemoryClient from 'mem0ai';
const client = new MemoryClient({ apiKey: "your-api-key" });

const messages = [
  { role: "user", content: "Hi, I'm Alex. I'm a vegetarian and I'm allergic to nuts." },
  { role: "assistant", content: "Hello Alex! I've noted that you're a vegetarian and have a nut allergy." }
];

client.add(messages, { user_id: "alex", version: "v2" })
  .then(result => console.log(result))
  .catch(error => console.error(error));

bash

curl --request POST \
  --url https://api.mem0.ai/v1/memories/ \
  --header 'Authorization: Token <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {"role": "user", "content": "Hi, I am Alex. I am a vegetarian."}
  ],
  "user_id": "alex",
  "version": "v2"
}'

Response

json

[
  {
    "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
    "event": "ADD",
    "data": {
      "memory": "The user is a vegetarian and is allergic to nuts."
    }
  }
]

Events return ADD, UPDATE, or DELETE enum values.

Get Memories (List/Filter)

POST /v2/memories/

Retrieve memories with advanced filtering using logical operators (AND, OR, NOT) and comparison queries.

Request Body

Field	Type	Required	Description
`filters`	object	Yes	Filter conditions with logical/comparison operators.
`fields`	array	Optional	Specific fields to return.
`page`	integer	Optional	Page number. Default: `1`.
`page_size`	integer	Optional	Items per page. Default: `100`.
`org_id`	string	Optional	Organization identifier.
`project_id`	string	Optional	Project identifier.
`output_format`	string	Optional	`v1.1` includes graph memory with entity relationships.

Filter Fields

user_id, agent_id, app_id, run_id, created_at, updated_at, keywords, categories, metadata

Comparison Operators

Operator	Description
`in`	Matches specified values
`gte` / `lte`	Greater/less than or equal
`gt` / `lt`	Greater/less than
`ne`	Not equal
`icontains`	Case-insensitive containment
`contains`	Case-sensitive containment
`*`	Wildcard matching

Code Examples

PythonJavaScriptcURL

python

from mem0 import MemoryClient

client = MemoryClient(api_key="your_api_key", org_id="your_org_id",
                      project_id="your_project_id")

memories = client.get_all(
    filters={
        "AND": [
            {"user_id": "alex"},
            {"created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}}
        ]
    },
    version="v2"
)
print(memories)

javascript

import MemoryClient from 'mem0ai';
const client = new MemoryClient({ apiKey: "your-api-key" });

const filters = {
  AND: [
    { user_id: 'alex' },
    { created_at: { gte: '2024-07-01', lte: '2024-07-31' } }
  ]
};

client.getAll({ filters, api_version: 'v2' })
  .then(result => console.log(result))
  .catch(error => console.error(error));

bash

curl -X POST 'https://api.mem0.ai/v2/memories/' \
  -H 'Authorization: Token your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "AND": [
      { "user_id": "alex" },
      { "created_at": { "gte": "2024-07-01", "lte": "2024-07-31" } }
    ]
  }
}'

Response

json

{
  "results": [
    {
      "id": "uuid",
      "memory": "Alex is a vegetarian.",
      "created_at": "2024-07-15T10:30:00Z",
      "updated_at": "2024-07-15T10:30:00Z",
      "metadata": {},
      "immutable": false,
      "expiration_date": null
    }
  ],
  "total": 1
}

Search Memories

POST /v2/memories/search/

Search memories with semantic queries and advanced filtering.

Request Body

Field	Type	Required	Description
`query`	string	Yes	The search query.
`filters`	object	Yes	Filter conditions.
`version`	string	Optional	Memory version (use `v2`).
`top_k`	integer	Optional	Number of results. Default: `10`.
`fields`	array	Optional	Fields to include in response.
`rerank`	boolean	Optional	Rerank results. Default: `false`.
`keyword_search`	boolean	Optional	Enable keyword search. Default: `false`.
`filter_memories`	boolean	Optional	Apply filtering. Default: `false`.
`threshold`	number	Optional	Minimum similarity threshold. Default: `0.3`.
`org_id`	string	Optional	Organization identifier.
`project_id`	string	Optional	Project identifier.

PythonJavaScriptcURL

python

results = client.search(
    query="What food does Alex like?",
    filters={"user_id": "alex"},
    version="v2",
    top_k=5
)

javascript

const results = await client.search({
  query: "What food does Alex like?",
  filters: { user_id: "alex" },
  api_version: "v2",
  top_k: 5
});

bash

curl -X POST 'https://api.mem0.ai/v2/memories/search/' \
  -H 'Authorization: Token your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "What food does Alex like?",
  "filters": {"user_id": "alex"},
  "version": "v2",
  "top_k": 5
}'

Get Memory (Single)

GET /v1/memories/{memory_id}/

Retrieve a single memory by its unique ID.

Path Parameters

Parameter	Type	Required	Description
`memory_id`	string (UUID)	Yes	The unique memory identifier.

Response (200)

json

{
  "id": "uuid",
  "memory": "Alex is a vegetarian.",
  "user_id": "alex",
  "agent_id": null,
  "app_id": null,
  "run_id": null,
  "hash": "abc123",
  "metadata": {},
  "created_at": "2024-07-15T10:30:00Z",
  "updated_at": "2024-07-15T10:30:00Z"
}

Error (404)

json

{ "message": "Memory not found!" }

Update Memory

PUT /v1/memories/{memory_id}/

Update memory content and metadata.

Path Parameters

Parameter	Type	Required	Description
`memory_id`	string (UUID)	Yes	The memory to update.

Request Body

Field	Type	Description
`text`	string	Updated text content.
`metadata`	object	Updated metadata.

PythonJavaScriptcURL

python

client.update(memory_id="mem_id", data="Updated memory text")

javascript

await client.update("mem_id", { text: "Updated memory text" });

bash

curl --request PUT \
  --url https://api.mem0.ai/v1/memories/{memory_id}/ \
  --header 'Authorization: Token <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{"text": "Updated memory text"}'

Delete Memory (Single)

DELETE /v1/memories/{memory_id}/

Delete a single memory by ID.

Response (204)

json

{ "message": "Memory deleted successfully!" }

PythonJavaScriptcURL

python

client.delete(memory_id="mem_id")

javascript

await client.delete("mem_id");

bash

curl --request DELETE \
  --url https://api.mem0.ai/v1/memories/{memory_id}/ \
  --header 'Authorization: Token <api-key>'

Delete Memories (Filtered)

DELETE /v1/memories/

Delete memories by filter. At least one filter is required.

Query Parameters

Parameter	Type	Description
`user_id`	string	Filter by user ID (use `*` for all users).
`agent_id`	string	Filter by agent ID.
`app_id`	string	Filter by app ID.
`run_id`	string	Filter by run ID.
`metadata`	object	JSON string filtering by metadata.
`org_id`	string	Organization identifier.
`project_id`	string	Project identifier.

Response (204)

json

{ "message": "Memories deleted successfully!" }

Batch Update

PUT /v1/batch/

Update up to 1000 memories in a single request.

Request Body

json

{
  "memories": [
    { "memory_id": "uuid-1", "text": "Updated text 1" },
    { "memory_id": "uuid-2", "text": "Updated text 2" }
  ]
}

Response (200)

json

{ "message": "Successfully updated 2 memories" }

PythonJavaScript

python

client.batch_update([
    {"memory_id": "id-1", "text": "Updated text 1"},
    {"memory_id": "id-2", "text": "Updated text 2"}
])

javascript

await client.batchUpdate([
  { memoryId: "id-1", text: "Updated text 1" },
  { memoryId: "id-2", text: "Updated text 2" }
]);

Batch Delete

DELETE /v1/batch/

Delete up to 1000 memories in a single request.

Request Body

json

{
  "memory_ids": ["uuid-1", "uuid-2"]
}

Response (200)

json

{ "message": "Successfully deleted 2 memories" }

Memory History

GET /v1/memories/{memory_id}/history/

Retrieve the full change history of a specific memory.

Response

Returns an array of history entries:

json

[
  {
    "id": "uuid",
    "memory_id": "uuid",
    "input": [{"role": "user", "content": "..."}],
    "old_memory": null,
    "new_memory": "Alex is a vegetarian.",
    "user_id": "alex",
    "event": "ADD",
    "metadata": null,
    "created_at": "2024-07-15T10:30:00Z",
    "updated_at": "2024-07-15T10:30:00Z"
  }
]

Event types: ADD, UPDATE, DELETE.

Feedback

POST /v1/feedback/

Submit feedback for a memory to improve quality.

Request Body

Field	Type	Required	Description
`memory_id`	string	Yes	Memory to provide feedback for.
`feedback`	string	Optional	`POSITIVE`, `NEGATIVE`, or `VERY_NEGATIVE`.
`feedback_reason`	string	Optional	Reason for the feedback.

Response (200)

json

{
  "id": "uuid",
  "feedback": "POSITIVE",
  "feedback_reason": "Accurate memory"
}

Create Memory Export

POST /v1/exports/

Create a structured export of memories.

Request Body

Field	Type	Required	Description
`schema`	object	Yes	Schema definition for the export (Pydantic-style).
`filters`	object	Optional	Filter by `user_id`, `agent_id`, `app_id`, `run_id`.
`org_id`	string	Optional	Organization identifier.
`project_id`	string	Optional	Project identifier.

Response (201)

json

{
  "message": "Memory export request received...",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Get Memory Export

POST /v1/exports/get

Retrieve the latest structured memory export after submitting an export job.

Request Body

Field	Type	Description
`memory_export_id`	string	Unique export identifier.
`org_id`	string	Organization filter.
`project_id`	string	Project filter.
`filters`	object	Optional filters.

Memory API Fresh ​

Add Memories ​

Request Body ​

Code Examples ​

Response ​

Get Memories (List/Filter) ​

Request Body ​

Filter Fields ​

Comparison Operators ​

Code Examples ​

Response ​

Search Memories ​

Request Body ​

Get Memory (Single) ​

Path Parameters ​

Response (200) ​

Error (404) ​

Update Memory ​

Path Parameters ​

Request Body ​

Delete Memory (Single) ​

Response (204) ​

Delete Memories (Filtered) ​

Query Parameters ​

Response (204) ​

Batch Update ​

Request Body ​

Response (200) ​

Batch Delete ​

Request Body ​

Response (200) ​

Memory History ​

Response ​

Feedback ​

Request Body ​

Response (200) ​

Create Memory Export ​

Request Body ​

Response (201) ​

Get Memory Export ​

Request Body ​

Memory API Fresh

Add Memories

Request Body

Code Examples

Response

Get Memories (List/Filter)

Request Body

Filter Fields

Comparison Operators

Code Examples

Response

Search Memories

Request Body

Get Memory (Single)

Path Parameters

Response (200)

Error (404)

Update Memory

Path Parameters

Request Body

Delete Memory (Single)

Response (204)

Delete Memories (Filtered)

Query Parameters

Response (204)

Batch Update

Request Body

Response (200)

Batch Delete

Request Body

Response (200)

Memory History

Response

Feedback

Request Body

Response (200)

Create Memory Export

Request Body

Response (201)

Get Memory Export

Request Body