feat(skills): add mem0-oss-to-platform migration skill (#5455)
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: kartik-mem0 <kartik.labhshetwar@mem0.ai>
This commit is contained in:
youneshima
co-authored by
Claude Opus 4.8
kartik-mem0
Claude Opus 4.8
kartik-mem0
parent
1d56f85705
commit
f48b133101
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
</Info>
|
||||
|
||||
## Plan
|
||||
### Plan
|
||||
|
||||
1. **Sign up**: Create an account on <a href="https://app.mem0.ai?utm_source=oss&utm_medium=migration-oss-to-platform" rel="nofollow">Mem0 Platform</a>.
|
||||
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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
+3
-1
@@ -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/<slug> 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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
```
|
||||
Reference in New Issue
Block a user