Mem0 Platform API Reference

REST API endpoints for the Mem0 Platform. Base URL: https://api.mem0.ai

All endpoints require: Authorization: Token <MEM0_API_KEY>

Endpoints

Note: v1/v2 endpoints still work (backward compatible).

Memory Object Structure

Search results additionally include score (relevance metric).

Scoping Identifiers

Memories can be scoped to different levels:

Critical: Combining user_id and agent_id in a single AND filter yields empty results. Entities are stored separately. Use OR logic or separate queries.

Processing Model

• Memories are processed asynchronously (v3 default)
• Add responses return queued ADD events only (v3 is ADD-only, no UPDATE/DELETE)
• Poll status via GET /v1/event/{event_id}/

Filter System

Filters use nested JSON with a logical operator at the root:

{
    "AND": [
        {"user_id": "alice"},
        {"categories": {"contains": "finance"}},
        {"created_at": {"gte": "2024-01-01"}}
    ]
}

Root must be AND, OR, or NOT. Simple shorthand {"user_id": "alice"} also works.

Supported Operators

Filterable Fields

Filter Constraints

1. Entity scope partitioning: user_id AND agent_id in one AND block yields empty results.
2. Metadata limitations: Only top-level keys. Only eq, contains, ne. No in or gt.
3. Operator syntax: Use gte, lt, ne. SQL-style (>=, !=) rejected.
4. Entity filter required for get-all: At least one of user_id, agent_id, app_id, or run_id.
5. Wildcard excludes null: * matches only non-null values.
6. Date format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Timezone-naive defaults to UTC.

Response Formats

Add Response (v3)

{
  "message": "Memory processing has been queued for background execution",
  "status": "PENDING",
  "event_id": "evt-uuid"
}

v3 is ADD-only. No UPDATE or DELETE events.

Search Response

{
  "results": [
    {
      "id": "ea925981-...",
      "memory": "Is a vegetarian and allergic to nuts.",
      "user_id": "user123",
      "categories": ["food", "health"],
      "score": 0.89,
      "created_at": "2024-07-26T10:29:36.630547-07:00"
    }
  ]
}

In v3, score is a combined multi-signal relevance score.

Get All Response (v3)

{
  "count": 123,
  "next": "https://api.mem0.ai/v3/memories/?page=2&page_size=50",
  "previous": null,
  "results": [...]
}

v3 returns paginated envelope. Use page and page_size query params.