mem0 Memory System

![Mem0 Logo](https://res.cloudinary.com/di7ctlowx/image/upload/v1741739911/mem0-logo_dlssjm.svg)

# @pinkpixel/mem0-mcp MCP 服务器 ✨

一个模型上下文协议 (MCP) 服务器，与 [Mem0.ai](https://mem0.ai/) 集成，为 LLM 提供持久记忆功能。它允许 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 全局安装该软件包：

```bash
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 存储库。

克隆存储库，安装依赖项，并构建服务器：

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

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

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

技术实现说明 🔧

高级 Mem0 API 参数

在使用带有 Mem0 API 的云存储模式时，您可以利用其他参数进行更复杂的内存管理。虽然未在工具模式中显式公开，但这些参数可以包含在添加记忆时的 metadata 对象中：

add_memory 的高级参数：

参数	类型	描述
metadata	object	存储有关记忆的附加上下文（例如，位置、时间、标识符）。这可用于在检索期间进行过滤。
includes	string	要包含在记忆中的特定偏好。
excludes	string	要从记忆中排除的特定偏好。
infer	boolean	是否推断记忆或直接存储消息（默认值：true）。
output_format	string	格式版本，v1.0（默认，已弃用）或 v1.1（推荐）。
custom_categories	object	具有名称和描述的类别列表。
custom_instructions	string	用于处理和组织记忆的项目特定指南。
immutable	boolean	记忆是否不可变（默认值：false）。
expiration_date	string	记忆何时过期（格式：YYYY-MM-DD）。
org_id	string	与此记忆关联的组织 ID。
project_id	string	与此记忆关联的项目 ID。
version	string	记忆版本（v1 已弃用，建议新应用程序使用 v2）。

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

{
  "content": "需要记住的重要信息",
  "userId": "user123",
  "sessionId": "project-abc",
  "metadata": {
    "includes": "重要的上下文",
    "excludes": "敏感数据",
    "immutable": true,
    "expiration_date": "2025-12-31",
    "custom_instructions": "优先考虑此记忆以用于财务问题",
    "version": "v2"
  }
}

search_memory 的高级参数：

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

参数	类型	描述
filters	object	具有逻辑运算符和比较条件的复杂过滤器
top_k	integer	要返回的顶部结果数（默认值：10）
fields	string[]	要包含在响应中的特定字段
rerank	boolean	是否重新排序记忆（默认值：false）
keyword_search	boolean	是否基于关键字搜索（默认值：false）
filter_memories	boolean	是否过滤记忆（默认值：false）
threshold	number	结果的最小相似度阈值（默认值：0.3）
org_id	string	用于过滤记忆的组织 ID
project_id	string	用于过滤记忆的项目 ID

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

运算符	描述
in	匹配指定的任何值
gte	大于或等于
lte	小于或等于
gt	大于
lt	小于
ne	不等于
icontains	不区分大小写的包含检查

使用带有 search_memory 工具的复杂过滤器的示例：

{
  "query": "Alice 的爱好是什么？",
  "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 库或我们自己的代码的日志调用
• 为 MCP 协议保留干净的 stdout
• 在进程退出时自动清理资源

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

环境变量

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

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

---

Made with ❤️ by Pink Pixel