Mem0 Mcp

@pinkpixel/mem0-mcp MCP サーバー ✨

Mem0.ai と連携し、LLM に永続的なメモリ機能を提供する Model Context Protocol（MCP）サーバーです。AI エージェントはセッションをまたいで情報を保存・取得できます。

このサーバーは、主要な機能に mem0ai Node.js SDK を使用しています。

機能 🧠

最新化・高度化されたツール（v0.8.0）

• add_memory：テキストコンテンツまたは構造化メッセージ配列からメモリーを保存します。
  • 入力： content（文字列）または messages（ロール／コンテンツオブジェクトの配列）、userId（文字列）、runId／sessionId（文字列）、agentId（文字列）、appId（文字列）、metadata（オブジェクト）、infer（ブール値）、customInstructions（文字列）、waitForCompletion（ブール値、デフォルト：true）、timeoutMs（数値、デフォルト：15000）
  • 動作： Cloud V3 での追加は非同期で行われます。デフォルトでは、このツールはバックグラウンドキューの処理が完了するまでポーリングします。waitForCompletion: false を指定すると、eventId をすぐに取得できます。
• search_memories：セマンティック検索と BM25 を組み合わせたフィルターを使用してメモリーを検索します。
  • 入力： query（文字列）、userId（文字列）、runId／sessionId（文字列）、agentId（文字列）、appId（文字列）、filters（オブジェクト）、threshold（数値）、topK（数値）、rerank（ブール値）、referenceDate（文字列）
  • 動作： API の検証エラーを防ぐため、スコープ変数を V3 の filters ブロック内に自動的にネストします。
• search_memory：後方互換性のための search_memories のエイリアスです。
• list_memories：識別子でスコープを指定したメモリーレコードをページ分割して一覧表示します。
  • 入力： userId（文字列）、runId／sessionId（文字列）、agentId（文字列）、appId（文字列）、filters（オブジェクト）、page（数値）、pageSize（数値）
• get_memory：ID で単一のメモリーレコードを取得します。
  • 入力： memoryId（文字列）
• update_memory：既存のメモリーのテキストまたはメタデータを変更します。
  • 入力： memoryId（文字列）、text（文字列）、metadata（オブジェクト）
• delete_memory：ID で指定したメモリーレコードを削除します。
  • 入力： memoryId（文字列）
• get_memory_history：メモリーの改訂履歴を取得します（クラウドのみ）。
  • 入力： memoryId（文字列）
• get_memory_capabilities：アクティブなバックエンドストレージモードの機能一覧とサポート状況を公開します。
  • 入力： なし
• batch_update_memories：複数のメモリーのテキストコンテンツを一括更新します（クラウドのみ）。
  • 入力： updates（{ memoryId: string, text: string } オブジェクトの配列）
• batch_delete_memories：複数のメモリーを一括削除します。
  • 入力： memoryIds（文字列の配列）、confirm（ブール値、実行するには true が必要）
• rate_memory：メモリーレコードの品質評価フィードバックを送信します（クラウドのみ）。
  • 入力： memoryId（文字列）、feedback（文字列：positive、negative、very_negative）、reason（文字列、任意）
• get_memory_event：特定のバックグラウンドイベントジョブの詳細を手動で取得します（クラウドのみ）。
  • 入力： eventId（文字列）
• list_memory_events：バックグラウンドでのメモリー処理イベントの履歴ログを一覧表示します（クラウドのみ）。
  • 入力： page（数値）、pageSize（数値）
• create_memory_export：非同期のメモリーエクスポートクエリジョブを開始します（クラウドのみ）。
  • 入力： schema（オブジェクト）、filters（オブジェクト、任意）、exportInstructions（文字列、任意）
• get_memory_export：メモリーエクスポートジョブのステータスとダウンロードメタデータを取得します（クラウドのみ）。
  • 入力： exportId（文字列）

前提条件 🔑

このサーバーでは、3 つのストレージモードがサポートされています。

1. クラウドストレージモード ☁️（本番環境での使用を推奨）

   • Mem0 API キーが必要です（MEM0_API_KEY 環境変数として指定）
   • メモリは Mem0 のクラウドサーバーに永続的に保存されます
   • ローカルデータベースは不要です
   • 高度なフィルタリングと検索を含むすべての機能が利用できます

2. Supabase ストレージモード 🗄️（セルフホストでの使用を推奨）

   • Supabase の認証情報が必要です（SUPABASE_URL と SUPABASE_KEY 環境変数）
   • エンベディングにはOpenAI API キーが必要です（OPENAI_API_KEY 環境変数）
   • メモリは Supabase データベースに永続的に保存されます
   • 無料プランがあり、セルフホストも可能です
   • 初期データベースのセットアップが必要です（SQL マイグレーションは以下に記載）

3. ローカルストレージモード 💾（開発／テスト専用）

   • OpenAI API キーが必要です（OPENAI_API_KEY 環境変数として指定）
   • メモリはインメモリのベクトルデータベースに保存されます（デフォルトでは永続化されません）
   • 永続ストレージを設定しない限り、サーバーの再起動時にデータが失われます

インストールと設定 ⚙️

このサーバーは、主に 3 つの方法で実行できます。

Smithery 経由でインストール

Smithery 経由で、Claude Desktop 用の Mem0 Memory Server を自動的にインストールするには：

npx -y @smithery/cli install @pinkpixel-dev/mem0-mcp-server --client claude

1. グローバルインストール（頻繁に使用する場合に推奨）

パッケージをグローバルにインストールし、mem0-mcp コマンドを使用します。

npm install -g @pinkpixel/mem0-mcp

グローバルインストール後、サーバーを直接実行できます。

mem0-mcp

グローバルコマンドを使用するように MCP クライアントを設定します。

クラウドストレージの設定（グローバルインストール）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase ストレージの設定（グローバルインストール）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

ローカルストレージの設定（グローバルインストール）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

2. npx の使用（ときどき使用する場合に推奨）

npx を使用してサーバーを実行するよう、MCP クライアント（Claude Desktop、Cursor、Cline、Roo Code など）を設定します。

クラウドストレージの設定（npx）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase ストレージの設定（npx）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

ローカルストレージの設定（npx）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

3. クローンしたリポジトリから実行

注：この方法では、最初にリポジトリを git clone する必要があります。

リポジトリをクローンし、依存関係をインストールして、サーバーをビルドします。

git clone https://github.com/pinkpixel-dev/mem0-mcp
cd mem0-mcp
npm install
npm run build

次に、ビルド済みのスクリプトを node で直接実行するよう、MCP クライアントを設定します。

クラウドストレージの設定（クローンしたリポジトリ）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase ストレージの設定（クローンしたリポジトリ）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

ローカルストレージの設定（クローンしたリポジトリ）

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory",
        "delete_memory"
      ]
    }
  }
}

重要事項：

1. /absolute/path/to/mem0-mcp/ を、クローンしたリポジトリの実際の絶対パスに置き換えてください
2. src/index.ts ファイルではなく、build/index.js ファイルを使用してください
3. MCP サーバーのプロトコル通信にはクリーンな stdout が必要です。stdout に書き込むライブラリやコードは、プロトコルに干渉する可能性があります

Supabase のセットアップ 🗄️

Supabase ストレージモードを使用する場合は、必要なテーブルを作成して Supabase データベースをセットアップする必要があります。

1. Supabase プロジェクトの作成

1. supabase.com にアクセスし、新しいプロジェクトを作成します
2. プロジェクト設定で、プロジェクト URL と anon キーを確認します

2. SQL マイグレーションの実行

Supabase SQL エディターで、以下の SQL コマンドを実行します。

-- Enable the vector extension
create extension if not exists vector;

-- Create the memories table
create table if not exists memories (
  id text primary key,
  embedding vector(1536),
  metadata jsonb,
  created_at timestamp with time zone default timezone('utc', now()),
  updated_at timestamp with time zone default timezone('utc', now())
);

-- Create the vector similarity search function
create or replace function match_vectors(
  query_embedding vector(1536),
  match_count int,
  filter jsonb default '{}'::jsonb
)
returns table (
  id text,
  similarity float,
  metadata jsonb
)
language plpgsql
as $$
begin
  return query
  select
    t.id::text,
    1 - (t.embedding <=> query_embedding) as similarity,
    t.metadata
  from memories t
  where case
    when filter::text = '{}'::text then true
    else t.metadata @> filter
  end
  order by t.embedding <=> query_embedding
  limit match_count;
end;
$$;

-- Create the memory_history table for history tracking
create table if not exists memory_history (
  id text primary key,
  memory_id text not null,
  previous_value text,
  new_value text,
  action text not null,
  created_at timestamp with time zone default timezone('utc', now()),
  updated_at timestamp with time zone,
  is_deleted integer default 0
);

3. 環境変数の設定

これらを MCP の設定に追加します。

• SUPABASE_URL：Supabase プロジェクトの URL（例：https://your-project.supabase.co）
• SUPABASE_KEY：Supabase の anon キー
• OPENAI_API_KEY：OpenAI API キー（エンベディング用）

Supabase モードのメリット

✅ 永続ストレージ — サーバーを再起動してもデータが保持されます ✅ 無料プランあり — 開発に使える充実した無料プラン ✅ セルフホスト可能 — 独自の Supabase インスタンスを実行できます ✅ スケーラブル — ニーズに応じて拡張できます ✅ SQL アクセス — 高度なクエリ向けにデータベースへ直接アクセスできます ✅ リアルタイム機能 — リアルタイムサブスクリプションが組み込まれています

パラメーター設定 🎯

Mem0 のパラメーターについて

サーバーでは、メモリを整理してスコープを設定するために、4 つの主要なパラメーターを使用します。

1. userId - ユーザーを識別します（必須）
2. agentId - ツール呼び出しを行う LLM／エージェントを識別します（任意）
3. appId - ユーザーのプロジェクト／アプリケーションを識別します - プロジェクトのスコープはこの値で決まります！（任意）
4. sessionId - 会話セッションを識別します（Mem0 の run_id に対応します）（任意）

環境変数のフォールバック 🔄

MCP サーバーは、ユーザーの識別とプロジェクト設定に環境変数のフォールバックをサポートしています。

• DEFAULT_USER_ID：ツール呼び出しで指定されていない場合に使用するフォールバックのユーザー ID
• DEFAULT_AGENT_ID：LLM／エージェントの識別に使用するフォールバックのエージェント ID
• DEFAULT_APP_ID：プロジェクトのスコープ設定に使用するフォールバックのアプリ ID

優先順位（重要！）

1. ツールパラメーター（最優先） - ツール呼び出しで LLM が指定する値
2. 環境変数（フォールバック） - MCP の設定から取得する値

動作例：

// Your MCP config
"env": {
  "DEFAULT_USER_ID": "john-doe",
  "DEFAULT_AGENT_ID": "my-assistant",
  "DEFAULT_APP_ID": "my-project"
}

LLM がパラメーターを指定した場合：

{
  "tool": "add_memory",
  "arguments": {
    "content": "Remember this",
    "userId": "session-123",        // ← Overrides DEFAULT_USER_ID
    "agentId": "different-agent",   // ← Overrides DEFAULT_AGENT_ID
    "appId": "special-project"      // ← Overrides DEFAULT_APP_ID
    // sessionId omitted           // ← No fallback, will be undefined
  }
}

結果：session-123、different-agent、special-project が使用されます

LLM がパラメーターを省略した場合：

{
  "tool": "add_memory",
  "arguments": {
    "content": "Remember this"
    // All IDs omitted - uses environment variables
  }
}

結果：john-doe、my-assistant、my-project が使用されます

LLM の動作の制御

環境変数が確実に使用されるように、LLM に次のように指示してください。

• 「環境に設定されているデフォルトのユーザー ID を使用してください」
• 「userId、agentId、appId のパラメーターを指定しないでください」
• 「設定済みのデフォルト値をサーバーに使用させてください」

システムプロンプトの推奨事項

最良の結果を得るには、システムプロンプトに次のような指示を含めてください。

When creating memories, use:
- agentId: "my-assistant"
- appId: "my-project"
- sessionId: "current-conversation-id"

DEFAULT_USER_ID を使用した設定例：

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "ORG_ID": "your-org-id",
        "PROJECT_ID": "your-project-id"
      }
    }
  }
}

または、node で直接実行する場合：

git clone https://github.com/pinkpixel-dev/mem0-mcp
cd mem0-mcp
npm install
npm run build

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

ストレージモードの比較 🔄

クラウドストレージ（Mem0 API）☁️

• デフォルトで永続化 - メモリはセッション間やサーバーの再起動後も利用できます
• ローカルデータベースは不要 - すべてのデータは Mem0 のサーバーに保存されます
• 検索品質の向上 - Mem0 の最適化された検索アルゴリズムを使用します
• 追加フィールド - agent_id および threshold パラメーターをサポートします
• 完全マネージド - セットアップやメンテナンスは不要です
• 必要なもの - Mem0 API キー

Supabase ストレージ 🗄️

• 永続ストレージ - データは Supabase の PostgreSQL データベースに保存されます
• 無料プランあり - 開発や小規模プロジェクト向けの充実した無料プランを利用できます
• セルフホスト可能 - 完全な制御を実現するため、独自の Supabase インスタンスを実行できます
• SQL アクセス - 高度なクエリや分析のためにデータベースへ直接アクセスできます
• スケーラブル - 無料プランからエンタープライズまで、ニーズに応じて拡張できます
• ベクトル検索 - 効率的な類似検索に pgvector 拡張機能を使用します
• リアルタイム機能 - リアルタイムサブスクリプションと Webhook を組み込みで利用できます
• 必要なもの - Supabase プロジェクトのセットアップと、埋め込み用の OpenAI API キー

ローカルストレージ（OpenAI API）💾

• デフォルトではメモリ内に保存 - データは RAM にのみ保存され、長期的には永続化されません。一部のキャッシュが行われる場合もありますが、永続ストレージとしては使用しないでください。
• データ損失のリスク - サーバーの再起動、システムの再起動、またはプロセスの終了時にメモリデータが失われます
• 推奨用途 - 開発、テスト、または一時的な使用に限ります
• 永続ストレージが必要な場合 - 信頼性の高い長期メモリが必要な場合は、クラウドストレージまたは Supabase のオプションを使用してください
• OpenAI の埋め込みを使用 - ベクトル検索機能に使用します
• 自己完結型 - すべてのデータはマシン上に保存されます
• 必要なもの - OpenAI API キー

開発 💻

リポジトリをクローンし、依存関係をインストールします。

git clone https://github.com/pinkpixel-dev/mem0-mcp
cd mem0-mcp
npm install

サーバーをビルドします。

npm run build

ファイルの変更時に自動で再ビルドする開発モードの場合：

npm run watch

デバッグ 🐞

MCP サーバーは stdio 経由で通信するため、デバッグが難しい場合があります。次の方法をお試しください。

1. MCP Inspector を使用する：このツールで MCP プロトコルの通信を監視できます。

npm run inspector

2. コンソールへのログ出力：コンソールログを追加する場合は、MCP プロトコルへの干渉を避けるため、必ず console.log() ではなく console.error() を使用してください。

3. 環境ファイル：ローカル開発では .env ファイルを使用すると、API キーやその他の設定オプションを簡単に設定できます。

技術的な実装に関する注意事項 🔧

1. Platform V3 の非同期追加とポーリング

Mem0 Cloud V3 への追加は、非同期のバックグラウンドタスクです。add_memory を呼び出すと、サーバーはリクエストを /v3/memories/add/ に送信し、eventId を受け取ります。

• **同期ポーリング（デフォルト）：**サーバーは、ステータスが SUCCEEDED または FAILED になるまで、イベントステータスエンドポイント（/v1/event/{id}/）を 500ms ごとに、最大 timeoutMs（デフォルトは 15000ms）ポーリングします。解決されると、最終結果を返します。
• **非同期実行：**ポーリングを省略するには、"waitForCompletion": false を渡します。サーバーは直ちに eventId と PENDING ステータスを返します。

2. ネストされた V3 フィルターの正規化

Mem0 Cloud V3 の検索および一覧取得エンドポイントは、トップレベルのスコープ ID（user_id、agent_id、app_id、run_id）を受け付けず、HTTP 400 エラーを返します。V3 では、これらのフィールドをネストされた filters オブジェクト内に指定する必要があります。 クライアント設定に影響が出ないよう、このサーバーはトップレベルのスコープ変数（userId、agentId、appId、runId／sessionId）を自動的に正規化し、API リクエストの送信前に内部でネストされた filters オブジェクトに統合します。

3. 機能の対応状況

バックエンドによって、対応する機能は異なります。get_memory_capabilities を呼び出すと、アクティブなバックエンドの機能マトリックスを構造化された形式で取得できます。

• **クラウドモード：**すべての機能に完全対応しています（apiVersion: "v3"、非同期イベント、一覧取得、監査履歴、論理クエリ）。
• **Supabase／ローカルモード：**標準の V1 ベクトルインターフェースを使用します。クラウド固有の未対応ツール（get_memory_history や list_memories など）は、機能が利用できないことを明確に示すメッセージとともに、エラーを適切に返します。

4. ロギングとプロトコルの安定性

MCP サーバーは、stdout 上で JSON-RPC を使用して通信します。予期しないライブラリのログが stdout に出力されると、プロトコルの通信チャネルが破損し、クライアントがクラッシュする原因になります。 このサーバーは、標準的なロギングを確実に抑制またはリダイレクトし、stdio 通信をクリーンに保つため、console.log などのデフォルトの console 出力メソッドを上書きします。

---

💖 Pink Pixel によって作成されました