@pinkpixel/mem0-mcp MCP 服务器 ✨

这是一个与 Mem0.ai 集成的模型上下文协议（MCP）服务器，为大型语言模型（LLMs）提供持久内存功能。它允许AI代理在会话之间存储和检索信息。

该服务器使用 mem0ai Node.js SDK 来实现其核心功能。

特性 🧠

工具

• add_memory: 将一段文本内容作为特定 userId 的记忆存储。
  • 输入: content (字符串, 必需), userId (字符串, 必需), sessionId (字符串, 可选), agentId (字符串, 可选), metadata (对象, 可选)
  • 存储提供的文本，以便在未来交互中能够回忆起。
• search_memory: 基于自然语言查询搜索特定 userId 的已存储记忆。
  • 输入: query (字符串, 必需), userId (字符串, 必需), sessionId (字符串, 可选), agentId (字符串, 可选), filters (对象, 可选), threshold (数字, 可选)
  • 根据语义相似度检索相关记忆。
• delete_memory: 通过ID从存储中删除特定的记忆。
  • 输入: memoryId (字符串, 必需), userId (字符串, 必需), sessionId (字符串, 可选), agentId (字符串, 可选)
  • 永久移除指定的记忆。
  • 根据语义相似度检索相关记忆。

先决条件 🔑

此服务器支持两种存储模式：

1. 云存储模式 ☁️ (推荐)

   • 需要一个 Mem0 API 密钥 (以 MEM0_API_KEY 环境变量形式提供)
   • 记忆将持久保存在 Mem0 的云端服务器上
   • 不需要本地数据库

2. 本地存储模式 💾

   • 需要一个 OpenAI API 密钥 (以 OPENAI_API_KEY 环境变量形式提供)
   • 记忆存储在一个内存向量数据库中 (默认情况下是非持久性的)
   • 除非配置为持久存储，否则当服务器重启时数据将会丢失

安装与配置 ⚙️

你可以通过以下两种主要方式运行此服务器：

1. 使用 npx (快速使用的推荐方法)

使用 npm 全局安装包：

npm install -g @pinkpixel/mem0-mcp

配置你的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"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

注意： 将 "YOUR_MEM0_API_KEY_HERE" 替换为您的实际Mem0 API密钥。

本地存储配置 (备选方案)

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

注意： 将 "YOUR_OPENAI_API_KEY_HERE" 替换为您的实际OpenAI API密钥。

2. 从克隆仓库运行

注意：这种方法需要您先克隆仓库。

克隆仓库、安装依赖项并构建服务器：

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

然后，配置您的MCP客户端直接使用 node 运行构建好的脚本：

{
  "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"
        // OR use "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE" for local storage
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

重要提示：

1. 将 /absolute/path/to/mem0-mcp/ 替换为克隆仓库的实际绝对路径
2. 使用 build/index.js 文件，而不是 src/index.ts 文件
3. MCP 服务器需要干净的 stdout 进行协议通信 - 任何写入 stdout 的库或代码都可能干扰协议

默认用户 ID（可选回退）

add_memory 和 search_memory 工具都需要一个 userId 参数来将记忆与特定用户关联。

为了在测试期间或单用户场景中的方便，您可以在启动服务器时选择设置 DEFAULT_USER_ID 环境变量。如果设置了此变量，并且在调用 search_memory 工具时省略了 userId 参数，服务器将使用 DEFAULT_USER_ID 的值进行搜索。

**注意：**虽然存在这种回退机制，但通常建议调用代理（LLM）明确提供正确的 userId 来添加和搜索记忆以避免歧义。

使用 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" 
      },
    }
  }
}

或者直接使用 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" 
      },
    }
  }
}

云存储 vs 本地存储 🔄

云存储（Mem0 API）

• 默认持久化 - 您的记忆将在会话之间和服务器重启后仍然可用
• 不需要本地数据库 - 所有数据存储在 Mem0 的服务器上
• 更高的检索质量 - 使用 Mem0 优化的搜索算法
• 附加字段 - 支持 agent_id 和 threshold 参数
• 要求 - 需要 Mem0 API 密钥

本地存储（OpenAI API）

• 默认内存中存储 - 数据仅存储在 RAM 中，不支持长期持久化。尽管可能会有一些缓存发生，但不应依赖于此作为永久存储。
• 数据丢失风险 - 在服务器重启、系统重启或进程终止时，记忆数据将会丢失
• 推荐用于 - 仅开发、测试或临时使用
• 对于持久化存储 - 如果需要可靠的长期记忆，请使用带有 Mem0 API 的云存储选项
• 使用 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

1. 控制台日志记录：当添加控制台日志时，始终使用 console.error() 而不是 console.log() 以避免干扰 MCP 协议

2. 环境文件：使用 .env 文件进行本地开发，以简化设置 API 密钥和其他配置选项

技术实现说明 🔧

高级 Mem0 API 参数

当使用Mem0 API的云存储模式时，您可以利用额外的参数来进行更复杂的内存管理。虽然这些参数在工具架构中没有明确列出，但可以在添加记忆时包含在metadata对象中。

add_memory 的高级参数：

要与MCP服务器一起使用这些参数，请在调用add_memory工具时将它们包含在您的元数据对象中。例如：

{
  "content": "Important information to remember",
  "userId": "user123",
  "sessionId": "project-abc",
  "metadata": {
    "includes": "important context",
    "excludes": "sensitive data",
    "immutable": true,
    "expiration_date": "2025-12-31",
    "custom_instructions": "Prioritize this memory for financial questions",
    "version": "v2"
  }
}

search_memory 的高级参数：

Mem0 v2搜索API提供了强大的过滤功能，可以通过filters参数来利用这些功能：

filters参数支持复杂的逻辑操作（AND, OR）和各种比较运算符：

使用复杂过滤器与search_memory工具的例子：

{
  "query": "What are Alice's hobbies?",
  "userId": "user123",
  "filters": {
    "AND": [
      {
        "user_id": "alice"
      },
      {
        "agent_id": {"in": ["travel-agent", "sports-agent"]}
      }
    ]
  },
  "threshold": 0.5,
  "top_k": 5
}

这将搜索与 Alice 的爱好相关的记忆，其中 user_id 为 "alice" 并且 agent_id 为 "travel-agent" 或 "sports-agent"，最多返回 5 个结果，并且相似度分数至少为 0.5。

有关这些参数的更多详细信息，请参阅 Mem0 API 文档。

SafeLogger

MCP 服务器实现了一个 SafeLogger 类，该类有选择地将 mem0ai 库中的 console.log 调用重定向到 stderr，而不会干扰 MCP 协议：

• 拦截 console.log 调用并检查堆栈跟踪以确定来源
• 仅重定向来自 mem0ai 库或我们自己代码的日志调用
• 保持干净的 stdout 用于 MCP 协议通信
• 在进程退出时自动清理资源

这允许在 MCP 客户端中正常运行，同时保留有用的调试信息。

环境变量

服务器识别几个控制其行为的环境变量：

• MEM0_API_KEY：云存储模式的 API 密钥
• OPENAI_API_KEY：本地存储模式（嵌入）的 API 密钥
• DEFAULT_USER_ID：内存操作的默认用户 ID

由 Pink Pixel 用心制作 ❤️