mem0-integrate

mem0-integrate

目標主導かつテストファーストのパイプラインで、既存のリポジトリに Mem0 を組み込みます。 検証には mem0-test-integration を併用します。

正式な情報源（判断する前に取得してください）

ステップ 3 の前に、このスキルは必ず WebFetch で以下の URL を取得し、plan.md に引用してください。 これらを確かな情報源とし、Mem0 API についての一般知識に頼らないでください。

エージェント向けドキュメント

• スコープタグ付きドキュメントインデックス：https://docs.mem0.ai/llms.txt
• 全ドキュメント（単一ファイル、詳細解説）：https://docs.mem0.ai/llms-full.txt
• OpenAPI 仕様（Platform REST、機械可読形式）：https://docs.mem0.ai/openapi.json
• ホスト型 MCP サーバー：https://mcp.mem0.ai/mcp（Platform API キーが必要）
• インテグレーションインデックス：https://docs.mem0.ai/integrations

公開済みの Mem0 スキル — 委任して、再実装しないでください

独自の呼び出しパターンを作成するよりも、こちらを優先してください。各スキルはトリガー、例、バージョン固定のコードを含む独立した SKILL.md です。

• SDK（Python + TS、Platform + OSS）：https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0/SKILL.md
• CLI：https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-cli/SKILL.md
• Vercel AI SDK：https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-vercel-ai-sdk/SKILL.md
• ポータブルなエディター／MCP プラグイン：https://github.com/mem0ai/mem0/tree/main/integrations/mem0-agent-plugin

SDK ソース（ドキュメントが曖昧な場合に参照）

公開リポジトリです。main ブランチがメジャーバージョンを超えて更新されている場合は、このスキルのフロントマターにある mem0_tested_versions の範囲と照合してください。

• リポジトリのルート：https://github.com/mem0ai/mem0
• Python SDK：https://github.com/mem0ai/mem0/tree/main/mem0
• TypeScript SDK：https://github.com/mem0ai/mem0/tree/main/mem0-ts

クイックスタート（不慣れなスタックの初期設定用）

• Platform：https://docs.mem0.ai/platform/quickstart
• OSS Python：https://docs.mem0.ai/open-source/python-quickstart
• OSS Node：https://docs.mem0.ai/open-source/node-quickstart
• Platform と OSS の比較：https://docs.mem0.ai/platform/platform-vs-oss

統合の原則（譲れない条件）

このスキルの真の目的は、メンテナーが異議なく受け入れられる PR を作成することです。そのため、侵襲的な変更は一切行いません。

1. 置き換えではなく追加。 対象リポジトリに既存のメモリシステム、セッションストア、ユーザーコンテキストレイヤー、または Memory／memory_* という名前のものがある場合、Mem0 はそれを置き換えるのではなく、併用します。既存のシステムは変更なしで動作し続けます。
2. デフォルトではオプトイン。 新しい Mem0 コードはすべて、機能フラグ（MEM0_ENABLED=1 のような環境変数、設定キー、または戦略セレクター）で制御します。フラグが設定されていない場合、リポジトリ本来の動作をバイト単位で維持します。
3. 破壊的変更なし。 エクスポートの削除、公開関数の名前変更、メソッドシグネチャの変更、既存テストの変更、既存テストの動作変更は行いません。既存のテストはすべて、フラグの設定時と未設定時の両方で、変更なしに合格する必要があります。
4. 依存関係の追加は最小限に。 mem0ai（および委任先のスキルが必要とする依存関係）以外は追加しません。新しいベクトルストア、グラフデータベース、リポジトリで現在使われていないプロバイダー SDK は追加しません。
5. コミットを分離。 コード、テスト、設定／ドキュメントは、それぞれ別のコミットに含め、レビュアーが個別にチェリーピックできるようにします。
6. 何もしない選択肢を優先。 手順 6（計画）の後に、追加方式でフラグ制御可能な適合方法が見つからなければ、理由を示して終了コード 1 で終了します。質の低い PR は、PR を出さないよりも悪い選択です。
7. バックエンドのみ。 Mem0 の統合はサーバー側のコードに実装します。API キー、メモリのスコープ、ユーザー ID の解決をクライアント側で扱うのは安全ではありません。バックエンドとフロントエンドの両方があるリポジトリでは、呼び出し箇所をバックエンドのファイルに配置します。フロントエンドのみのリポジトリは、事前条件の確認時に対象外とします。

以下の 4 つのゲートで徹底します。事前条件（フロントエンドのみのリポジトリ、および追加方式での適合が不可能なリポジトリを除外）、手順 2 の理解（バックエンドの存在を確認し、候補となる箇所を示す）、手順 6 の計画レビュー（既存のエクスポートを変更する計画や、クライアント側の呼び出し箇所を挙げる計画を却下）、手順 10 の自己修復ループ（原則違反を「修正」せず、問題として提示）。

スキル委任のルール

コードを書く前に、対象のスタックをカバーする公開済みスキルがないか確認します。見つかった場合は、そのスキルに委任し、呼び出し箇所のパターンを plan.md とテストにそのまま記載します。言い換えないでください。

対象リポジトリで検出されたもの	委任先	理由
package.json に @ai-sdk/* と ai がある	skills/mem0-vercel-ai-sdk	統合には生の MemoryClient ではなく、createMem0 プロバイダーラッパーを使います。
CLI のみのリポジトリ（Typer、Commander、Click、Cobra）で、LLM の呼び出し箇所がない	skills/mem0-cli	呼び出し箇所はモデルラッパーではなくコマンドハンドラーです。まず mem0 が本当に適合するか検討してください。
対象が MCP クライアント／エディター設定（Claude Code、Cursor、Codex 設定）	integrations/mem0-agent-plugin	ローカルの stdio MCP サーバー（検索ツール 1 つ）とスキルを使用し、フックや自動取得はありません。ホスト型エンドポイントを使う場合は https://mcp.mem0.ai/mcp を使用してください。通常、SDK コードは不要です。
上記以外の、LLM の呼び出し箇所がある Python または TS リポジトリ	skills/mem0	デフォルトの SDK 統合方法です。

委任先スキルの生 URL を、plan.md の "Delegated skill:" フィールドに記録します。手順 7 のテスト作成者と、手順 8 の実装サブエージェントは、どちらもこのフィールドを参照します。

前提条件

以下のすべてを満たしていない場合は、開始を拒否してください。

• 現在の作業ディレクトリが、インデックスがクリーンな Git リポジトリ内にあること （コミットされていない変更がないこと）。ユーザーの作業を保護します。すべての編集は、 進行中の変更の上ではなく、フィーチャーブランチに反映されます。
• リポジトリで言語を検出できること（package.json／pyproject.toml／ requirements.txt）。言語を検出できない場合は、理由を記載して正常に終了します。
• リポジトリにバックエンドがあること。検出対象は、backend/、server/、api/の いずれかのディレクトリ、FastAPI／Flask／Django／Starlette を使用する Python パッケージ、 Express／Fastify／Koa／NestJS／Next-API-routes を使用する Node パッケージ、 またはエージェントループフレームワーク（LangGraph、LangChain、LlamaIndex、Agno）です。 フロントエンドのみのリポジトリ（React／Vue／Svelte の SPA のみ、静的サイト、 モバイルのみ）は、理由を添えてコード 1 で終了します。Mem0 はクライアント側には インストールされません。
• ユーザーが、このリポジトリに Mem0 が適しているとすでに判断していること。このスキルは 適合性を正当化するためにコードベースを調査しません。具体的な目標を持ち込んでください。 （ステップ 2 では、リポジトリの内容を把握し、バックエンドの統合箇所を特定するために リポジトリを読み込みます。これは適合性の正当化ではなく、作業上必要なものです。）

前提条件を満たさない場合は、理由を記載して終了してください。「とにかく動かす」ことは 試みないでください。

パイプライン

全 10 ステップです。詳細な手順、ドキュメントテンプレート、ゲートのルールは references/pipeline.md に記載されています。ステップの実行を 開始する際はそのファイルを読んでください。以下の概要は、進行先を示すためだけのものです。

#	ステップ	ゲート
1	言語の検出。 package.json／pyproject.toml／requirements.txt。モノレポの場合は、対象のサブディレクトリを尋ねます。
2	リポジトリの把握。 README、コントリビューター向けドキュメント、エントリーポイント、ディレクトリの上位 2 階層を、予算に応じて読み込みます。優先順位を付けたバックエンドの統合箇所を含む repo-summary.md を作成します。	ユーザーが概要を確認し、統合箇所を選択します。バックエンドの統合箇所がない場合は、コード 1 で終了します。
3	製品の選択。 Platform と OSS のいずれかを選択します。依存関係のシグナルから推奨しますが、何もない状態で質問することはありません。	goal.md に確定し、再検討しません。
4	API キーの確認。 Platform の場合は MEM0_API_KEY、OSS の場合は OPENAI_API_KEY。Platform でキーがない場合は、mem0 init --agent による Agent Mode を既定にします。	キーがない CI モードの場合は、コード 2 で終了します。
5	目標ドキュメント。 goal.md：保存する内容、取得するタイミングと理由、製品、委任するスキル、対象外の範囲。	必須ゲート。 明示的な承認が必要です。3 回却下された場合は、コード 3 で終了します。
6	統合計画。 呼び出し箇所と ID のソースを対象を絞って grep します。plan.md：書き込み／読み取りパターン、スコープ設定、呼び出し箇所、依存関係、維持する動作、共存方法、フィーチャーフラグ、ソース、E2E の実行手順。	必須ゲート。 妥当な追加呼び出し箇所がない場合、または 3 回却下された場合は、コード 5 で終了します。
7	テストを先に作成。 リポジトリ標準のフレームワークで、失敗する書き込みテストと読み取りテストを作成します。アサーションの形式は、標準のシグネチャから取り入れます。MEM0_API_KEY が未設定でもインポートできなければなりません。	テストは失敗しなければなりません。合格する場合は、テストが誤っています。
8	実装。 新しいコンテキストのサブエージェントを使用し、プロンプトは references/subagent-prompts.md に従います。plan.md と goal.md に照らしてレビューする差分が返されます。	レビューループを 3 回行い、その後コード 4 で終了します。
9	コミットと引き継ぎ。 ブランチ mem0-integrate/<slug> を使用し、依存関係、モジュール、接続、テストの 4 つに分けてコミットします。	--no-heal の場合はここで停止します。
10	自己修復ループ。 /mem0-test-integration --ci を実行し、失敗を分類し、範囲を限定した修正用サブエージェントを起動します。リグレッションが発生した場合は元に戻します。	既存テストの失敗がある場合は、停止してコード 6 で終了します。決して「修正」しないでください。

成果物（すべて .mem0-integration/ 内）

ファイル	目的	保持期間
repo-summary.md	リポジトリの理解とバックエンド候補のインターフェース（ステップ 2）。	実行間で保持します。
goal.md	承認済みの目的。ステップ 6 以降は書き換えません。	実行間で保持します。
plan.md	承認済みの仕組み（場所、方法、呼び出し箇所、維持する動作）。	実行間で保持します。
trace.jsonl	今回の実行におけるすべてのツール呼び出し、判断、サブエージェントとのやり取り。	実行ごとに上書きします。
diff.patch	レビュー可能なパッチとしての、コミット済み統合内容。	実行ごとに上書きします。
heal-trace.md	自己修復ループ（ステップ 10）の試行ごとの記録。	実行ごとに上書きします。
product.json	{"product": "platform"|"oss", "language": "...", "mem0_version": "...", "write_site": "file:line", "read_site": "file:line", "feature_flag": "MEM0_ENABLED", "preferred_site": "<surface index from step 2>"}。検証スキルで使用されます。	実行ごとに上書きします。

初回実行時に .mem0-integration/ を .gitignore に追加します。このディレクトリとリポジトリのソースツリー以外には何も書き込みません。

モード

モード	起動条件	動作
インタラクティブ（デフォルト）	TTY が存在し、MEM0_INTEGRATE_CI が未設定	キーの入力を求め、目的ドキュメントを確認し、推奨事項を表示します。
CI	MEM0_INTEGRATE_CI=1	キーを環境変数に設定する必要があります。--product が必要です。goal.md が存在する場合は、その内容を目的ドキュメントとして自動承認します。それ以外の場合は、すぐに失敗します。

実行

/mem0-integrate                            # インタラクティブ、自己修復 ON
/mem0-integrate --no-heal                  # コミット後に停止。手動で検証
/mem0-integrate --heal-max 5               # カテゴリごとの自己修復試行回数の上限（デフォルト 3）
/mem0-integrate --product platform         # プロダクトの確認を省略
/mem0-integrate --product oss
/mem0-integrate --ci                       # 非インタラクティブ（テストハーネス用）

終了コード

コード	意味
0	成功。フィーチャーブランチにコミット済みです。検証スキルを実行できます。
1	前提条件を満たしていません（リポジトリに未コミットの変更がある、言語を検出できないなど）。
2	CI モードで環境変数のキーが不足しています。
3	目的ドキュメントが 3 回以上却下されました。統合の仕様が不十分です。
4	サブエージェントのレビューループが 3 ラウンド以内に収束しませんでした。
5	統合計画が 3 回以上却下されたか、妥当な追加の呼び出し箇所が見つかりませんでした。
6	自己修復ループが収束しなかった、非侵襲性の違反が検出された、または既存のテストが失敗しました。

明示的に対象外

• リポジトリ内の適合箇所の調査。このスキルを実行する前に、Mem0 が役立つ場所を人が判断します。
• 既存のメモリ／セッション／状態管理システムの置き換え。常に機能フラグを付けて追加する方式にします。「統合の原則」を参照してください。
• 自己修復中であっても、既存のテストの変更。機能フラグを未設定にしても統合後に失敗するテストは、非侵襲性の違反であり、修正すべきバグではありません。
• Platform と OSS のどちらを使うかを黙って決めること。必ず推奨事項を添えて確認します。
• ブランチの切り替え、プッシュ、PR の作成。ローカルでコミットして停止します（または、自己修復ループに入る場合もローカルで実行します）。
• ストア間のデータ移行。問い合わせがあった場合は、migration/oss-to-platform のドキュメントを案内します。
• OSS のデフォルト LLM 以外のプロバイダー選択。カスタム LLM／埋め込みモデル／ベクトルストアが必要な場合は、components/* のドキュメントを案内し、新しいキーを使ってステップ 4 を再実行します。