Mem0 Oss To Platform

Migrate mem0 OSS → mem0 Platform (hosted)

This skill migrates a project's memory layer from the self-hosted mem0 OSS SDK to the hosted mem0 Platform SDK, working for any project shape — an agent, a RAG pipeline, an API service, a chatbot, a background worker. You discover where mem0 is actually used, write a plan the developer reviews, and then execute it on approval.

The mental model (read this first — it's why the migration is shaped the way it is)

OSS mem0 means the developer runs the whole memory stack themselves: a vector store (Qdrant/pgvector/Chroma/…), an embedder, an LLM for fact extraction, and a local history DB. All of that is wired up in a config object passed to Memory.

The Platform means mem0 runs that stack for them. The developer just holds an API key. So the migration is mostly subtraction: the local infrastructure config collapses into a single MemoryClient(api_key=...). The method calls stay recognizable (add/search/get_all/…), but a few parameter conventions tighten up and the return values are server responses.

So the core of every migration is: 1. Memory / Memory.from_config({...}) → MemoryClient() (reads the API key from the env). 2. Delete the local vector_store / llm / embedder / graph_store / history_db_path config. 3. Fix up each call site to the hosted call convention (entity IDs into filters, pagination, etc.). 4. Flag everything that isn't a clean 1:1 so the developer can decide (see references/gotchas.md).

Scope discipline: touch only mem0-related code, config, dependencies, and env. Preserve the project's existing behavior, structure, and style. Do not rename things, "tidy" nearby code, or change the app's logic. The developer asked to swap a backend, not to refactor their project.

Workflow

Work through these phases in order. Phases 1–4 produce the plan; phase 5 runs only after approval.

Phase 0 — Prerequisite check

The hosted SDK needs a mem0 API key (MEM0_API_KEY, obtainable at https://app.mem0.ai). Confirm the developer has one. You don't need the key value to write the plan, but flag in the plan that it must be set (in .env / secrets manager, never hardcoded) before execution and verification.

Phase 1 — Discover the mem0 footprint

Do not assume the layout. Find every place mem0 appears. Detect the language and the installed version first, then sweep for usage. Concretely, search for:

• Imports / instantiation: from mem0 import Memory, Memory.from_config, Memory(,

import ... from "mem0ai", from "mem0ai/oss", new Memory(.

• Config blocks: keys like vector_store/vectorStore, embedder, llm, graph_store/

graphStore, history_db_path, historyStore, custom_fact_extraction_prompt, custom_update_memory_prompt, enable_graph.

• Every call site: .add(, .search(, .get_all(/.getAll(, .delete_all(/.deleteAll(,

.get(, .update(, .delete(, .reset(, .history(.

• Dependencies & env: requirements.txt/pyproject.toml/package.json for mem0ai and any

local-infra deps that exist only for mem0 (e.g. qdrant-client, chromadb); .env/config for things like OPENAI_API_KEY used by the local embedder/LLM; any docker-compose service (e.g. a Qdrant container) that exists only to back mem0.

Use Grep/Glob broadly; a single missed call site is a runtime break later. Record file:line for each finding — the plan's inventory is built from this.

Phase 2 — Verify the API against the installed SDK (don't guess)

Versions drift, and the OSS and hosted classes have subtly different signatures. Before mapping, confirm the real signatures of the installed package rather than trusting memory:

• Python: python -c "import inspect; from mem0 import MemoryClient; print(inspect.signature(MemoryClient.search))"

for each method you'll touch, and read the installed source under site-packages/mem0/client/main.py if anything is ambiguous (e.g. whether a method rejects top-level entity params). Also check the OSS side the project currently uses.

• TypeScript: read the installed types/dist under node_modules/mem0ai/ to confirm option names

(limit vs topK, userId vs a nested filters) and the default vs mem0ai/oss export.

This verification step is the single most important habit — it's what keeps the plan correct across mem0 versions. Then consult references/api-mapping.md for the OSS→hosted translation of each method (Python and TypeScript), and the official guide at https://docs.mem0.ai/migration/oss-v2-to-v3.

Phase 3 — Map each site and flag the gaps

For every call site and config block from Phase 1, determine the hosted equivalent using the mapping. Most calls map cleanly. Some don't — and those matter more than the mechanical edits. Read references/gotchas.md and flag anything that needs a human decision: self-hosted/data- residency setups, local model choices moving server-side, graph-memory usage, custom prompts, hot- path calls that now make network round-trips, and existing locally-stored memories not carrying over (data migration is out of scope unless the developer asks — note it, don't silently attempt it).

Phase 4 — Write the plan and stop

Write the full plan to MEM0_MIGRATION_PLAN.md at the repo root, following the structure in references/plan-template.md. It must be concrete enough to execute from and honest about the gaps. Then stop and present it for review. Do not start editing code in the same turn — the whole point is that the developer reads and approves the plan first.

Phase 5 — Execute on approval (guided)

Once the developer approves (they may ask for changes first — incorporate them), execute the plan:

• Make the edits file by file, staying strictly within mem0 scope.
• Update dependencies and env (MEM0_API_KEY; remove now-dead local-infra deps/services only if

they exist solely for mem0 and you're confident).

• Verify, mirroring how you'd confirm any backend swap:
• It imports / type-checks / byte-compiles.
• A smoke test exercises add → search/get_all → delete_all against the hosted API with a

real MEM0_API_KEY, and the app's own entry point still runs.

• No local mem0 storage directory gets created anymore (e.g. a .mem0/, local Qdrant path) —

proof the memory really lives on the platform now.

• Report what changed, what was verified, and any flagged concerns the developer still needs to act

on (e.g. configuring custom instructions in the dashboard, migrating old data).

Reference files

• references/api-mapping.md — exact OSS→hosted method/param/return mapping for Python and

TypeScript, plus dependency and env changes. Read during Phase 2–3.

• references/gotchas.md — the things that aren't a clean 1:1 and need a human decision. Read

during Phase 3 so the plan's "Concerns" section is complete.

• references/plan-template.md — the exact structure for MEM0_MIGRATION_PLAN.md. Use in Phase 4.

mem0-oss-to-platform — Pipeline Skill

Migrate a project from the Mem0 Open Source (self-hosted) SDK to the Mem0 Platform (hosted) SDK, end to end. The skill audits where Mem0 is used, writes a reviewable migration plan, and executes it after you approve.

This is a pipeline skill, not a reference skill. Invoke it when you want your agent to migrate an existing project's Mem0 integration from OSS to the Platform. For day-to-day SDK coding help, install `mem0` instead.

>

Part of the Mem0 Skill Graph:

- Reference: mem0 · mem0-cli · mem0-vercel-ai-sdk

- Pipeline: mem0-integrate → mem0-test-integration · mem0-oss-to-platform (this skill)

What This Skill Does

When invoked, your assistant will:

• Discover every place Mem0 is used in the project — imports, client init, config blocks, call sites, dependencies, env, and local infra
• Verify the exact API against the installed SDK rather than guessing
• Map each OSS Memory usage to its hosted MemoryClient equivalent (Python and TypeScript)
• Flag everything that isn't a clean 1:1 and needs a human decision
• Write a reviewable MEM0_MIGRATION_PLAN.md, then execute it after you approve — strictly scoped to the Mem0 integration, with no unrelated refactors

When to Use

Trigger phrases:

• "Migrate my Mem0 setup to the Platform"
• "Switch from self-hosted Mem0 to MemoryClient"
• "Use my Mem0 API key instead of a local Qdrant"
• "Move Mem0 to the hosted/managed service"

Do not use this skill for general SDK usage (install `mem0`), or to add Mem0 to a repo that doesn't use it yet (use `mem0-integrate`).

Installation

CLI (Claude Code, Codex, OpenCode, OpenClaw, or any tool that supports skills)

npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform

Claude.ai

1. Download this skills/mem0-oss-to-platform folder as a ZIP 2. Go to Settings > Capabilities > Skills 3. Click Upload skill and select the ZIP

Claude API (Skills API)

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mem0-oss-to-platform", "source": "https://github.com/mem0ai/mem0/tree/main/skills/mem0-oss-to-platform"}'

Prerequisites

• A Mem0 Platform API key (get one)
• An existing project that uses the Mem0 OSS SDK

Workflow

(invoke skill)  →  audits the repo's Mem0 usage,
                   writes MEM0_MIGRATION_PLAN.md,
                   stops for your review
(approve)       →  executes the plan and verifies
                   (compile/import, real-API smoke test)

Links

• Mem0 Platform Dashboard
• Mem0 Documentation
• OSS → Platform migration guide
• Platform vs OSS comparison

License

Apache-2.0

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.

Gotchas — the things that aren't a clean 1:1

Swapping Memory for MemoryClient is mostly mechanical. These items are not mechanical: they change behavior, move responsibility off the developer's machine, or have no direct equivalent. Every one that applies to the project belongs in the plan's "Concerns & decisions needed" section, phrased as a decision for the developer — never silently resolved.

1. Data does not migrate with the code

Migrating the code does not move the memories. Anything stored in the local vector store / history DB stays there; the hosted account starts empty. This is the most surprising gap, so call it out prominently. Data migration is out of scope unless the developer explicitly asks. If they do, the rough path is: read everything from the OSS store (get_all per user/entity) and re-add it to the hosted client — but treat that as a separate, opt-in task.

2. Self-hosting / data residency

A local or self-hosted vector store sometimes exists on purpose — compliance, data residency, air- gapped deployment, cost. Moving to the managed platform sends memory content to mem0's servers. Don't assume that's acceptable; flag it as an explicit decision, especially for regulated domains.

3. Local models move server-side

If the OSS config used specific local/self-chosen models (e.g. Ollama, a particular embedder, a non-OpenAI LLM for fact extraction), those choices disappear — extraction and embedding now run on the platform with the platform's configuration. Memory content and quality may shift as a result. Flag where the project depended on a specific model.

4. Graph memory

If the project uses graph memory (enable_graph, graph_store), this changed in v3 and is handled differently on the platform. Don't assume a drop-in mapping — verify current platform graph support in the docs and flag the usage for the developer.

5. Custom prompts / extraction config

custom_fact_extraction_prompt → custom_instructions, and custom_update_memory_prompt is deprecated. On the platform these tend to be project-level settings configured in the dashboard rather than passed in code. Flag any custom prompt the project relied on so the developer can re- apply it in the dashboard.

6. Every call is now a network request

Local calls become remote API calls. That introduces latency, network failures, timeouts, rate limits, and per-call cost. Flag mem0 calls on hot paths or in tight loops, and recommend adding error handling / retries / timeouts where the old local calls were effectively infallible. For async apps, use AsyncMemoryClient (Python) so calls don't block the event loop.

7. API key & secrets

The hosted client needs MEM0_API_KEY. It must come from the environment / a secrets manager — never hardcoded. Ensure it's added to .env.example, local .env, CI, and deployment config. Without it the client fails to initialize.

8. Dropped constructor args & legacy options

org_id / project_id (Python) and organizationId / projectId (TS) are no longer passed to the constructor in v3 — they're resolved from the API key. Per-call legacy options like async_mode, output_format, and enable_graph are gone. Remove them rather than leaving dead args.

9. Return-shape drift

• add() returns only ADD events on v3. Code that inspected add() results for UPDATE /

DELETE events has dead branches now.

• search / get_all return {"results": [...]}; get_all is paginated (count/next/

previous/results). Code that limited via top_k on get_all should move to page/page_size.

• Default top_k dropped 100 → 20, threshold now 0.1, rerank now false — result counts and

ordering can change even when the call looks equivalent.

10. No global reset()

The OSS reset() wipes the whole local store. There's no hosted equivalent that nukes everything; use delete_all scoped by filters. Flag any reset() call.

Plan template — MEM0_MIGRATION_PLAN.md

Write the plan to MEM0_MIGRATION_PLAN.md at the repo root using the structure below. Keep it concrete enough to execute from and honest about the gaps. Fill every section from the actual findings — don't leave placeholders. Drop a section only if it genuinely doesn't apply (and say so).

# mem0 OSS → Platform Migration Plan

## Summary
- One paragraph: what's moving (self-hosted `Memory` → hosted `MemoryClient`) and why.
- Detected language(s) and the installed `mem0ai` version.
- Counts: N files touched, M call sites, plus config/deps/env changes.

## Prerequisites
- `MEM0_API_KEY` must be set in the environment before execution/verification (https://app.mem0.ai).
- Note where it should live (`.env`, secrets manager, CI, deploy config).

## Inventory
A table of every mem0 touchpoint found, so the developer can see the full footprint:

| File:line | Current (OSS) usage | Category | Maps to |
|-----------|--------------------|----------|---------|
| path:LN   | `Memory.from_config({...})` | client init | `MemoryClient()` |
| path:LN   | `memory.search(q, user_id=...)` | call site | `search(q, filters={...}, top_k=...)` |
| ...       | ...                | config / dep / env / infra | ... |

## Change set
Grouped by file. For each, a short before → after with the actual surrounding code, so the edits are
unambiguous. Example:

### `path/to/file.py`
- Replace import `from mem0 import Memory` → `from mem0 import MemoryClient`.
- Replace the `Memory.from_config({...})` block with `MemoryClient()` (drops local vector_store/
  llm/embedder/history config).
- `search(...)`: move `user_id` into `filters={"user_id": ...}`; keep `top_k`.

before

...

after

...

## Dependencies & config
- `requirements.txt` / `pyproject.toml` / `package.json`: keep `mem0ai`; remove now-unused local-
  infra deps (list them, with the reason each is safe to remove).
- Env: add `MEM0_API_KEY`; remove env vars only used by the old local embedder/LLM if now unused.
- Infrastructure: local services that existed only for mem0 (e.g. a Qdrant docker-compose service)
  can be retired — listed for the developer's confirmation, not auto-deleted.

## Concerns & decisions needed
The non-1:1 items from the gotchas that apply here, each phrased as a decision for the developer.
Cover, where relevant: data not migrating, self-hosting/data-residency, local models moving server-
side, graph memory, custom prompts (now dashboard settings), network/latency/cost on hot paths,
return-shape changes (`add` ADD-only, `get_all` pagination, default `top_k`/threshold/rerank), and
any `reset()` usage. Be specific about which file/line each concern affects.

## Out of scope
- Existing memory **data** is not migrated (code only). If wanted, it's a separate opt-in task
  (export from the OSS store, re-add to the hosted client).
- No unrelated refactors, renames, or behavior changes.

## Verification plan
How execution will be confirmed end-to-end:
- Imports / type-checks / byte-compiles cleanly.
- Smoke test against the hosted API with a real `MEM0_API_KEY`: `add` a fact → `search`/`get_all`
  returns it → `delete_all` clears it. Plus: the app's own entry point still runs.
- Confirm no local mem0 storage dir is created anymore (e.g. `.mem0/`) — proof memory is hosted.

## Rollback
- All changes are in version control; revert with git if needed. Note the branch/commit strategy.