{
  "openapi": "3.1.0",
  "info": {
    "title": "Mem0 Cloud",
    "description": "A hosted agent-memory API shaped like mem0's REST API (an alternative to running mem0 yourself): add conversations, search, list, get and delete memories. No vector database or LLM to run. Memories are private to the secret memory_key you send; kept 365 days.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://mem0-cloud.saastemly.com"
    }
  ],
  "paths": {
    "/v3/memories/add": {
      "post": {
        "operationId": "add_memory",
        "summary": "Store memories from a conversation, like mem0's add: an AI model extracts durable facts about the user from the messages (or, with infer=false, stores each message as is), embeds them and saves them privately under your memory_key (a secret string you generate; required).",
        "description": "Store memories from a conversation, like mem0's add: an AI model extracts durable facts about the user from the messages (or, with infer=false, stores each message as is), embeds them and saves them privately under your memory_key (a secret string you generate; required). Identical facts are stored once. Needs at least one of user_id, agent_id, app_id, run_id. Memories are kept for 365 days. Returns {event_id, status, results:[{id, memory, event: ADD|NONE}]}.\n\nPrice: $0.008 per call (x402, or prepaid credits with an API key).",
        "x-price-usd": 0.008,
        "responses": {
          "200": {
            "description": "The result",
            "content": {
              "application/json": {
                "example": {
                  "event_id": "2c4d1f44-4f7b-4b2f-9f6e-7b5b4f5a1234",
                  "status": "SUCCEEDED",
                  "results": [
                    {
                      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                      "memory": "User moved to San Francisco from New York.",
                      "event": "ADD",
                      "user_id": "alice"
                    },
                    {
                      "id": "9d1b7c2e-5f0a-4e3b-8c6d-1a2b3c4d5e6f",
                      "memory": "User prefers vegetarian food.",
                      "event": "ADD",
                      "user_id": "alice"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is not valid (nothing is charged)"
          },
          "402": {
            "description": "Payment required: the x402 terms are in the PAYMENT-REQUIRED header; or send an API key"
          }
        },
        "security": [
          {},
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "memory_key": {
                    "type": "string",
                    "description": "Your secret: a random string of 16-256 characters that you generate once and keep (also accepted as the X-Memory-Key header). Memories are stored and searched only under its hash, so nobody who lacks it can read them, whatever user_id they send. Lose it and the memories are unreachable."
                  },
                  "messages": {
                    "type": "array",
                    "description": "Conversation turns, each {role: user|assistant|system, content: string}; up to 6000 bytes as JSON. A plain string is also accepted (one user message).",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "description": "user, assistant or system"
                        },
                        "content": {
                          "type": "string",
                          "description": "The message text"
                        }
                      }
                    }
                  },
                  "user_id": {
                    "type": "string",
                    "description": "Entity: the user the memories are about (1-128 characters)"
                  },
                  "agent_id": {
                    "type": "string",
                    "description": "Entity: the agent the memories belong to (1-128 characters)"
                  },
                  "app_id": {
                    "type": "string",
                    "description": "Entity: the app (1-128 characters)"
                  },
                  "run_id": {
                    "type": "string",
                    "description": "Entity: the session or run (1-128 characters)"
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Custom key/value metadata stored with every memory (up to 2000 bytes as JSON)"
                  },
                  "infer": {
                    "type": "boolean",
                    "description": "Default true: extract facts with the model. false: store each message verbatim (up to 10 messages of 300 characters)"
                  },
                  "expiration_date": {
                    "type": "string",
                    "description": "Optional YYYY-MM-DD: the memory is hidden from search and listing after that day (unless show_expired is true)"
                  },
                  "custom_instructions": {
                    "type": "string",
                    "description": "Optional extra extraction instructions (with includes and excludes, up to 800 bytes together)"
                  },
                  "includes": {
                    "type": "string",
                    "description": "Optional: what to focus on when extracting"
                  },
                  "excludes": {
                    "type": "string",
                    "description": "Optional: what not to extract"
                  }
                },
                "required": [
                  "memory_key",
                  "messages"
                ]
              },
              "example": {
                "memory_key": "mk_7f3a9c1e5b2d48a6b0c4e9d1",
                "user_id": "alice",
                "messages": [
                  {
                    "role": "user",
                    "content": "I just moved to San Francisco from New York and I prefer vegetarian food."
                  },
                  {
                    "role": "assistant",
                    "content": "Got it, I'll remember that."
                  }
                ],
                "metadata": {
                  "source": "onboarding"
                }
              }
            }
          }
        }
      }
    },
    "/v3/memories/search": {
      "post": {
        "operationId": "search_memories",
        "summary": "Search your stored memories by meaning, like mem0's search: embeds the query and returns the closest memories with a relevance score from 0 to 1.",
        "description": "Search your stored memories by meaning, like mem0's search: embeds the query and returns the closest memories with a relevance score from 0 to 1. Only memories stored under the same memory_key (your secret string; required) are searched. filters must name at least one of user_id, agent_id, app_id, run_id. Returns {results:[{id, memory, score, metadata, ...}]}.\n\nPrice: $0.004 per call (x402, or prepaid credits with an API key).",
        "x-price-usd": 0.004,
        "responses": {
          "200": {
            "description": "The result",
            "content": {
              "application/json": {
                "example": {
                  "results": [
                    {
                      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                      "memory": "User moved to San Francisco from New York.",
                      "user_id": "alice",
                      "agent_id": null,
                      "app_id": null,
                      "run_id": null,
                      "metadata": {
                        "source": "onboarding"
                      },
                      "categories": [],
                      "created_at": "2026-10-03T09:00:00.000Z",
                      "updated_at": null,
                      "expiration_date": null,
                      "score": 0.82
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is not valid (nothing is charged)"
          },
          "402": {
            "description": "Payment required: the x402 terms are in the PAYMENT-REQUIRED header; or send an API key"
          }
        },
        "security": [
          {},
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "memory_key": {
                    "type": "string",
                    "description": "Your secret: a random string of 16-256 characters that you generate once and keep (also accepted as the X-Memory-Key header). Memories are stored and searched only under its hash, so nobody who lacks it can read them, whatever user_id they send. Lose it and the memories are unreachable."
                  },
                  "query": {
                    "type": "string",
                    "description": "What to look for, in natural language (up to 500 characters)"
                  },
                  "filters": {
                    "type": "object",
                    "description": "mem0 filters: at least one of user_id, agent_id, app_id, run_id, each a string, \"*\" or {\"in\": [up to 20 strings]}; AND lists of those. OR and NOT are not supported."
                  },
                  "top_k": {
                    "type": "integer",
                    "description": "How many memories to return, 1-100 (default 10)"
                  },
                  "threshold": {
                    "type": "number",
                    "description": "Minimum relevance score, 0-1 (default 0.1; 0 disables)"
                  },
                  "show_expired": {
                    "type": "boolean",
                    "description": "Include memories whose expiration_date has passed (default false)"
                  }
                },
                "required": [
                  "memory_key",
                  "query",
                  "filters"
                ]
              },
              "example": {
                "memory_key": "mk_7f3a9c1e5b2d48a6b0c4e9d1",
                "query": "where does the user live?",
                "filters": {
                  "user_id": "alice"
                },
                "top_k": 5
              }
            }
          }
        }
      }
    },
    "/v1/memories": {
      "get": {
        "operationId": "get_memories",
        "summary": "Read your stored memories, like mem0's get memory and get all memories.",
        "description": "Read your stored memories, like mem0's get memory and get all memories. With memory_id: returns that one memory (404 if it is not yours). Without it: returns a page {count, next, previous, results} of the memories matching user_id, agent_id, app_id or run_id (at least one; \"*\" matches any value), newest first. Requires your memory_key (a secret string you generate): a different key sees nothing.\n\nPrice: $0.002 per call (x402, or prepaid credits with an API key).",
        "x-price-usd": 0.002,
        "responses": {
          "200": {
            "description": "The result",
            "content": {
              "application/json": {
                "example": {
                  "count": 1,
                  "next": null,
                  "previous": null,
                  "results": [
                    {
                      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                      "memory": "User moved to San Francisco from New York.",
                      "user_id": "alice",
                      "agent_id": null,
                      "app_id": null,
                      "run_id": null,
                      "metadata": {
                        "source": "onboarding"
                      },
                      "categories": [],
                      "created_at": "2026-10-03T09:00:00.000Z",
                      "updated_at": null,
                      "expiration_date": null
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request is not valid (nothing is charged)"
          },
          "402": {
            "description": "Payment required: the x402 terms are in the PAYMENT-REQUIRED header; or send an API key"
          }
        },
        "security": [
          {},
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "memory_key",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Your secret: a random string of 16-256 characters that you generate once and keep (also accepted as the X-Memory-Key header). Memories are stored and searched only under its hash, so nobody who lacks it can read them, whatever user_id they send. Lose it and the memories are unreachable."
            }
          },
          {
            "name": "memory_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "UUID of one memory to fetch; leave out to list memories instead"
            }
          },
          {
            "name": "user_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Entity: the user the memories are about (1-128 characters)"
            }
          },
          {
            "name": "agent_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Entity: the agent the memories belong to (1-128 characters)"
            }
          },
          {
            "name": "app_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Entity: the app (1-128 characters)"
            }
          },
          {
            "name": "run_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Entity: the session or run (1-128 characters)"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "description": "Page number, from 1 (default 1)"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "description": "Memories per page, 1-100 (default 50)"
            }
          },
          {
            "name": "show_expired",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "description": "Include memories whose expiration_date has passed (default false)"
            }
          }
        ]
      },
      "delete": {
        "operationId": "delete_memories",
        "summary": "Delete your stored memories, like mem0's delete memory and delete all memories.",
        "description": "Delete your stored memories, like mem0's delete memory and delete all memories. With memory_id: deletes that one memory (404 if it is not yours). Without it: deletes up to 200 of your memories matching user_id, agent_id, app_id or run_id (at least one), and says if more remain. Requires your memory_key (a secret string you generate): other keys cannot delete your memories.\n\nPrice: $0.002 per call (x402, or prepaid credits with an API key).",
        "x-price-usd": 0.002,
        "responses": {
          "200": {
            "description": "The result",
            "content": {
              "application/json": {
                "example": {
                  "message": "Memories deleted.",
                  "event_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                  "deleted_count": 2,
                  "has_more": false
                }
              }
            }
          },
          "400": {
            "description": "The request is not valid (nothing is charged)"
          },
          "402": {
            "description": "Payment required: the x402 terms are in the PAYMENT-REQUIRED header; or send an API key"
          }
        },
        "security": [
          {},
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "memory_key": {
                    "type": "string",
                    "description": "Your secret: a random string of 16-256 characters that you generate once and keep (also accepted as the X-Memory-Key header). Memories are stored and searched only under its hash, so nobody who lacks it can read them, whatever user_id they send. Lose it and the memories are unreachable."
                  },
                  "memory_id": {
                    "type": "string",
                    "description": "UUID of one memory to delete; leave out to delete by entity instead"
                  },
                  "user_id": {
                    "type": "string",
                    "description": "Entity: the user the memories are about (1-128 characters)"
                  },
                  "agent_id": {
                    "type": "string",
                    "description": "Entity: the agent the memories belong to (1-128 characters)"
                  },
                  "app_id": {
                    "type": "string",
                    "description": "Entity: the app (1-128 characters)"
                  },
                  "run_id": {
                    "type": "string",
                    "description": "Entity: the session or run (1-128 characters)"
                  }
                },
                "required": [
                  "memory_key"
                ]
              },
              "example": {
                "memory_key": "mk_7f3a9c1e5b2d48a6b0c4e9d1",
                "user_id": "alice"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key with prepaid credits, from https://mem0-cloud.saastemly.com"
      }
    }
  },
  "x-mcp-server": "https://mem0-cloud.saastemly.com/mcp"
}