From f48b133101e7ee27b93979861f05d3838482d7e4 Mon Sep 17 00:00:00 2001 From: youneshima Date: Fri, 12 Jun 2026 07:18:37 -0700 Subject: [PATCH] feat(skills): add mem0-oss-to-platform migration skill (#5455) Co-authored-by: Claude Opus 4.8 Co-authored-by: kartik-mem0 --- AGENTS.md | 4 +- README.md | 3 +- docs/migration/oss-to-platform.mdx | 23 ++- docs/vibecoding.mdx | 2 + skills/README.md | 4 +- skills/mem0-oss-to-platform/LICENSE | 189 ++++++++++++++++++ skills/mem0-oss-to-platform/README.md | 79 ++++++++ skills/mem0-oss-to-platform/SKILL.md | 120 +++++++++++ .../references/api-mapping.md | 117 +++++++++++ .../references/gotchas.md | 63 ++++++ .../references/plan-template.md | 72 +++++++ 11 files changed, 668 insertions(+), 8 deletions(-) create mode 100644 skills/mem0-oss-to-platform/LICENSE create mode 100644 skills/mem0-oss-to-platform/README.md create mode 100644 skills/mem0-oss-to-platform/SKILL.md create mode 100644 skills/mem0-oss-to-platform/references/api-mapping.md create mode 100644 skills/mem0-oss-to-platform/references/gotchas.md create mode 100644 skills/mem0-oss-to-platform/references/plan-template.md diff --git a/AGENTS.md b/AGENTS.md index 514e6297e..73aee9d54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ This is a **polyglot monorepo** containing Python and TypeScript packages, CLIs, | `integrations/vercel-ai-sdk/` | `@mem0/vercel-ai-provider` — Vercel AI SDK memory provider | | `server/` | FastAPI REST server for self-hosted Mem0 (Docker: FastAPI + PostgreSQL/pgvector + Neo4j) | | `openmemory/` | Self-hosted memory platform — `api/` (FastAPI + Alembic + MCP server) and `ui/` (Next.js 15 + React 19) | -| `skills/` | Claude Code skill definitions. Reference skills (SDK knowledge, always-on): `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/`. Pipeline skills (run on demand): `mem0-integrate/`, `mem0-test-integration/` | +| `skills/` | Claude Code skill definitions. Reference skills (SDK knowledge, always-on): `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/`. Pipeline skills (run on demand): `mem0-integrate/`, `mem0-test-integration/`, `mem0-oss-to-platform/` | | `docs/` | Documentation site (Mintlify) | | `tests/` | Python SDK tests (pytest) | | `evaluation/` | Benchmarking framework — LOCOMO evals, experiment runner, score generation | @@ -390,7 +390,7 @@ Model Context Protocol support in multiple places: - `integrations/mem0-plugin/` provides integrations for Claude Code, Cursor, and Codex via MCP server connections and lifecycle hooks for automatic memory capture. - `skills/` contains structured skill definitions for AI agents, split into two categories: - **Reference skills** (always-on SDK knowledge): `mem0` (Python + TS SDKs, framework integrations), `mem0-cli` (terminal workflows), `mem0-vercel-ai-sdk` (Vercel AI provider). - - **Pipeline skills** (run on demand): `mem0-integrate` wires Mem0 into an existing repo via a TDD pipeline; `mem0-test-integration` verifies what the integrator produced on the same branch. The two are loosely coupled via `.mem0-integration/` artifacts. + - **Pipeline skills** (run on demand): `mem0-integrate` wires Mem0 into an existing repo via a TDD pipeline; `mem0-test-integration` verifies what the integrator produced on the same branch (the two are loosely coupled via `.mem0-integration/` artifacts); `mem0-oss-to-platform` migrates an existing project from Mem0 OSS to the hosted Platform SDK (plan, then execute on approval). ### Adding a New Provider diff --git a/README.md b/README.md index 6ef3a8e7e..15dcc992e 100644 --- a/README.md +++ b/README.md @@ -186,9 +186,10 @@ npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk ```bash npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration +npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform ``` -Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture. +Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. Use `/mem0-oss-to-platform` to migrate an existing project from Mem0 OSS to the hosted Platform SDK. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture. ### Basic Usage diff --git a/docs/migration/oss-to-platform.mdx b/docs/migration/oss-to-platform.mdx index 8b70e363d..c478701e2 100644 --- a/docs/migration/oss-to-platform.mdx +++ b/docs/migration/oss-to-platform.mdx @@ -6,9 +6,7 @@ versionFrom: "Open Source" versionTo: "Platform" --- -# Migrate from Open Source to Platform - -Move your Mem0 implementation to managed infrastructure with enterprise features. +## Overview | Scope | Effort | Downtime | | --------------------- | -------------- | ---------------------------- | @@ -30,12 +28,29 @@ Move your Mem0 implementation to managed infrastructure with enterprise features - **Production Grade**: Auto-scaling, high availability, dedicated support -## Plan +### Plan 1. **Sign up**: Create an account on Mem0 Platform. 2. **Get API Key**: Navigate to **Settings > API Keys** and generate a new key. 3. **Review Usage**: Identify where you instantiate `Memory` and where you call `search` or `get_all`. +## Migrate with Agent Skill + +Paste this prompt into your coding agent. It uses a migration skill to produce a plan; once you review and approve it, the agent implements the changes. + +```text +Migrate my project from Mem0 OSS to the Mem0 Platform SDK using the +mem0-oss-to-platform skill in the mem0ai/mem0 repo, at +skills/mem0-oss-to-platform/ + +Get the skill whichever way is easiest: +- install it: npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform +- if the mem0 repo is cloned locally, read it from skills/mem0-oss-to-platform/ +- otherwise fetch that folder from github.com/mem0ai/mem0 (SKILL.md + references/) + +Then read SKILL.md and begin the migration. +``` + ## Migrate ### 1. Import Memories Into Platform diff --git a/docs/vibecoding.mdx b/docs/vibecoding.mdx index 1de91f645..2cb4c826b 100644 --- a/docs/vibecoding.mdx +++ b/docs/vibecoding.mdx @@ -45,10 +45,12 @@ Let your assistant execute an end-to-end workflow in an existing repo. Invoked a ```bash npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration +npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform ``` - `/mem0-integrate` — wire Mem0 into an existing repository using a goal-driven, test-first pipeline. Detects the stack, asks whether to use Platform or OSS, writes failing tests first, and keeps the integration additive and feature-flagged. - `/mem0-test-integration` — verify what `/mem0-integrate` produced. Runs the repo's native test suite and a real end-to-end smoke flow against your API key, then produces a scorecard. +- `/mem0-oss-to-platform` — migrate an existing project from Mem0 OSS to the hosted Platform SDK. Audits where Mem0 is used, writes a reviewable migration plan, then executes it on approval. See the [skills index](https://github.com/mem0ai/mem0/tree/main/skills) for the full catalog. diff --git a/skills/README.md b/skills/README.md index c14b5cab2..b38716f3b 100644 --- a/skills/README.md +++ b/skills/README.md @@ -22,8 +22,9 @@ Invoked as a slash command to execute a specific end-to-end workflow. These do r |-------|---------|---------| | [`mem0-integrate`](./mem0-integrate/) | `/mem0-integrate` — wire Mem0 into an existing repo via TDD | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate` | | [`mem0-test-integration`](./mem0-test-integration/) | `/mem0-test-integration` — verify what `/mem0-integrate` produced | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration` | +| [`mem0-oss-to-platform`](./mem0-oss-to-platform/) | `/mem0-oss-to-platform` — migrate a project from Mem0 OSS to the hosted Platform SDK | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform` | -The two pipeline skills are designed to run in sequence on the same workspace: +The `mem0-integrate` and `mem0-test-integration` skills are designed to run in sequence on the same workspace: ``` /mem0-integrate → mem0-integrate/ branch + .mem0-integration/ artifacts @@ -36,6 +37,7 @@ The two pipeline skills are designed to run in sequence on the same workspace: - **Using the terminal CLI?** → `mem0-cli` - **Building with `@ai-sdk/*`?** → `mem0-vercel-ai-sdk` - **Want the assistant to wire Mem0 into an existing repo for you?** → `mem0-integrate`, then `mem0-test-integration` +- **Already using Mem0 OSS and want to move to the hosted Platform?** → `mem0-oss-to-platform` ## Links diff --git a/skills/mem0-oss-to-platform/LICENSE b/skills/mem0-oss-to-platform/LICENSE new file mode 100644 index 000000000..78c99ae28 --- /dev/null +++ b/skills/mem0-oss-to-platform/LICENSE @@ -0,0 +1,189 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but not + limited to compiled object code, generated documentation, and + conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work. + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to the Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by the Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding any notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2024 Mem0.ai + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/skills/mem0-oss-to-platform/README.md b/skills/mem0-oss-to-platform/README.md new file mode 100644 index 000000000..2f28e0ac6 --- /dev/null +++ b/skills/mem0-oss-to-platform/README.md @@ -0,0 +1,79 @@ +# 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`](../mem0/SKILL.md) instead. +> +> **Part of the Mem0 Skill Graph:** +> - Reference: [mem0](../mem0/SKILL.md) · [mem0-cli](../mem0-cli/SKILL.md) · [mem0-vercel-ai-sdk](../mem0-vercel-ai-sdk/SKILL.md) +> - Pipeline: [mem0-integrate](../mem0-integrate/SKILL.md) → [mem0-test-integration](../mem0-test-integration/SKILL.md) · **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`](../mem0/SKILL.md)), or to add Mem0 to a repo that doesn't use it yet (use [`mem0-integrate`](../mem0-integrate/SKILL.md)). + +## Installation + +### CLI (Claude Code, Codex, OpenCode, OpenClaw, or any tool that supports skills) + +```bash +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) + +```bash +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](https://app.mem0.ai/dashboard/api-keys)) +- 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](https://app.mem0.ai) +- [Mem0 Documentation](https://docs.mem0.ai) +- [OSS → Platform migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) +- [Platform vs OSS comparison](https://docs.mem0.ai/platform/platform-vs-oss) + +## License + +Apache-2.0 diff --git a/skills/mem0-oss-to-platform/SKILL.md b/skills/mem0-oss-to-platform/SKILL.md new file mode 100644 index 000000000..1cdde7dff --- /dev/null +++ b/skills/mem0-oss-to-platform/SKILL.md @@ -0,0 +1,120 @@ +--- +name: mem0-oss-to-platform +description: >- + Plan and then execute a migration of a project from the mem0 open-source / self-hosted SDK + (the local `Memory` class) to the mem0 Platform / hosted / managed SDK (the `MemoryClient` + class). Use this whenever a developer wants to move, switch, or migrate their mem0 usage off + OSS/self-hosted to the hosted API — e.g. "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 cloud/hosted/managed service", or "replace my local mem0 vector store + embedder config + with the platform". Applies to Python (`from mem0 import Memory` → `from mem0 import MemoryClient`) + and TypeScript/JavaScript (`import { Memory } from "mem0ai/oss"` → `import MemoryClient from "mem0ai"`). + Trigger even when the user doesn't say the word "migrate" but clearly wants their existing mem0 + integration to run against the hosted platform. It first produces a reviewable migration plan, + then executes it after the developer approves. Strictly scoped to the mem0 integration — it does + not refactor, restructure, or "improve" any unrelated code. +--- + +# 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. diff --git a/skills/mem0-oss-to-platform/references/api-mapping.md b/skills/mem0-oss-to-platform/references/api-mapping.md new file mode 100644 index 000000000..9c9a04b66 --- /dev/null +++ b/skills/mem0-oss-to-platform/references/api-mapping.md @@ -0,0 +1,117 @@ +# 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](#python) +- [TypeScript / JavaScript](#typescript--javascript) +- [Return shapes](#return-shapes) +- [Dependencies & environment](#dependencies--environment) +- [v2→v3 default/behavior changes](#v2v3-defaultbehavior-changes) + +--- + +## Python + +### Import & client construction +```python +# 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 +| Operation | OSS `Memory` | Hosted `MemoryClient` | +|---|---|---| +| add | `memory.add(messages, user_id="u")` | `memory.add(messages, user_id="u")` — unchanged (top-level entity IDs accepted) | +| search | `memory.search(q, user_id="u", limit=N)` *(older)* or `…, filters={"user_id":"u"}, top_k=N` *(newer)* | `memory.search(q, filters={"user_id": "u"}, top_k=N)` — entity IDs **must** be inside `filters`; top-level `user_id`/`agent_id`/`app_id`/`run_id` raise `ValueError` | +| get_all | `memory.get_all(user_id="u")` or `…, filters={"user_id":"u"}` | `memory.get_all(filters={"user_id": "u"}, page=1, page_size=N)` — entity IDs in `filters`; paginated with `page`/`page_size` (**not** `top_k`) | +| delete_all | `memory.delete_all(user_id="u")` | `memory.delete_all(user_id="u")` — unchanged | +| get | `memory.get(memory_id)` | `memory.get(memory_id)` | +| update | `memory.update(memory_id, data=...)` | `memory.update(memory_id, text=...)` — confirm param name against installed sig | +| delete | `memory.delete(memory_id)` | `memory.delete(memory_id)` | +| reset | `memory.reset()` (wipes the local store) | **No global reset.** Use `memory.delete_all(filters=...)` scoped to the relevant entity. Flag this. | + +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 +```typescript +// 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) +| Operation | OSS / old client | Hosted client (v3) | +|---|---|---| +| add | `memory.add(messages, { userId: "u" })` | `memory.add(messages, { userId: "u" })` — unchanged | +| search | `memory.search(q, { userId: "u", limit: 20 })` | `memory.search(q, { filters: { userId: "u" }, topK: 20 })` — entity IDs into `filters`; `limit` → `topK` | +| getAll | `memory.getAll({ userId: "u" })` | `memory.getAll({ filters: { userId: "u" } })` — entity IDs into `filters` | +| deleteAll | `memory.deleteAll({ userId: "u" })` | `memory.deleteAll({ userId: "u" })` | +| get / update / delete | `memory.get(id)` etc. | same, by memory id | + +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. diff --git a/skills/mem0-oss-to-platform/references/gotchas.md b/skills/mem0-oss-to-platform/references/gotchas.md new file mode 100644 index 000000000..d5e610f72 --- /dev/null +++ b/skills/mem0-oss-to-platform/references/gotchas.md @@ -0,0 +1,63 @@ +# 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. diff --git a/skills/mem0-oss-to-platform/references/plan-template.md b/skills/mem0-oss-to-platform/references/plan-template.md new file mode 100644 index 000000000..bd9cbcd0c --- /dev/null +++ b/skills/mem0-oss-to-platform/references/plan-template.md @@ -0,0 +1,72 @@ +# 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). + +```markdown +# 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. +```