OSS → Platform API mapping

Exact translation of the mem0 OSS (self-hosted Memory) API to the hosted MemoryClient API. Always confirm against the installed package (see SKILL.md Phase 2) — versions drift. The facts below match mem0ai 2.0.x (the v3 platform API) and the official guide: https://docs.mem0.ai/migration/oss-v2-to-v3

Contents

• Python
• TypeScript / JavaScript
• Return shapes
• Dependencies & environment
• v2→v3 default/behavior changes

Python

Import & client construction

# OSS (self-hosted)
from mem0 import Memory
memory = Memory()                       # or:
memory = Memory.from_config({           # all of this local config disappears
    "vector_store": {...},
    "llm": {...},
    "embedder": {...},
    "history_db_path": "...",
})

# Platform (hosted)
from mem0 import MemoryClient
memory = MemoryClient()                 # reads MEM0_API_KEY from the env
# or: MemoryClient(api_key="...")

Notes:

• The client reads MEM0_API_KEY from the environment when api_key is omitted.
• Drop vector_store, llm, embedder, graph_store, history_db_path — these are managed server-side now.
• Drop org_id / project_id constructor args if present — they're resolved from the API key in v3.
• For async codebases, use AsyncMemoryClient (same methods, await-ed).

Method calls

Key rule: for search and get_all, the hosted client requires entity IDs (user_id, agent_id, app_id, run_id) inside a filters dict and will raise if you pass them top-level. For add and delete_all, top-level entity IDs are accepted.

TypeScript / JavaScript

The hosted and OSS SDKs ship in the same mem0ai npm package, distinguished by import path. Confirm option names against node_modules/mem0ai/ types.

Import & client construction

// OSS (self-hosted) — note the "/oss" subpath
import { Memory } from "mem0ai/oss";
const memory = new Memory({ /* vectorStore, embedder, llm, historyStore … */ });

// Platform (hosted) — default export from the package root
import MemoryClient from "mem0ai";
const memory = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
// Drop organizationId / projectId — resolved from the API key in v3.

Method calls (option-object differences)

Also drop legacy options that no longer apply on v3: async_mode, output_format, enable_graph.

Return shapes

• search(...) and get_all(...) return {"results": [...]}; each item has at least a memory (text) field, plus id and (for search) score. Code that reads result["results"] and pulls item["memory"] keeps working.
• get_all(...) on the hosted client is paginated: {"count", "next", "previous", "results": [...]}.
• add(...) returns the created memories. On v3 it returns only ADD events — if the old code branched on event == "UPDATE" / "DELETE" from add() results, that branch is now dead.

Dependencies & environment

• Keep the mem0ai dependency — MemoryClient ships in the same package. No version bump is required just to use the hosted client (confirm the installed version supports it).
• Remove dependencies that existed only to back the local mem0 store/embedder/LLM and are now unused (e.g. qdrant-client, chromadb, a local embedding lib). Only remove what you can confirm is unused elsewhere.
• Add MEM0_API_KEY to the environment / .env.example / secrets manager / deployment config.
• Local-infra services (e.g. a Qdrant docker-compose service) that existed only for mem0 can be retired — flag this rather than deleting infrastructure unilaterally.

v2→v3 default/behavior changes

From the official migration guide — surface any that affect the project:

• Python top_k default changed 100 → 20; TS limit renamed to topK.
• New threshold default 0.1 (was none); new rerank default false (was true).
• custom_fact_extraction_prompt → custom_instructions; custom_update_memory_prompt deprecated.
• Graph memory (enable_graph, graph_store) removed from the OSS v3 surface — see gotchas.