pinkpixel-dev/mem0-api

Mem0 API & SDK

Mem0 is a managed memory layer for LLM agents. It extracts facts from conversations, deduplicates, and exposes them via semantic search — giving agents persistent, cross-session context without you managing a vector DB.

Two products, one mental model:

• Mem0 Platform (managed, recommended) — hosted API + dashboard, sub-50ms retrieval
• Mem0 OSS (self-hosted) — run your own vector store, LLM, and embedder stack

Quick Product Routing

User imports `from mem0 import MemoryClient`      → Platform
User imports `from mem0 import Memory`             → OSS (Python)
User imports `import { Memory } from "mem0ai/oss"` → OSS (Node)
User imports `import MemoryClient from "mem0ai"`   → Platform (TS/JS)
No package installed yet                           → Recommend Platform first

---

Install

# Python
pip install mem0ai

# Node / TypeScript
npm install mem0ai

# CLI
pip install mem0-cli    # Python CLI
npm install -g @mem0/cli  # Node CLI

API Key: Get from app.mem0.ai/dashboard/api-keys

Auth header: Authorization: Token <YOUR_API_KEY>

---

Platform SDK — Core CRUD (TypeScript / Python)

TypeScript (primary for this project)

import MemoryClient from "mem0ai";

const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });

// ADD — async, returns event_id
const result = await client.add(
  [{ role: "user", content: "I moved to Austin last month." }],
  { user_id: "alice" }
);
// result.event_id → poll GET /v1/event/{id}/ to confirm SUCCEEDED

// SEARCH — V3 hybrid (semantic + BM25 + entity). Filters REQUIRED in V3.
const hits = await client.search("Where does Alice live?", {
  filters: { user_id: "alice" },
  top_k: 10,
});

// GET ALL
const all = await client.getAll({ user_id: "alice" });

// GET ONE
const mem = await client.get("<memory_id>");

// UPDATE
await client.update("<memory_id>", { text: "Alice lives in Austin, TX" });

// DELETE ONE
await client.delete("<memory_id>");

// DELETE ALL for a scope
await client.deleteAll({ user_id: "alice" });

Python

from mem0 import MemoryClient

client = MemoryClient(api_key="your-api-key")

# ADD
result = client.add(
    [{"role": "user", "content": "I love hiking on weekends"}],
    user_id="alice",
)

# SEARCH (V3 — filters required)
results = client.search(
    "What are Alice's hobbies?",
    filters={"user_id": "alice"},
    top_k=10,
)

# CRUD mirrors TypeScript API
client.get_all(user_id="alice")
client.get("<memory_id>")
client.update("<memory_id>", data="Alice loves mountain hiking")
client.delete("<memory_id>")
client.delete_all(user_id="alice")

---

REST API Quick Reference

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

| Operation | Method | Endpoint | Notes | |-----------------|--------|-----------------------------|--------------------------------------| | Add memories | POST | /v3/memories/add/ | Async; returns event_id | | Search | POST | /v3/memories/search/ | Filters object required in V3 | | Get all | GET | /v1/memories/ | Query params: user_id, page, etc. | | Get one | GET | /v1/memories/{id}/ | | | Update | PATCH | /v1/memories/{id}/ | | | Delete one | DELETE | /v1/memories/{id}/ | | | Delete all | DELETE | /v1/memories/ | Scoped by entity params | | Memory history | GET | /v1/memories/{id}/history/| Full change log for a memory | | Poll event | GET | /v1/event/{event_id}/ | Status: PENDING / SUCCEEDED / FAILED | | Get users | GET | /v1/entities/ | List known users/agents | | Batch update | POST | /v1/memories/batch/ | Bulk update many memories | | Batch delete | POST | /v1/memories/batch-delete/| Bulk delete many memories | | Create webhook | POST | /v1/webhooks/ | | | Feedback | POST | /v1/memories/{id}/feedback/| User quality signal |

→ Full request/response shapes: references/api-endpoints.md

---

Entity Scoping (Critical — Read This)

Memories are scoped with up to 4 identifiers:

| Field | Purpose | Example | |------------|-----------------------------------------|--------------------| | user_id | Persistent person/account | "customer_6412" | | agent_id | Distinct agent persona | "travel_planner" | | app_id | Tenant / white-label product surface | "ios_retail_app" | | run_id | Ephemeral session / support ticket | "ticket-9241" |

Key rules:

1. At least one entity ID required on every add/search
2. V3 search: entity IDs go INSIDE the filters object (top-level rejected with 400)
3. Writing with user_id="alice" + agent_id=null → searching {user_id:"alice", agent_id:"bot"} returns nothing (null != "bot")
4. Platform stores multi-ID writes as separate records per entity. Query per-entity scope using OR, not AND across entities.
5. Wildcard "*" matches any non-null value: {"run_id": "*"} = any session

// ✅ Correct V3 search
await client.search("hobbies", {
  filters: { user_id: "alice" }
});

// ✅ OR across entities
await client.search("hobbies", {
  filters: {
    OR: [{ user_id: "alice" }, { agent_id: { in: ["bot-a", "bot-b"] } }]
  }
});

// ❌ Wrong — top-level entity IDs rejected in V3
await client.search("hobbies", { user_id: "alice" }); // 400 error

---

V3 Search Filter Operators

Filters support full logical composition:

{
  "AND": [
    { "user_id": "alice" },
    { "categories": { "in": ["hobbies", "travel"] } },
    { "created_at": { "gte": "2025-01-01" } }
  ]
}

Operators: in, gte, lte, gt, lt, ne, icontains, contains, * (wildcard)

Search params:

• top_k: 1–1000, default 10
• threshold: 0–1, default 0.1 (pass 0.0 to disable)
• rerank: default false (enable for better ordering at cost of latency)
• reference_date: Unix epoch / ISO datetime for temporal reasoning

---

MCP Integration

Mem0 has a hosted MCP server — ideal for giving Claude/Cursor/Codex automatic memory:

# One-command setup for all clients
npx mcp-add \
  --name mem0-mcp \
  --type http \
  --url "https://mcp.mem0.ai/mcp" \
  --clients "claude,claude code,cursor,windsurf,vscode,opencode"

MCP tools exposed: add_memory, search_memories, get_memories, get_memory, update_memory, delete_memory, delete_all_memories, delete_entities, list_entities, list_events, get_event_status

→ See references/mcp-and-integrations.md for framework integrations (LangChain, Vercel AI SDK, etc.)

---

Async Add Pattern

V3 add() is always async. The response returns an event_id, not memories directly.

const { event_id } = await client.add(messages, { user_id: "alice" });

// Poll until SUCCEEDED
async function waitForMemory(eventId: string) {
  while (true) {
    const res = await fetch(`https://api.mem0.ai/v1/event/${eventId}/`, {
      headers: { Authorization: `Token ${process.env.MEM0_API_KEY}` }
    });
    const { status } = await res.json();
    if (status === "SUCCEEDED") return;
    if (status === "FAILED") throw new Error("Memory add failed");
    await new Promise(r => setTimeout(r, 500));
  }
}

---

Webhooks

Events: memory_add, memory_update, memory_delete, memory_categorize

# Python SDK
webhook = client.create_webhook(
    url="https://your-app.com/webhook",
    name="Memory Logger",
    project_id="proj_123",
    event_types=["memory_add", "memory_categorize"]
)

Payload shape:

{
  "event_details": {
    "id": "<memory_id>",
    "data": { "memory": "Name is Alex" },
    "event": "ADD"
  }
}

---

OSS Self-Hosted

Use from mem0 import Memory instead of MemoryClient. Requires configuring providers:

from mem0 import Memory

config = {
    "vector_store": { "provider": "qdrant", "config": { "host": "localhost", "port": 6333 } },
    "llm":          { "provider": "openai", "config": { "model": "gpt-4.1-mini" } },
    "embedder":     { "provider": "openai", "config": { "model": "text-embedding-3-small" } },
    "reranker":     { "provider": "cohere", "config": { "model": "rerank-english-v3.0" } },
}

memory = Memory.from_config(config)
memory.add("I love hiking", user_id="alice")
memory.search("hobbies", user_id="alice")

Supported vector stores: Qdrant, Chroma, PGVector, Pinecone, MongoDB, Redis, Supabase, Neon, Weaviate, FAISS, Elasticsearch, Milvus, Cloudflare Vectorize, S3 Vectors, and more.

→ Full provider reference: references/oss-configuration.md

---

Version Gotchas

| Issue | Fix | |-------|-----| | V3 search rejects top-level entity IDs | Move user_id etc. into filters: {} | | add() returns no memories, just event_id | It's async — poll /v1/event/{id}/ | | OSS Memory vs Platform MemoryClient confused | Different classes, different config needs | | AND across user_id + agent_id returns nothing | Platform stores them as separate records; use OR | | Python mem0ai v2.x vs TS mem0ai v3.x | Different major versions, both current |

---

Reference Files

• references/api-endpoints.md — Complete REST endpoint schemas, all request/response fields
• references/mcp-and-integrations.md — MCP setup, LangChain, Vercel AI SDK, LlamaIndex, etc.
• references/oss-configuration.md — All OSS provider configs (LLM, embedder, vector store, reranker)