mem0-oss-to-platform

mem0 OSS から mem0 Platform（ホステッド）への移行

このスキルは、プロジェクトのメモリ層をセルフホストの mem0 OSS SDKからホステッド mem0 Platform SDKに移行します。エージェント、RAG パイプライン、API サービス、チャットボット、バックグラウンドワーカーなど、あらゆる形態のプロジェクトに対応します。mem0 が実際に使われている箇所を特定し、開発者が確認する計画を作成して、承認後に移行を実行します。

考え方（最初にお読みください。移行の形がこのようになっている理由です）

OSS mem0 では、開発者がメモリスタック全体を自分で実行します。ベクトルストア（Qdrant／pgvector／Chroma／…）、埋め込みモデル、事実抽出用の LLM、ローカルの履歴 DB が必要です。これらすべてを設定オブジェクトにまとめ、Memory に渡します。

Platform では、mem0 がそのスタックを代わりに実行します。開発者が用意するのは API キーだけです。そのため、移行の大部分は 削除 です。ローカルインフラの設定は、単一の MemoryClient(api_key=...) に集約されます。メソッド呼び出し（add／search／get_all／…）は見慣れた形のままですが、一部のパラメーター規約が厳密になり、戻り値はサーバーからのレスポンスになります。

そのため、あらゆる移行の中核は次のとおりです。

1. Memory ／ Memory.from_config({...}) → MemoryClient()（環境変数から API キーを読み取ります）。
2. ローカルの vector_store ／ llm ／ embedder ／ reranker ／ history_db_path の設定と、残っている graph_store を削除します。
3. 各呼び出し箇所をホステッド版の呼び出し規約（filters へのエンティティ ID の指定、ページネーションなど）に合わせて修正します。
4. そのままでは 1 対 1 で移行できない箇所をすべて明示し、開発者が判断できるようにします（references/gotchas.md を参照）。

スコープの厳守： mem0 関連のコード、設定、依存関係、環境変数のみを変更してください。プロジェクト既存の動作、構成、スタイルは維持してください。名前の変更、周辺コードの「整理」、アプリのロジックの変更は行わないでください。開発者が求めているのはバックエンドの切り替えであり、プロジェクトのリファクタリングではありません。

ワークフロー

以下のフェーズを順番に進めてください。フェーズ 1～4 で計画を作成し、フェーズ 5 は承認後にのみ実行します。

フェーズ 0 — 前提条件の確認

ホステッド SDK には mem0 API キー（MEM0_API_KEY、https://app.mem0.ai で取得可能）が必要です。開発者がキーを持っていることを確認してください。計画の作成時にキーの値を知る必要はありませんが、実行と検証の前に設定する必要があること（ハードコードはせず、.env またはシークレットマネージャーに設定すること）を計画に明記してください。

フェーズ 1 — mem0 の使用箇所を特定

プロジェクトの構成を決めつけないでください。mem0 が登場する箇所をすべて見つけてください。まず言語とインストール済みバージョンを特定し、その後で使用箇所を網羅的に検索します。具体的には、次を検索してください。

• インポート／インスタンス化： from mem0 import Memory、AsyncMemory、Memory.from_config、 Memory(、import ... from "mem0ai"、from "mem0ai/oss"、new Memory(。
• 設定ブロック： vector_store／vectorStore、embedder、llm、reranker、 graph_store／graphStore、history_db_path／historyDbPath、historyStore、 custom_instructions／customInstructions、custom_fact_extraction_prompt／customPrompt、 custom_update_memory_prompt、enable_graph などのキー。
• すべての呼び出し箇所： .add(、.search(、.get_all(／.getAll(、.delete_all(／.deleteAll(、 .get(、.update(、.delete(、.reset(、.history(。
• 依存関係と環境変数： requirements.txt／pyproject.toml／package.json にある mem0ai と、mem0 のためだけに使われているローカルインフラ関連の依存関係（例：qdrant-client、chromadb）を確認します。ローカルの埋め込みモデルや LLM で使われる OPENAI_API_KEY などの .env／設定も確認してください。mem0 のバックエンドとしてのみ存在する docker-compose サービス（例：Qdrant コンテナー）も調べてください。

Grep／Glob を広く使ってください。呼び出し箇所をひとつ見落とすだけでも、後に実行時エラーが発生します。各該当箇所の file:line を記録してください。計画の一覧はこの記録をもとに作成します。

フェーズ 2 — インストール済み SDK に対して API を確認する（推測しない）

バージョンによって差異があり、OSS 版とホステッド版のクラスではシグネチャが微妙に異なります。マッピングする前に、記憶を頼りにせず、インストール済みパッケージの実際のシグネチャを確認します。

• Python: python -c "import inspect; from mem0 import MemoryClient; print(inspect.signature(MemoryClient.search))" を、使用する各メソッドについて実行し、不明な点（メソッドがトップレベルのエンティティパラメーターを拒否するかどうかなど）があれば、インストール済みのソースコード site-packages/mem0/client/main.py を確認します。また、プロジェクトが現在使用している OSS 版も確認します。
• TypeScript: node_modules/mem0ai/ 内のインストール済みの型定義／dist を確認し、オプション名（limit と topK、userId とネストされた filters: { user_id }）と、デフォルトのエクスポートと mem0ai/oss のエクスポートを確認します。

この確認手順は最も重要な習慣です。これによって、mem0 のバージョンが変わっても計画を正確に保てます。その後、各メソッドを OSS 版からホステッド版へ変換する方法について、references/api-mapping.md（Python および TypeScript）を確認します。ドキュメントのガイドは https://docs.mem0.ai/migration/oss-to-platform です（コードサンプルはインストール済み SDK と照合してください）。OSS のアップグレードに関する変更点は https://docs.mem0.ai/migration/oss-v2-to-v3 にあります。

フェーズ 3 — 各使用箇所をマッピングし、相違点に印を付ける

フェーズ 1 で洗い出した各呼び出し箇所と設定ブロックについて、マッピングを使ってホステッド版での相当箇所を特定します。ほとんどの呼び出しは問題なく対応できます。そうでないものもあり、機械的な編集よりも、そうした点のほうが重要です。references/gotchas.md を読み、人の判断が必要な項目に印を付けます。セルフホスト／データレジデンシーの構成、ローカルモデルのサーバー側への移行、グラフメモリの使用、カスタムプロンプト、ホットパスの呼び出しで新たに発生するネットワーク往復、そして既存のローカル保存メモリが引き継がれないことが該当します（開発者から依頼がない限り、データ移行は対象外です。注記はしますが、黙って実行しないでください。依頼があった場合は、ホステッド Qdrant の移行スクリプトを説明している references/gotchas.md の #1 を参照してください）。

フェーズ 4 — 計画を作成して停止する

リポジトリのルートにある MEM0_MIGRATION_PLAN.md に、references/plan-template.md の構成に従って完全な計画を記述します。計画は、実行に十分な具体性があり、相違点についても正直に記載されている必要があります。その後、停止してレビューに回します。 同じターンでコードの編集を始めないでください。まず開発者が計画を読んで承認することが目的です。

フェーズ 5 — 承認後に実行する（ガイド付き）

開発者が承認したら（先に変更を依頼された場合は、それを反映してから）、計画を実行します。

• ファイルごとに編集し、mem0 の範囲を厳守します。
• 依存関係と環境変数を更新します（MEM0_API_KEY。mem0 専用であり、削除して問題ないと確信できる場合に限り、不要になったローカルインフラの依存関係／サービスを削除します）。
• バックエンドの置き換えを確認する場合と同様に、検証します。
  • インポート、型チェック、バイトコンパイルが成功すること。
  • 実際の MEM0_API_KEY を使ってホステッド API に対し、add → search／get_all → delete_all を実行するスモークテストを行い、アプリケーション独自のエントリーポイントも引き続き実行できること。ホステッド版の add は非同期なので、search／get_all で情報が表示されるまで少し待ちます。
  • ローカルの OSS ストレージが新たに作成されないこと（例：~/.mem0/history.db、ローカルの Qdrant パス）。ただし、クライアント自体は ~/.mem0/config.json を作成するため、確認に .mem0/ ディレクトリ全体を使わないでください。
• 変更内容、検証した項目、開発者が引き続き対応する必要のある懸念事項（例：カスタム指示を project.update で再適用すること、古いデータの移行）を報告します。

参考ファイル

• references/api-mapping.md — Python および TypeScript における OSS 版からホステッド版へのメソッド／パラメーター／戻り値の正確な対応関係と、依存関係および環境変数の変更点。フェーズ 2〜3 で読みます。
• references/gotchas.md — 単純な 1 対 1 の対応にならず、人の判断が必要な項目。計画の「懸念事項」セクションを漏れなく記載できるよう、フェーズ 3 で読みます。
• references/plan-template.md — MEM0_MIGRATION_PLAN.md の正確な構成。フェーズ 4 で使用します。