openapi: 3.0.1 info: title: Mem0 API Docs agents memories API description: mem0.ai API Docs contact: email: support@mem0.ai license: name: Apache 2.0 version: v1 servers: - url: https://api.mem0.ai/ security: - ApiKeyAuth: [] tags: - name: memories paths: /v1/memories/: get: tags: - memories description: Get all memories. operationId: memories_list parameters: - name: user_id in: query schema: type: string description: Filter memories by user ID. - name: agent_id in: query schema: type: string description: Filter memories by agent ID. - name: app_id in: query schema: type: string description: Filter memories by app ID. - name: run_id in: query schema: type: string description: Filter memories by run ID. - name: metadata in: query schema: type: object description: Filter memories by metadata (JSON string). style: deepObject explode: true - name: categories in: query schema: type: array items: type: string description: Filter memories by categories. - name: org_id in: query schema: type: string description: Filter memories by organization ID. - name: project_id in: query schema: type: string description: Filter memories by project ID. - name: fields in: query schema: type: array items: type: string description: Filter memories by fields. - name: keywords in: query schema: type: string description: Filter memories by keywords. - name: page in: query schema: type: integer description: 'Page number for pagination. Default: 1.' - name: page_size in: query schema: type: integer description: 'Number of items per page. Default: 100.' - name: start_date in: query schema: type: string description: Filter memories by start date. - name: end_date in: query schema: type: string description: Filter memories by end date. responses: '200': description: Successfully retrieved memories. content: application/json: schema: type: array items: type: object properties: id: type: string memory: type: string input: type: array items: type: object properties: role: type: string content: type: string created_at: type: string format: date-time updated_at: type: string format: date-time owner: type: string immutable: type: boolean description: Whether the memory is immutable. title: Immutable default: false expiration_date: type: string format: date description: 'The date when the memory will expire. Format: YYYY-MM-DD.' title: Expiration date nullable: true default: null organization: type: string metadata: type: object required: - id - memory - created_at - updated_at - total_memories - owner - organization - type '400': description: Bad Request. content: application/json: schema: type: object properties: message: type: string example: 'One of the filters: app_id, user_id, agent_id, run_id is required!' x-code-samples: - lang: Python source: '# To use the Python SDK, install the package: # pip install mem0ai from mem0 import MemoryClient client = MemoryClient(api_key="your_api_key") # Retrieve memories for a specific user user_memories = client.get_all(filters={"user_id": ""}) print(user_memories)' - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\n// Retrieve memories for a specific user\nclient.getAll({ user_id: \"\" })\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: 'curl --location --request GET ''https://api.mem0.ai/v1/memories/'' \ --header ''Authorization: Token ''' - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v1/memories/\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v1/memories/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"GET\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.get(\"https://api.mem0.ai/v1/memories/\")\n .header(\"Authorization\", \"Token \")\n .asString();" post: tags: - memories description: Add memories. operationId: memories_create requestBody: content: application/json: schema: $ref: '#/components/schemas/MemoryInput' required: true responses: '200': description: Successful memory creation. content: application/json: schema: type: array items: type: object properties: id: type: string data: type: object properties: memory: type: string required: - memory event: type: string enum: - ADD - UPDATE - DELETE required: - id - data - event '400': description: Bad Request. 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. content: application/json: schema: type: object required: - error - details example: 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. x-code-samples: - lang: Python source: "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\n\nclient = MemoryClient(api_key=\"your_api_key\")\n\nmessages = [\n {\"role\": \"user\", \"content\": \"\"},\n {\"role\": \"assistant\", \"content\": \"\"}\n]\n\nclient.add(messages, user_id=\"\")" - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst messages = [\n { role: \"user\", content: \"Hi, I'm Alex. I'm a vegetarian and I'm allergic to nuts.\" },\n { role: \"assistant\", content: \"Hello Alex! I've noted that you're a vegetarian and have a nut allergy. I'll keep this in mind for any food-related recommendations or discussions.\" }\n];\n\nclient.add(messages, { user_id: \"\" })\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "curl --request POST \\\n --url https://api.mem0.ai/v1/memories/ \\\n --header 'Authorization: Token ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"messages\": [\n {}\n ],\n \"agent_id\": \"\",\n \"user_id\": \"\",\n \"app_id\": \"\",\n \"run_id\": \"\",\n \"metadata\": {},\n \"includes\": \"\",\n \"excludes\": \"\",\n \"infer\": true,\n \"custom_categories\": {}, \n \"org_id\": \"\",\n \"project_id\": \"\",\n \"version\": \"v2\"\n}'" - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v1/memories/\"\n\n\tpayload := strings.NewReader(\"{\n \\\"messages\\\": [\n {}\n ],\n \\\"agent_id\\\": \\\"\\\",\n \\\"user_id\\\": \\\"\\\",\n \\\"app_id\\\": \\\"\\\",\n \\\"run_id\\\": \\\"\\\",\n \\\"metadata\\\": {},\n \\\"includes\\\": \\\"\\\",\n \\\"excludes\\\": \\\"\\\",\n \\\"infer\\\": true,\n \\\"custom_categories\\\": {},\n \\\"org_id\\\": \\\"\\\",\n \\\"project_id\\\": \\\"\",\n \\\"version\\\": \"v2\"\n}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v1/memories/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => \"{\n \\\"messages\\\": [\n {}\n ],\n \\\"agent_id\\\": \\\"\\\",\n \\\"user_id\\\": \\\"\\\",\n \\\"app_id\\\": \\\"\\\",\n \\\"run_id\\\": \\\"\\\",\n \\\"metadata\\\": {},\n \\\"includes\\\": \\\"\\\",\n \\\"excludes\\\": \\\"\\\",\n \\\"infer\\\": true,\n \\\"custom_categories\\\": {}, \n \\\"org_id\\\": \\\"\\\",\n \\\"project_id\\\": \\\"\",\n \\\"version\\\": \"v2\"\n}\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \",\n \"Content-Type: application/json\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.post(\"https://api.mem0.ai/v1/memories/\")\n .header(\"Authorization\", \"Token \")\n .header(\"Content-Type\", \"application/json\")\n .body(\"{\n \\\"messages\\\": [\n {}\n ],\n \\\"agent_id\\\": \\\"\\\",\n \\\"user_id\\\": \\\"\\\",\n \\\"app_id\\\": \\\"\\\",\n \\\"run_id\\\": \\\"\\\",\n \\\"metadata\\\": {},\n \\\"includes\\\": \\\"\\\",\n \\\"excludes\\\": \\\"\\\",\n \\\"infer\\\": true,\n \\\"custom_categories\\\": {}, \n \\\"org_id\\\": \\\"\\\",\n \\\"project_id\\\": \\\"\",\n \\\"version\\\": \"v2\"\n}\")\n .asString();" x-codegen-request-body-name: data delete: tags: - memories description: Delete memories by filter. At least one filter is required — previously omitting all filters silently deleted everything; now it returns a validation error. operationId: memories_delete_all parameters: - name: user_id in: query schema: type: string description: Filter by user ID. Pass `*` to delete memories for all users. - name: agent_id in: query schema: type: string description: Filter by agent ID. Pass `*` to delete memories for all agents. - name: app_id in: query schema: type: string description: Filter by app ID. Pass `*` to delete memories for all apps. - name: run_id in: query schema: type: string description: Filter by run ID. Pass `*` to delete memories for all runs. - name: metadata in: query schema: type: object description: Filter memories by metadata (JSON string). style: deepObject explode: true - name: org_id in: query schema: type: string description: Filter memories by organization ID. - name: project_id in: query schema: type: string description: Filter memories by project ID. responses: '204': description: Successful deletion of memories. content: application/json: schema: type: object properties: message: type: string example: Memories deleted successfully! x-code-samples: - lang: Python source: '# To use the Python SDK, install the package: # pip install mem0ai from mem0 import MemoryClient client = MemoryClient(api_key="your_api_key") # Delete all memories for a specific user client.delete_all(user_id="") # Delete all memories for every user in the project (wildcard) client.delete_all(user_id="*") # Full project wipe — all four filters must be explicitly set to "*" client.delete_all(user_id="*", agent_id="*", app_id="*", run_id="*") # NOTE: Calling delete_all() with no filters raises a validation error. # At least one filter is required to prevent accidental data loss.' - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\n// Delete all memories for a specific user\nclient.deleteAll({ user_id: \"\" })\n .then(result => console.log(result))\n .catch(error => console.error(error));\n\n// Delete all memories for every user in the project (wildcard)\nclient.deleteAll({ user_id: \"*\" })\n .then(result => console.log(result))\n .catch(error => console.error(error));\n\n// Full project wipe — all four filters must be explicitly set to \"*\"\nclient.deleteAll({ user_id: \"*\", agent_id: \"*\", app_id: \"*\", run_id: \"*\" })\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "# Delete memories for a specific user\ncurl --request DELETE \\\n --url 'https://api.mem0.ai/v1/memories/?user_id=' \\\n --header 'Authorization: Token '\n\n# Delete memories for all users (wildcard)\ncurl --request DELETE \\\n --url 'https://api.mem0.ai/v1/memories/?user_id=*' \\\n --header 'Authorization: Token '\n\n# Full project wipe — all four filters must be set to *\ncurl --request DELETE \\\n --url 'https://api.mem0.ai/v1/memories/?user_id=*&agent_id=*&app_id=*&run_id=*' \\\n --header 'Authorization: Token '" - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v1/memories/\"\n\n\treq, _ := http.NewRequest(\"DELETE\", url, nil)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v1/memories/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"DELETE\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.delete(\"https://api.mem0.ai/v1/memories/\")\n .header(\"Authorization\", \"Token \")\n .asString();" x-codegen-request-body-name: data /v2/memories/: post: tags: - memories description: Get all memories. operationId: memories_list_v2 requestBody: content: application/json: schema: $ref: '#/components/schemas/MemoryGetInputV2' required: true responses: '200': description: Successfully retrieved memories. content: application/json: schema: type: array items: type: object properties: id: type: string memory: type: string created_at: type: string format: date-time updated_at: type: string format: date-time owner: type: string immutable: type: boolean description: Whether the memory is immutable. title: Immutable default: false expiration_date: type: string format: date description: 'The date when the memory will expire. Format: YYYY-MM-DD.' title: Expiration date nullable: true default: null organization: type: string metadata: type: object required: - id - memory - created_at - updated_at - total_memories - owner - organization - type '400': description: Bad Request. content: application/json: schema: type: object properties: message: type: string example: 'One of the filters: app_id, user_id, agent_id, run_id is required!' x-code-samples: - lang: Python source: "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Retrieve memories with filters\nmemories = client.get_all(\n filters={\n \"AND\": [\n {\n \"user_id\": \"alex\"\n },\n {\n \"created_at\": {\n \"gte\": \"2024-07-01\",\n \"lte\": \"2024-07-31\"\n }\n }\n ]\n }\n)\n\nprint(memories)" - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst filters = {\n AND: [\n { user_id: 'alex' },\n { created_at: { gte: '2024-07-01', lte: '2024-07-31' } }\n ]\n};\n\nclient.getAll({ filters })\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "curl -X POST 'https://api.mem0.ai/v2/memories/' \\\n-H 'Authorization: Token your-api-key' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"filters\": {\n \"AND\": [\n { \"user_id\": \"alex\" },\n { \"created_at\": { \"gte\": \"2024-07-01\", \"lte\": \"2024-07-31\" } }\n ]\n },\n \"org_id\": \"your-org-id\",\n \"project_id\": \"your-project-id\"\n}'" - lang: Go source: "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io/ioutil\"\n\t\"net/http\"\n)\n\nfunc main() {\n\turl := \"https://api.mem0.ai/v2/memories/\"\n\tfilters := map[string]interface{}{\n\t\t\"AND\": []map[string]interface{}{\n\t\t\t{\"user_id\": \"alex\"},\n\t\t\t{\"created_at\": map[string]string{\n\t\t\t\t\"gte\": \"2024-07-01\",\n\t\t\t\t\"lte\": \"2024-07-31\",\n\t\t\t}},\n\t\t},\n\t}\n\tpayload, _ := json.Marshal(map[string]interface{}{\"filters\": filters})\n\treq, _ := http.NewRequest(\"POST\", url, bytes.NewBuffer(payload))\n\treq.Header.Add(\"Authorization\", \"Token your-api-key\")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(string(body))\n}" - lang: PHP source: " [\n ['user_id' => 'alex'],\n ['created_at' => ['gte' => '2024-07-01', 'lte' => '2024-07-31']]\n ]\n];\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"https://api.mem0.ai/v2/memories/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => json_encode(['filters' => $filters]),\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token your-api-key\",\n \"Content-Type: application/json\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "import com.konghq.unirest.http.HttpResponse;\nimport com.konghq.unirest.http.Unirest;\nimport org.json.JSONObject;\n\nJSONObject filters = new JSONObject()\n .put(\"AND\", new JSONArray()\n .put(new JSONObject().put(\"user_id\", \"alex\"))\n .put(new JSONObject().put(\"created_at\", new JSONObject()\n .put(\"gte\", \"2024-07-01\")\n .put(\"lte\", \"2024-07-31\")\n ))\n );\n\nHttpResponse response = Unirest.post(\"https://api.mem0.ai/v2/memories/\")\n .header(\"Authorization\", \"Token your-api-key\")\n .header(\"Content-Type\", \"application/json\")\n .body(new JSONObject().put(\"filters\", filters).toString())\n .asString();\n\nSystem.out.println(response.getBody());" /v1/memories/events/: get: tags: - memories operationId: memories_events_list responses: '200': description: Successfully retrieved memory events. content: {} /v1/memories/search/: post: tags: - memories description: Perform a semantic search on memories. operationId: memories_search_create requestBody: content: application/json: schema: $ref: '#/components/schemas/MemorySearchInput' required: true responses: '200': description: Successfully retrieved search results. content: application/json: schema: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier for the memory. memory: type: string description: The content of the memory user_id: type: string description: The identifier of the user associated with this memory metadata: type: object nullable: true description: Additional metadata associated with the memory categories: type: array items: type: string description: Categories associated with the memory immutable: type: boolean description: Whether the memory is immutable. title: Immutable default: false expiration_date: type: string format: date description: 'The date when the memory will expire. Format: YYYY-MM-DD.' title: Expiration date nullable: true default: null created_at: type: string format: date-time description: The timestamp when the memory was created. updated_at: type: string format: date-time description: The timestamp when the memory was last updated. required: - id - memory - user_id - created_at - updated_at '400': description: Bad Request. content: application/json: schema: type: object properties: message: type: string example: 'At least one of the filters: agent_id, user_id, app_id, run_id is required!' x-code-samples: - lang: Python source: '# To use the Python SDK, install the package: # pip install mem0ai from mem0 import MemoryClient client = MemoryClient(api_key="your_api_key") query = "Your search query here" results = client.search(query, filters={"user_id": ""}) print(results)' - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst query = \"Your search query here\";\n\nclient.search(query, { user_id: \"\" })\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "curl --request POST \\\n --url https://api.mem0.ai/v1/memories/search/ \\\n --header 'Authorization: Token ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"query\": \"\",\n \"agent_id\": \"\",\n \"user_id\": \"\",\n \"app_id\": \"\",\n \"run_id\": \"\",\n \"metadata\": {},\n \"top_k\": 123,\n \"fields\": [\n \"\"\n ],\n \"rerank\": true,\n \"org_id\": \"\",\n \"project_id\": \"\"\n}'" - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v1/memories/\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v1/memories/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"GET\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.get(\"https://api.mem0.ai/v1/memories/\")\n .header(\"Authorization\", \"Token \")\n .asString();" x-codegen-request-body-name: data /v2/memories/search/: post: tags: - memories description: Search memories based on a query and filters. operationId: memories_search_v2 requestBody: content: application/json: schema: $ref: '#/components/schemas/MemorySearchInputV2' required: true responses: '200': description: Successfully retrieved search results. content: application/json: schema: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier for the memory. memory: type: string description: The content of the memory user_id: type: string description: The identifier of the user associated with this memory metadata: type: object nullable: true description: Additional metadata associated with the memory categories: type: array items: type: string description: Categories associated with the memory immutable: type: boolean description: Whether the memory is immutable. title: Immutable default: false expiration_date: type: string format: date description: 'The date when the memory will expire. Format: YYYY-MM-DD.' title: Expiration date nullable: true default: null created_at: type: string format: date-time description: The timestamp when the memory was created. updated_at: type: string format: date-time description: The timestamp when the memory was last updated. required: - id - memory - user_id - created_at - updated_at x-code-samples: - lang: Python source: "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\nquery = \"What do you know about me?\"\nfilters = {\n \"OR\":[\n {\n \"user_id\":\"alex\"\n },\n {\n \"agent_id\":{\n \"in\":[\n \"travel-assistant\",\n \"customer-support\"\n ]\n }\n }\n ]\n}\nclient.search(query, filters=filters)" - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst query = \"What do you know about me?\";\nconst filters = {\n OR: [\n { user_id: \"alex\" },\n { agent_id: { in: [\"travel-assistant\", \"customer-support\"] } }\n ]\n};\n\nclient.search(query, { filters })\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "curl --request POST \\\n --url https://api.mem0.ai/v2/memories/search/ \\\n --header 'Authorization: Token ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"query\": \"\",\n \"filters\": {},\n \"top_k\": 123,\n \"fields\": [\n \"\"\n ],\n \"rerank\": true,\n \"org_id\": \"\",\n \"project_id\": \"\"\n}'" - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v2/memories/search/\"\n\n\tpayload := strings.NewReader(\"{\n \\\"query\\\": \\\"\\\",\n \\\"filters\\\": {},\n \\\"top_k\\\": 123,\n \\\"fields\\\": [\n \\\"\\\"\n ],\n \\\"rerank\\\": true,\n \\\"org_id\\\": \\\"\\\",\n \\\"project_id\\\": \\\"\\\"\n}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v2/memories/search/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => \"{\n \\\"query\\\": \\\"\\\",\n \\\"filters\\\": {},\n \\\"top_k\\\": 123,\n \\\"fields\\\": [\n \\\"\\\"\n ],\n \\\"rerank\\\": true,\n \\\"org_id\\\": \\\"\\\",\n \\\"project_id\\\": \\\"\\\"\n}\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \",\n \"Content-Type: application/json\"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.post(\"https://api.mem0.ai/v2/memories/search/\")\n .header(\"Authorization\", \"Token \")\n .header(\"Content-Type\", \"application/json\")\n .body(\"{\n \\\"query\\\": \\\"\\\",\n \\\"filters\\\": {},\n \\\"top_k\\\": 123,\n \\\"fields\\\": [\n \\\"\\\"\n ],\n \\\"rerank\\\": true,\n \\\"org_id\\\": \\\"\\\",\n \\\"project_id\\\": \\\"\\\"\n}\")\n .asString();" x-codegen-request-body-name: data /v3/memories/: post: tags: - memories summary: Get all memories (V3, paginated) description: List memories scoped by filters, paginated. Entity IDs **must** be passed inside the `filters` object — top-level `user_id` / `agent_id` / `run_id` are rejected with 400. `filters` supports the same operator set as V2 search (`AND`, `OR`, `NOT`, `in`, `gte`, `lte`, etc.). Response is a paginated envelope; pass `page` and `page_size` as query parameters to step through results. operationId: memories_list_v3 parameters: - in: query name: page schema: type: integer minimum: 1 default: 1 description: 1-indexed page number. - in: query name: page_size schema: type: integer minimum: 1 maximum: 200 default: 100 description: Results per page. requestBody: required: true content: application/json: schema: type: object required: - filters properties: filters: type: object description: Entity and metadata filters. Must include at least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`). additionalProperties: true example: filters: user_id: alice responses: '200': description: Paginated envelope of memories. content: application/json: schema: type: object properties: count: type: integer description: Total number of memories matching the filters. next: type: string format: uri nullable: true description: URL for the next page, or `null` if this is the last page. previous: type: string format: uri nullable: true description: URL for the previous page, or `null` if this is the first page. results: type: array items: type: object properties: id: type: string format: uuid description: Unique memory identifier. memory: type: string description: The extracted memory fact. score: type: number format: float minimum: 0 maximum: 1 description: Combined multi-signal relevance score in [0, 1] (search responses only). metadata: type: object additionalProperties: true description: User-supplied metadata attached to the memory. categories: type: array items: type: string created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - memory - created_at required: - count - next - previous - results example: count: 123 next: https://api.mem0.ai/v3/memories/?page=2&page_size=100 previous: null results: - id: mem-uuid memory: User moved to San Francisco from New York in January 2026 metadata: {} categories: - location created_at: '2026-01-15T10:30:00Z' updated_at: '2026-01-15T10:30:00Z' '400': description: Validation error — e.g. empty `filters` or no positively-scoped entity ID. '401': description: Unauthorized — missing or invalid API key. security: - tokenAuth: [] x-codeSamples: - lang: cURL source: "curl -X POST 'https://api.mem0.ai/v3/memories/?page=1&page_size=50' \\\n -H \"Authorization: Token \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"filters\": {\"user_id\": \"alice\"}}'" - lang: Python source: 'from mem0 import MemoryClient client = MemoryClient(api_key="your-api-key") page = client.get_all(filters={"user_id": "alice"}, page=1, page_size=50) # page == {"count": 123, "next": "...", "previous": None, "results": [...]} print(page["count"], len(page["results"]))' - lang: JavaScript source: "import MemoryClient from \"mem0ai\";\n\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst page = await client.getAll({\n filters: { userId: \"alice\" },\n page: 1,\n pageSize: 50,\n});\nconsole.log(page.count, page.results.length);" /v3/memories/add/: post: tags: - memories summary: Add memories (V3) description: 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. operationId: memories_add_v3 requestBody: required: true content: application/json: schema: type: object required: - messages properties: messages: type: array description: Conversation messages to extract memories from. items: type: object properties: role: type: string enum: - user - assistant - system content: type: string required: - role - content user_id: type: string description: Scope memories to this user. agent_id: type: string description: Scope memories to this agent. run_id: type: string description: Scope memories to this session / run. metadata: type: object additionalProperties: true description: User-supplied metadata to attach to each extracted memory. custom_instructions: type: string description: Project-level instructions that guide extraction for this call. infer: type: boolean default: true description: When `false`, stores each message verbatim without running the extraction LLM. example: messages: - role: user content: I just moved to San Francisco from New York. - role: assistant content: Got it — I'll update your location. user_id: alice responses: '200': description: Memory addition queued; returns an event identifier clients can poll via `GET /v1/event/{event_id}/`. content: application/json: schema: type: object properties: message: type: string status: type: string enum: - PENDING - SUCCEEDED - FAILED event_id: type: string format: uuid example: message: Memory processing has been queued for background execution status: PENDING event_id: 2c4d1f44-4f7b-4b2f-9f6e-7b5b4f5a1234 '400': description: Validation error — e.g. missing `messages` or no entity ID supplied. '401': description: Unauthorized — missing or invalid API key. security: - tokenAuth: [] x-codeSamples: - lang: cURL source: "curl -X POST https://api.mem0.ai/v3/memories/add/ \\\n -H \"Authorization: Token \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"messages\": [\n {\"role\": \"user\", \"content\": \"I just moved to San Francisco from New York.\"},\n {\"role\": \"assistant\", \"content\": \"Got it — I\\u0027ll update your location.\"}\n ],\n \"user_id\": \"alice\"\n }'" - lang: Python source: "from mem0 import MemoryClient\n\nclient = MemoryClient(api_key=\"your-api-key\")\n\nresult = client.add(\n messages=[\n {\"role\": \"user\", \"content\": \"I just moved to San Francisco from New York.\"},\n {\"role\": \"assistant\", \"content\": \"Got it — I'll update your location.\"}\n ],\n user_id=\"alice\",\n)\nprint(result)" - lang: JavaScript source: "import MemoryClient from \"mem0ai\";\n\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst result = await client.add(\n [\n { role: \"user\", content: \"I just moved to San Francisco from New York.\" },\n { role: \"assistant\", content: \"Got it — I'll update your location.\" },\n ],\n { userId: \"alice\" }\n);\nconsole.log(result);" /v3/memories/search/: post: tags: - memories summary: Search memories (V3) description: Relevance-ranked search across stored memories. V3 uses hybrid retrieval and can also apply temporal reasoning for time-aware queries. Entity IDs **must** be passed inside the `filters` object — top-level `user_id` / `agent_id` / `run_id` are rejected with 400. At least one entity ID is required. operationId: memories_search_v3 requestBody: required: true content: application/json: schema: type: object required: - query - filters properties: query: type: string minLength: 1 description: Natural-language search query. filters: type: object description: Entity and metadata filters. Must include at least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`). Supports `AND`, `OR`, `NOT`, and comparison operators (`in`, `gte`, `lte`, `gt`, `lt`, `contains`, `icontains`, `ne`). additionalProperties: true top_k: type: integer minimum: 1 maximum: 1000 default: 10 description: Number of results to return. threshold: type: number minimum: 0 maximum: 1 default: 0.1 description: Minimum semantic relevance score. Pass `0.0` to disable filtering. rerank: type: boolean default: false description: Apply the managed reranker for better ordering (adds latency). reference_date: oneOf: - type: integer - type: number - type: string nullable: true description: Optional query anchor time for relative temporal interpretation. Accepts Unix epoch, YYYY-MM-DD, or ISO datetime. example: query: where does the user live? filters: user_id: alice top_k: 10 responses: '200': description: Ranked search results. content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string format: uuid description: Unique memory identifier. memory: type: string description: The extracted memory fact. score: type: number format: float minimum: 0 maximum: 1 description: Combined multi-signal relevance score in [0, 1] (search responses only). metadata: type: object additionalProperties: true description: User-supplied metadata attached to the memory. categories: type: array items: type: string created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - memory - created_at required: - results example: results: - id: mem-uuid memory: User moved to San Francisco from New York in January 2026 score: 0.82 metadata: {} categories: - location created_at: '2026-01-15T10:30:00Z' updated_at: '2026-01-15T10:30:00Z' '400': description: Validation error — e.g. empty `query`, missing `filters`, or no positively-scoped entity ID. '401': description: Unauthorized — missing or invalid API key. security: - tokenAuth: [] x-codeSamples: - lang: cURL source: "curl -X POST https://api.mem0.ai/v3/memories/search/ \\\n -H \"Authorization: Token \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": \"where does the user live?\",\n \"filters\": {\"user_id\": \"alice\"},\n \"top_k\": 10\n }'" - lang: Python source: "from mem0 import MemoryClient\n\nclient = MemoryClient(api_key=\"your-api-key\")\n\nresults = client.search(\n \"where does the user live?\",\n filters={\"user_id\": \"alice\"},\n top_k=10,\n)\nfor r in results[\"results\"]:\n print(r[\"memory\"], r[\"score\"])" - lang: JavaScript source: "import MemoryClient from \"mem0ai\";\n\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst results = await client.search(\"where does the user live?\", {\n filters: { userId: \"alice\" },\n topK: 10,\n});\nfor (const r of results.results) {\n console.log(r.memory, r.score);\n}" /v1/memories/{entity_type}/{entity_id}/: parameters: - name: entity_type in: path required: true schema: type: string - name: entity_id in: path required: true schema: type: string get: tags: - memories operationId: memories_entity_read responses: '200': description: Successfully retrieved memories. content: {} /v1/memories/{memory_id}/: get: tags: - memories description: Get a memory. operationId: memories_read parameters: - name: memory_id in: path required: true schema: type: string format: uuid description: The unique identifier of the memory to retrieve. responses: '200': description: Successfully retrieved the memory. content: application/json: schema: type: object properties: id: type: string format: uuid description: Unique identifier for the memory. memory: type: string description: The content of the memory user_id: type: string description: Identifier of the user associated with this memory agent_id: type: string nullable: true description: The agent ID associated with the memory, if any app_id: type: string nullable: true description: The app ID associated with the memory, if any run_id: type: string nullable: true description: The run ID associated with the memory, if any hash: type: string description: Hash of the memory content metadata: type: object description: Additional metadata associated with the memory created_at: type: string format: date-time description: Timestamp of when the memory was created. updated_at: type: string format: date-time description: Timestamp of when the memory was last updated. '404': description: Memory not found. content: application/json: schema: type: object properties: error: type: string example: Memory not found! x-code-samples: - lang: Python source: '# To use the Python SDK, install the package: # pip install mem0ai from mem0 import MemoryClient client = MemoryClient(api_key="your_api_key") memory = client.get(memory_id="")' - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\n// Retrieve a specific memory\nclient.get(\"\")\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "curl --request GET \\\n --url https://api.mem0.ai/v1/memories/{memory_id}/ \\\n --header 'Authorization: Token '" - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v1/memories/{memory_id}/\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v1/memories/{memory_id}/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"GET\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.get(\"https://api.mem0.ai/v1/memories/{memory_id}/\")\n .header(\"Authorization\", \"Token \")\n .asString();" put: tags: - memories description: Get or Update or delete a memory. operationId: memories_update parameters: - name: memory_id in: path required: true schema: type: string format: uuid description: The unique identifier of the memory to retrieve. requestBody: content: application/json: schema: type: object properties: text: type: string description: The updated text content of the memory metadata: type: object description: Additional metadata associated with the memory responses: '200': description: Successfully updated memory. content: application/json: schema: type: object properties: id: type: string format: uuid description: The unique identifier of the updated memory. text: type: string description: The updated text content of the memory user_id: type: string nullable: true description: The user ID associated with the memory, if any agent_id: type: string nullable: true description: The agent ID associated with the memory, if any app_id: type: string nullable: true description: The app ID associated with the memory, if any run_id: type: string nullable: true description: The run ID associated with the memory, if any hash: type: string description: Hash of the memory content metadata: type: object description: Additional metadata associated with the memory created_at: type: string format: date-time description: Timestamp of when the memory was created. updated_at: type: string format: date-time description: Timestamp of when the memory was last updated. x-code-samples: - lang: Python source: "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Update a memory\nmemory_id = \"\"\nclient.update(\n memory_id=memory_id,\n text=\"Your updated memory message here\",\n metadata={\"category\": \"example\"}\n)" - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\n// Update a specific memory\nconst memory_id = \"\";\nclient.update(memory_id, { \n text: \"Your updated memory message here\",\n metadata: { category: \"example\" }\n})\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "curl --request PUT \\\n --url https://api.mem0.ai/v1/memories/{memory_id}/ \\\n --header 'Authorization: Token ' \\\n --header 'Content-Type: application/json' \\\n --data '{\"text\": \"Your updated memory text here\", \"metadata\": {\"category\": \"example\"}}'" - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v1/memories/{memory_id}/\"\n\n\tpayload := strings.NewReader(`{\n\t\"text\": \"Your updated memory text here\",\n\t\"metadata\": {\n\t\t\"category\": \"example\"\n\t}\n}`)\n\n\treq, _ := http.NewRequest(\"PUT\", url, payload)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v1/memories/{memory_id}/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"PUT\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \",\n \"Content-Type: application/json\"\n ],\n CURLOPT_POSTFIELDS => json_encode([\n \"text\" => \"Your updated memory text here\",\n \"metadata\" => [\"category\" => \"example\"]\n ])\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.put(\"https://api.mem0.ai/v1/memories/{memory_id}/\")\n .header(\"Authorization\", \"Token \")\n .header(\"Content-Type\", \"application/json\")\n .body(\"{\\\"text\\\": \\\"Your updated memory text here\\\", \\\"metadata\\\": {\\\"category\\\": \\\"example\\\"}}\")\n .asString();" x-codegen-request-body-name: data delete: tags: - memories description: Get or Update or delete a memory. operationId: memories_delete parameters: - name: memory_id in: path required: true schema: type: string format: uuid description: The unique identifier of the memory to retrieve. responses: '204': description: Successful deletion of memory. content: application/json: schema: type: object properties: message: type: string example: Memory deleted successfully! x-code-samples: - lang: Python source: '# To use the Python SDK, install the package: # pip install mem0ai from mem0 import MemoryClient client = MemoryClient(api_key="your_api_key") memory_id = "" client.delete(memory_id=memory_id)' - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\n// Delete a specific memory\nclient.delete(\"\")\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "curl --request DELETE \\\n --url https://api.mem0.ai/v1/memories/{memory_id}/ \\\n --header 'Authorization: Token '" - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v1/memories/{memory_id}/\"\n\n\treq, _ := http.NewRequest(\"DELETE\", url, nil)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v1/memories/{memory_id}/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"DELETE\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.delete(\"https://api.mem0.ai/v1/memories/{memory_id}/\")\n .header(\"Authorization\", \"Token \")\n .asString();" /v1/memories/{memory_id}/history/: get: tags: - memories description: Retrieve the history of a memory. operationId: memories_history_list parameters: - name: memory_id in: path required: true schema: type: string format: uuid description: The unique identifier of the memory to retrieve. responses: '200': description: Successfully retrieved the memory history. content: application/json: schema: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier for the history entry. memory_id: type: string format: uuid description: Unique identifier of the associated memory. input: type: array items: type: object properties: role: type: string enum: - user - assistant description: The role of the speaker in the conversation content: type: string description: The content of the message required: - role - content description: The conversation input that led to this memory change old_memory: type: string nullable: true description: The previous state of the memory, if applicable new_memory: type: string description: The new or updated state of the memory user_id: type: string description: The identifier of the user associated with this memory event: type: string enum: - ADD - UPDATE - DELETE description: The type of event that occurred metadata: type: object nullable: true description: Additional metadata associated with the memory change created_at: type: string format: date-time description: The timestamp when this history entry was created. updated_at: type: string format: date-time description: The timestamp when this history entry was last updated. required: - id - memory_id - input - new_memory - user_id - event - created_at - updated_at x-code-samples: - lang: Python source: '# To use the Python SDK, install the package: # pip install mem0ai from mem0 import MemoryClient client = MemoryClient(api_key="your_api_key") # Add some message to create history messages = [{"role": "user", "content": ""}] client.add(messages, user_id="") # Add second message to update history messages.append({"role": "user", "content": ""}) client.add(messages, user_id="") # Get history of how memory changed over time memory_id = "" history = client.history(memory_id)' - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\n// Get history of how memory changed over time\nclient.history(\"\")\n .then(result => console.log(result))\n .catch(error => console.error(error));" - lang: cURL source: "curl --request GET \\\n --url https://api.mem0.ai/v1/memories/{memory_id}/history/ \\\n --header 'Authorization: Token '" - lang: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.mem0.ai/v1/memories/{memory_id}/history/\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"Authorization\", \"Token \")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}" - lang: PHP source: " \"https://api.mem0.ai/v1/memories/{memory_id}/history/\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => \"\",\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 30,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => \"GET\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Token \"\n ],\n]);\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n echo \"cURL Error #:\" . $err;\n} else {\n echo $response;\n}" - lang: Java source: "HttpResponse response = Unirest.get(\"https://api.mem0.ai/v1/memories/{memory_id}/history/\")\n .header(\"Authorization\", \"Token \")\n .asString();" /v1/batch/: put: tags: - memories description: Batch update multiple memories (up to 1000) in a single API call. operationId: memories_batch_update requestBody: content: application/json: schema: type: object properties: memories: type: array items: type: object required: - memory_id - text properties: memory_id: type: string format: uuid description: The unique identifier of the memory to update text: type: string description: The new text content for the memory maxItems: 1000 required: - memories required: true responses: '200': description: Successfully updated memories content: application/json: schema: type: object properties: message: type: string example: Successfully updated 2 memories '400': description: Bad Request. content: application/json: schema: type: object properties: error: type: string example: Maximum of 1000 memories can be updated in a single request x-code-samples: - lang: Python source: "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\nupdate_memories = [\n {\n \"memory_id\": \"285ed74b-6e05-4043-b16b-3abd5b533496\",\n \"text\": \"Watches football\"\n },\n {\n \"memory_id\": \"2c9bd859-d1b7-4d33-a6b8-94e0147c4f07\",\n \"text\": \"Likes to travel\"\n }\n]\n\nresponse = client.batch_update(update_memories)\nprint(response)" - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst updateMemories = [\n {\n memoryId: \"285ed74b-6e05-4043-b16b-3abd5b533496\",\n text: \"Watches football\"\n },\n {\n memoryId: \"2c9bd859-d1b7-4d33-a6b8-94e0147c4f07\",\n text: \"Likes to travel\"\n }\n];\n\nclient.batchUpdate(updateMemories)\n .then(response => console.log('Batch update response:', response))\n .catch(error => console.error(error));" - lang: cURL source: "curl -X PUT \"https://api.mem0.ai/v1/batch/\" \\\n -H \"Authorization: Token your-api-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"memories\": [\n {\n \"memory_id\": \"285ed74b-6e05-4043-b16b-3abd5b533496\",\n \"text\": \"Watches football\"\n },\n {\n \"memory_id\": \"2c9bd859-d1b7-4d33-a6b8-94e0147c4f07\",\n \"text\": \"Likes to travel\"\n }\n ]\n }'" delete: tags: - memories description: Batch delete multiple memories (up to 1000) in a single API call. operationId: memories_batch_delete requestBody: content: application/json: schema: type: object properties: memory_ids: type: array items: type: string format: uuid maxItems: 1000 description: Array of memory IDs to delete. required: - memory_ids required: true responses: '200': description: Successfully deleted memories content: application/json: schema: type: object properties: message: type: string example: Successfully deleted 2 memories '400': description: Bad Request. content: application/json: schema: type: object properties: error: type: string example: Maximum of 1000 memories can be deleted in a single request x-code-samples: - lang: Python source: "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\ndelete_memories = [\n {\"memory_id\": \"285ed74b-6e05-4043-b16b-3abd5b533496\"},\n {\"memory_id\": \"2c9bd859-d1b7-4d33-a6b8-94e0147c4f07\"}\n]\n\nresponse = client.batch_delete(delete_memories)\nprint(response)" - lang: JavaScript source: "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst deleteMemories = [\n { memory_id: \"285ed74b-6e05-4043-b16b-3abd5b533496\" },\n { memory_id: \"2c9bd859-d1b7-4d33-a6b8-94e0147c4f07\" }\n];\n\nclient.batchDelete(deleteMemories)\n .then(response => console.log('Batch delete response:', response))\n .catch(error => console.error(error));" - lang: cURL source: "curl -X DELETE \"https://api.mem0.ai/v1/batch/\" \\\n -H \"Authorization: Token your-api-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"memories\": [\n {\n \"memory_id\": \"285ed74b-6e05-4043-b16b-3abd5b533496\"\n },\n {\n \"memory_id\": \"2c9bd859-d1b7-4d33-a6b8-94e0147c4f07\"\n }\n ]\n }'" components: schemas: MemorySearchInput: required: - query type: object properties: query: title: Query minLength: 1 type: string description: The query to search for in the memory. agent_id: title: Agent id type: string nullable: true description: The agent ID associated with the memory. user_id: title: User id type: string nullable: true description: The user ID associated with the memory. app_id: title: App id type: string nullable: true description: The app ID associated with the memory. run_id: title: Run id type: string nullable: true description: The run ID associated with the memory. metadata: title: Metadata type: object properties: {} nullable: true description: Additional metadata associated with the memory. top_k: title: Top K type: integer default: 10 description: The number of top results to return. fields: title: Fields type: array items: type: string description: A list of field names to include in the response. If not provided, all fields will be returned. rerank: title: Rerank type: boolean default: false description: Whether to rerank the memories. keyword_search: title: Keyword search type: boolean default: false description: Whether to search for memories based on keywords. output_format: title: Output format type: string nullable: true default: v1.1 description: 'The search method supports two output formats: `v1.0` (default) and `v1.1`. We recommend using `v1.1` as `v1.0` will be deprecated soon.' org_id: title: Organization id type: string nullable: true description: The unique identifier of the organization associated with the memory. project_id: title: Project id type: string nullable: true description: The unique identifier of the project associated with the memory. filter_memories: title: Filter memories type: boolean default: false description: Whether to properly filter the memories according to the input. categories: title: Categories type: array items: type: string description: A list of categories to filter the memories by. only_metadata_based_search: title: Only metadata based search type: boolean default: false description: Whether to only search for memories based on metadata. MemoryInput: type: object properties: messages: description: An array of message objects representing the content of the memory. Each message object typically contains 'role' and 'content' fields, where 'role' indicates the sender either 'user' or 'assistant' and 'content' contains the actual message text. This structure allows for the representation of conversations or multi-part memories. type: array items: type: object additionalProperties: type: string nullable: true agent_id: description: The unique identifier of the agent associated with this memory. title: Agent id type: string nullable: true user_id: description: The unique identifier of the user associated with this memory. title: User id type: string nullable: true app_id: description: The unique identifier of the application associated with this memory. title: App id type: string nullable: true run_id: description: The unique identifier of the run associated with this memory. title: Run id type: string nullable: true metadata: description: Additional metadata associated with the memory, which can be used to store any additional information or context about the memory. Best practice for incorporating additional information is through metadata (e.g. location, time, ids, etc.). During retrieval, you can either use these metadata alongside the query to fetch relevant memories or retrieve memories based on the query first and then refine the results using metadata during post-processing. title: Metadata type: object properties: {} nullable: true includes: description: String to include the specific preferences in the memory. title: Includes minLength: 1 type: string nullable: true excludes: description: String to exclude the specific preferences in the memory. title: Excludes minLength: 1 type: string nullable: true infer: description: Whether to infer the memories or directly store the messages. title: Infer type: boolean default: true output_format: description: 'Controls the response format structure. `v1.0` (deprecated) returns a direct array of memory objects: `[{...}, {...}]`. `v1.1` (recommended) returns an object with a ''results'' key containing the array: `{"results": [...]}`. The `v1.0` format will be removed in future versions.' title: Output format type: string nullable: true default: v1.1 custom_categories: description: A list of categories with category name and its description. title: Custom categories type: object properties: {} nullable: true custom_instructions: description: Defines project-specific guidelines for handling and organizing memories. When set at the project level, they apply to all new memories in that project. title: Custom instructions type: string nullable: true immutable: description: Whether the memory is immutable. title: Immutable type: boolean default: false async_mode: description: Whether to add the memory completely asynchronously. title: Async mode type: boolean default: true timestamp: description: 'The timestamp of the memory. Format: Unix timestamp' title: Timestamp type: integer nullable: true expiration_date: description: 'The date when the memory will expire. Format: YYYY-MM-DD' title: Expiration date type: string format: date nullable: true org_id: description: The unique identifier of the organization associated with this memory. title: Organization id type: string nullable: true project_id: description: The unique identifier of the project associated with this memory. title: Project id type: string nullable: true version: description: The version of the memory to use. The default version is v1, which is deprecated. We recommend using v2 for new applications. title: Version type: string nullable: true MemoryGetInputV2: type: object required: - filters properties: filters: title: Filters type: object description: 'A dictionary of filters to apply to retrieve memories. Available fields are: user_id, agent_id, app_id, run_id, created_at, updated_at, categories, keywords. Supports logical operators (AND, OR) and comparison operators (in, gte, lte, gt, lt, ne, contains, icontains, *). For categories field, use ''contains'' for partial matching (e.g., {"categories": {"contains": "finance"}}) or ''in'' for exact matching (e.g., {"categories": {"in": ["personal_information"]}}).' properties: user_id: type: string agent_id: type: string app_id: type: string run_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time keywords: type: object properties: contains: type: string icontains: type: string categories: type: object properties: in: type: array items: type: string metadata: type: object additionalProperties: type: object properties: in: type: array gte: type: string lte: type: string gt: type: string lt: type: string ne: type: string contains: type: string icontains: type: string fields: title: Fields type: array items: type: string description: A list of field names to include in the response. If not provided, all fields will be returned. page: title: Page type: integer default: 1 description: 'Page number for pagination. Default: 1' page_size: title: Page Size type: integer default: 100 description: 'Number of items per page. Default: 100' org_id: title: Organization id type: string nullable: true description: The unique identifier of the organization associated with the memory. project_id: title: Project id type: string nullable: true description: The unique identifier of the project associated with the memory. MemorySearchInputV2: type: object required: - query - filters properties: query: title: Query type: string description: The query to search for in the memory. version: title: Version type: string default: v2 description: The version of the memory to use. This should always be v2. filters: title: Filters type: object description: 'A dictionary of filters to apply to the search. Available fields are: user_id, agent_id, app_id, run_id, created_at, updated_at, categories, keywords. Supports logical operators (AND, OR) and comparison operators (in, gte, lte, gt, lt, ne, contains, icontains). For categories field, use ''contains'' for partial matching (e.g., {"categories": {"contains": "finance"}}) or ''in'' for exact matching (e.g., {"categories": {"in": ["personal_information"]}}).' properties: user_id: type: string agent_id: type: string app_id: type: string run_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time keywords: type: object properties: contains: type: string icontains: type: string categories: type: object properties: in: type: array items: type: string metadata: type: object additionalProperties: type: object properties: in: type: array gte: type: string lte: type: string gt: type: string lt: type: string ne: type: string contains: type: string icontains: type: string top_k: title: Top K type: integer default: 10 description: The number of top results to return. fields: title: Fields type: array items: type: string description: A list of field names to include in the response. If not provided, all fields will be returned. rerank: title: Rerank type: boolean default: false description: Whether to rerank the memories. keyword_search: title: Keyword search type: boolean default: false description: Whether to search for memories based on keywords. filter_memories: title: Filter memories type: boolean default: false description: Whether to filter the memories. threshold: title: Threshold type: number default: 0.3 description: The minimum similarity threshold for returned results. org_id: title: Organization id type: string nullable: true description: The unique identifier of the organization associated with the memory. project_id: title: Project id type: string nullable: true description: The unique identifier of the project associated with the memory. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'API key authentication. Prefix your Mem0 API key with ''Token ''. Example: ''Token your_api_key''' x-original-swagger-version: '2.0'