# https://github.com/pinkpixel-dev/mem0-mcp 项目说明书
生成时间：2026-06-25 01:38:56 UTC
## 目录
- [Project Overview & System Architecture](#page-1)
- [Core Tools, Parameters & V3 Data Flow](#page-2)
- [Installation, Configuration & Deployment](#page-3)
- [Troubleshooting & Community FAQ](#page-4)
## Project Overview & System Architecture
### 相关页面
相关主题：[Core Tools, Parameters & V3 Data Flow](#page-2), [Installation, Configuration & Deployment](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md)
- [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md)
- [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md)
- [ROADMAP.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/ROADMAP.md)
- [MEMORY.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/MEMORY.md)
- [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md)
- [src/index.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/index.ts)
- [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts)
- [src/backends/base.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/base.ts)
- [src/backends/cloud.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/cloud.ts)
- [src/backends/supabase.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/supabase.ts)
- [src/backends/local.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/local.ts)
# 项目概览与系统架构
## 一、项目定位与目标
`mem0-mcp` 是一个基于 Model Context Protocol (MCP) 协议的服务器实现，作为 Mem0 记忆平台与支持 MCP 的 LLM 客户端（如 Cursor、RooCode、Claude Desktop 等）之间的桥梁。它通过标准化的 JSON-RPC 工具回调，让大语言模型能够以工具调用（tool call）的形式向 Mem0 写入、检索、更新与删除长期记忆，从而跨会话保持用户偏好与上下文。资料来源：[README.md:1-40]() [OVERVIEW.md:1-30]()
项目的核心依赖包含 `@modelcontextprotocol/sdk@1.29.0`（实现 MCP 服务端协议）与 `mem0ai@^3.0.10`（Mem0 官方 Node.js SDK），并且在 0.7.0 版本中完成了对 Mem0 Platform V3 异步管线的全面兼容。资料来源：[CHANGELOG.md:1-30]() [OVERVIEW.md:80-95]()
## 二、模块化后端适配器架构
为避免早期单体 `src/index.ts` 膨胀至上千行的可维护性问题，0.7.0 版本将系统重构为**后端适配器模式**（Backend Adapter Pattern）。整体架构如下图所示：
```mermaid
flowchart TB
Client[MCP 客户端
Cursor / RooCode / Claude] -->|JSON-RPC| Server[Mem0MCPServer
src/index.ts]
Server -->|register tools| Adapter{Backend Adapter}
Adapter -->|Platform V3| Cloud[CloudBackend
src/backends/cloud.ts]
Adapter -->|pgvector| Supabase[SupabaseBackend
src/backends/supabase.ts]
Adapter -->|in-memory| Local[LocalBackend
src/backends/local.ts]
Cloud --> Mem0API[(Mem0 Cloud V3 API)]
Supabase --> PG[(PostgreSQL + pgvector)]
Local --> RAM[(内存向量集合)]
```
- **`Mem0MCPServer`**：位于 [src/index.ts]()，负责注册 MCP 工具 schema、解析 JSON-RPC 请求并分发给后端；该类同时维护能力门控（capability gating），避免向模型暴露当前后端不支持的工具。
- **`MemoryBackend` 抽象基类**：定义在 [src/backends/base.ts]()，规定所有适配器必须实现的 `add / search / list / get / update / delete` 等契约方法以及能力声明接口。
- **`CloudBackend`**：[src/backends/cloud.ts]() 实现 Mem0 Platform V3 集成，包括 V3 特有的异步事件轮询、scope 实体参数到嵌套 `filters` 的映射，以及对 `userId / agentId / appId / runId` 的语义化处理。资料来源：[OVERVIEW.md:40-75]() [MEMORY.md:1-20]()
- **`SupabaseBackend`**：[src/backends/supabase.ts]() 通过 pgvector 自托管持久化存储。
- **`LocalBackend`**：[src/backends/local.ts]() 提供轻量级内存向量集合，仅供开发与测试。
数据契约（如 `AddResult`、`SearchResult`、`MemoryRecord`）集中在 [src/types.ts]()，保证多个适配器之间的类型一致性。
## 三、存储模式与配置
服务器通过环境变量选择运行模式，配置通常写入 MCP 客户端的 `mcp.json`：
| 存储模式 | 关键环境变量 | 适用场景 | 资料来源 |
| --- | --- | --- | --- |
| ☁️ Cloud | `MEM0_API_KEY`、`DEFAULT_USER_ID`、`DEFAULT_AGENT_ID`、`DEFAULT_APP_ID` | 生产环境，利用 Mem0 托管 V3 异步管线 | [OVERVIEW.md:100-130]() |
| 🗄️ Supabase | `SUPABASE_URL`、`SUPABASE_KEY`、`OPENAI_API_KEY` | 私有化自托管、pgvector 长期存储 | [OVERVIEW.md:130-145]() |
| 💾 Local | `OPENAI_API_KEY`（可选） | 单元测试与本地快速验证 | [OVERVIEW.md:145-160]() |
仓库附带 [config_generator.sh]() 交互式 Bash 脚本，可生成 `mcp.json` 并支持 Cursor 路径写入、剪贴板复制或全局 npm 安装方式。资料来源：[OVERVIEW.md:115-135]()
## 四、工具集与已知问题
当前注册到 MCP 的核心工具包括 `add_memory`、`search_memory`、`list_memories`、`get_memory`、`update_memory`、`delete_memory` 等。V3 写入为异步管线，因此 `CloudBackend` 内部实现了基于事件 ID 的轮询逻辑，调用方可显式传入 `waitForCompletion` / `timeoutMs` 控制等待时长。资料来源：[src/index.ts:1-60]() [CHANGELOG.md:5-25]()
社区反馈的重点问题与本架构紧密相关：
- **Issue #4 — `search_memory` 始终返回空数组**：因 V3 搜索要求实体 ID 必须嵌套在 `filters` 中而非顶层字段，0.7.0 在 Cloud 适配器中统一了 `userId / agentId / appId / runId` → `filters` 的映射逻辑。资料来源：[CHANGELOG.md:10-25]()（参见社区上下文 Issue #4）
- **Issue #6 — 仅在显式传 `userId` 时才生效**：提醒用户工具调用参数优先级高于环境变量默认，因此即便配置了 `DEFAULT_USER_ID`，也应在调用时显式传入以避免被其他 scope 覆盖。资料来源：[PARAMETER_GUIDE.md:1-30]()（参见社区上下文 Issue #6）
- **Issue #3 — `DEFAULT_USER_ID` 失效**：早期版本曾错误地尝试透传 `orgId` / `projectId`，实际上 Mem0 V3 中这两个字段由平台自动分配，用户应改用 `appId`（即 `app_id`）控制项目范围。资料来源：[CHANGELOG.md:45-65]() [PARAMETER_GUIDE.md:1-25]()（参见社区上下文 Issue #3）
- **Issue #2 — API Key 明文风险**：建议使用 `envFile` 方式引用密钥，避免将凭证直接写入 `mcp.json`（已 close）。资料来源：[社区上下文 Issue #2]()
- **Issue #1 — 客户端“找不到连接”**：通常发生在 `npx` 首次运行时未完成依赖拉取或 MCP 客户端未将服务加入 “Connected MCP Servers” 白名单，需重启客户端。资料来源：[社区上下文 Issue #1]()
## 五、路线图与未来演进
按 [ROADMAP.md]() 的规划：
- **Phase 1（已完成）**：V3 现代化、模块化适配器、异步轮询、scope 参数归一化以及新增的 `list_memories / get_memory / update_memory / get_memory_history / get_memory_capabilities`。
- **Phase 2（进行中）**：批量更新/删除工具（需显式 `confirm: true`）、记忆质量反馈（`rate_memory`）、事件查询（`get_memory_event / list_memory_events`）以及导出能力（`create_memory_export / get_memory_export`）。
- **Phase 3（计划）**：暴露云端项目级设置（如 memory decay）、SSE HTTP 传输支持、Webhook 管理工具。
资料来源：[ROADMAP.md:1-25]() [CHANGELOG.md:1-30]()
## See Also
- [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md) — 安装、配置与使用说明
- [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md) — 工具参数与 scope 字段权威指南
- [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) — 版本演进与缺陷修复历史
- [ROADMAP.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/ROADMAP.md) — 三阶段功能演进计划
- [MEMORY.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/MEMORY.md) — 关键架构决策日志（ADR）
---
## Core Tools, Parameters & V3 Data Flow
### 相关页面
相关主题：[Project Overview & System Architecture](#page-1), [Troubleshooting & Community FAQ](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md)
- [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md)
- [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md)
- [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md)
- [ROADMAP.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/ROADMAP.md)
- [update-server.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/update-server.md)
- [src/index.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/index.ts)
- [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts)
# 核心工具、参数与 V3 数据流
## 核心工具集
mem0-mcp 通过 [`src/index.ts`](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/index.ts) 中的 `ListToolsRequestSchema` 向 MCP 客户端注册一组记忆管理工具，覆盖写入、检索、列表、获取、更新与删除六类核心操作：`add_memory`、`search_memory`、`list_memories`、`get_memory`、`update_memory`、`delete_memory`。每条工具都附带 `inputSchema`，定义必填与可选字段，使模型调用具备严格的结构约束。其中 `add_memory` 接受字符串简写或消息数组，`search_memory` 支持 `threshold` 与 `topK` 等调参字段，`list_memories` 默认 `pageSize` 为 25 并允许通过 `filters` 进行复合过滤。
## 参数体系与作用域映射
工具参数分为三类：用户作用域、调用方标识与运行时控制。[`PARAMETER_GUIDE.md`](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md) 给出了权威映射：
- `userId` → `user_id`，终端用户标识
- `agentId` → `agent_id`，发起调用的 LLM 或智能体
- `appId` → `app_id`，控制项目作用域的核心字段
- `sessionId` / `runId` → `run_id`，会话或运行追踪
- `orgId` / `projectId` 由 Mem0 自动分配，不建议手动覆盖
工具参数优先级高于 `DEFAULT_USER_ID`、`DEFAULT_AGENT_ID`、`DEFAULT_APP_ID` 等环境变量默认值。[`src/types.ts`](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts) 中的 `ListInput` 接口是参数解析层的契约来源，定义了 `userId`、`agentId`、`appId`、`runId`、`filters`、`page`、`pageSize` 等字段；`AddResult` 将异步结果统一为 `status`、`eventId`、`memories` 三要素；`SearchResult` 与 `ListResult` 分别封装命中数组与分页结构。
## V3 数据流与异步轮询
自 0.7.0 版本起，单体文件被重构为模块化后端适配器架构，[`OVERVIEW.md`](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md) 描述了三类后端（Cloud / Supabase / Local）与 `MemoryBackend` 抽象契约。V3 数据流如下：
```mermaid
flowchart LR
A[MCP 客户端] -->|JSON-RPC 调用| B[mem0-mcp Server]
B --> C{MemoryBackend}
C -->|Cloud| D[Mem0 Cloud V3 API]
C -->|Supabase| E[pgvector PostgreSQL]
C -->|Local| F[内存存储]
D -->|eventId 异步回执| B
B -->|后台轮询 SUCCEEDED| A
```
关键变化：
1. **异步写入**：`add_memory` 调用后端立即返回 `eventId`，由 [`CHANGELOG.md`](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) 中提到的 `wait/poll` 轮询逻辑等待 `SUCCEEDED` 或 `FAILED` 状态，避免客户端在长耗时写入中阻塞。
2. **嵌套过滤器**：V3 搜索要求把作用域 ID 放入 `filters` 内部，而非作为顶层字段，[`update-server.md`](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/update-server.md) 明确指出 V3 使用 semantic + BM25 + entity 融合打分，老式的顶层字段会被忽略。
3. **结构化能力声明**：后端实现 `MemoryBackend` 抽象类，向 MCP 层报告当前支持的工具子集，实现 capability gating，使不同部署形态仅暴露必要的工具。
## 常见问题与社区反馈
- **Issue #4 / #6**：`search_memory` 早期版本始终返回空数组，修复后仅在显式传入 `userId` 时生效；环境变量中的 `DEFAULT_USER_ID` 不会自动注入到 V3 的嵌套 `filters` 中。
- **Issue #3**：`DEFAULT_USER_ID` / `ORG_ID` / `PROJECT_ID` 在云模式下不生效，因为 `org_id` 与 `project_id` 由 Mem0 自动分配，外部配置无法覆盖——这一点与 [`CHANGELOG.md`](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) 中 0.5.0 的“正确参数实现”条目一致。
- **Issue #2**：将 `MEM0_API_KEY` 直接写在 `mcp.json` 的 `env` 中存在泄露风险，推荐改用 `envFile` 或宿主级环境变量。
- **Issue #1**：通过 `cmd /c npx -y @pinkpixel/mem0-mcp` 调用时偶发 "No connection found"，多与客户端未将服务注册到已连接列表有关。
[`ROADMAP.md`](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/ROADMAP.md) 中规划的 Phase 2 / 3 将引入 `batch_update_memories`、`rate_memory`、`get_memory_event`、`list_memory_events` 以及导出能力，进一步丰富 V3 工具集，并为管理员暴露 cloud project settings 与 SSE HTTP 传输选项。
## 参见
- [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md)
- [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md)
- [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md)
- 社区 Issue #4、`#6`、`#3`、`#2`、`#1`
---
## Installation, Configuration & Deployment
### 相关页面
相关主题：[Project Overview & System Architecture](#page-1), [Troubleshooting & Community FAQ](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md)
- [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md)
- [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md)
- [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md)
- [config_generator.sh](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/config_generator.sh)
- [smithery.yaml](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/smithery.yaml)
- [glama.json](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/glama.json)
- [package.json](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/package.json)
- [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts)
# 安装、配置与部署
`mem0-mcp` 是一个基于 Model Context Protocol (MCP) 的内存服务器,通过 stdio 协议向 LLM 客户端(如 Cursor、Claude Desktop、RooCode 等)提供 `add_memory`、`search_memory`、`delete_memory` 等工具。本页聚焦于该服务器的安装、配置与部署流程,涵盖三种官方支持的安装方式、环境变量定义、客户端集成配置以及常见故障模式。
## 项目文件结构
在进入安装流程之前,有必要了解仓库的核心布局,特别是与部署直接相关的入口文件:
```
mem0-mcp/
├── src/
│ ├── index.ts # MCP Server 入口与工具注册
│ ├── types.ts # 共享 TypeScript 契约
│ └── backends/ # 适配器:cloud / supabase / local
├── build/ # 编译产物 (npm run build 生成)
├── config_generator.sh # 交互式 mcp.json 生成脚本
├── package.json # 依赖与脚本定义
├── smithery.yaml # Smithery 部署配置
├── glama.json # Glama MCP 注册清单
└── OVERVIEW.md / README.md
```
资料来源：[OVERVIEW.md:File Structure]()
## 三种安装方式
项目同时支持基于 `npx` 的快速安装、全局 npm 安装以及本地源码构建三种方式,用户可以根据客户端的兼容性与可调试性需求进行选择。
### 方式一:npx 快速运行(推荐)
通过 `npx` 直接拉取并执行 `@pinkpixel/mem0-mcp` 包,无需本地克隆与编译,适合绝大多数生产与日常使用场景。客户端配置中只需声明 `command: npx` 与 `args: ["-y", "@pinkpixel/mem0-mcp"]` 即可。
资料来源：[OVERVIEW.md:Installation & Usage]()
### 方式二:全局 npm 安装
执行 `npm install -g @pinkpixel/mem0-mcp` 之后,系统中可直接调用 `mem0-mcp` 命令。CHANGELOG 显示 v0.6.0 版本明确添加了 "global installation support with `mem0-mcp` command",使得命令行集成更加直接。配置示例可简化为 `"command": "mem0-mcp"`。
资料来源：[CHANGELOG.md:[0.6.0]]()
### 方式三:本地源码构建
面向贡献者与需要调试 MCP 协议的开发者:
```bash
git clone https://github.com/pinkpixel-dev/mem0-mcp
cd mem0-mcp
npm install
npm run build # 编译到 build/index.js
npm run watch # 文件变更自动重建
npm run inspector # 启动 MCP Inspector 调试器
```
构建产物路径为 `build/index.js`,Smithery 部署配置中即引用该路径:`(config) => ({ command: 'node', args: ['build/index.js'], ... })`。
资料来源：[smithery.yaml:startCommand]()
## 客户端配置与环境变量
服务器通过 MCP 客户端的 `mcp.json` 启动,配置核心由 `command`、`args`、`env` 三部分组成。环境变量决定运行时所选用的存储后端以及默认作用域。
| 环境变量 | 作用 | 是否必填 |
| --- | --- | --- |
| `MEM0_API_KEY` | 启用云端存储模式 (Mem0 Cloud V3) | 云端模式必填 |
| `SUPABASE_URL` / `SUPABASE_KEY` | 启用 Supabase 自托管模式 | 自托管模式必填 |
| `OPENAI_API_KEY` | Supabase/Local 模式下的向量嵌入 | 本地/Supabase 模式必填 |
| `DEFAULT_USER_ID` | 工具调用时缺省的 user 作用域 | 推荐填写 |
| `DEFAULT_AGENT_ID` | 缺省的 LLM/Agent 标识 | 可选 |
| `DEFAULT_APP_ID` | 缺省的应用/项目作用域 | 可选 |
典型的云端模式配置示例:
```json
{
"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"
},
"disabled": false,
"alwaysAllow": ["add_memory", "search_memory"]
}
}
}
```
工具参数优先级高于环境变量:即使在配置中设置了 `DEFAULT_USER_ID`,在 `add_memory` 或 `search_memory` 调用时显式传入 `userId` 也会覆盖默认值。这一行为在社区反馈中得到印证——修复 issue #4 后,用户必须显式传递 `userID` 才能让搜索结果返回内容。
资料来源：[PARAMETER_GUIDE.md:Parameter Mapping]()、[OVERVIEW.md:Configuration]()
### 交互式配置生成器
对于不熟悉手工编辑 `mcp.json` 的用户,仓库提供了 `config_generator.sh` Bash 脚本,提供带 ASCII 横幅的交互菜单,支持生成 Cursor IDE 配置、复制到剪贴板或写入自定义路径,并同时支持本地构建与 npm 包两种安装模式。
资料来源：[OVERVIEW.md:Interactive Configuration Generator]()
## 平台部署与注册清单
服务器可通过两类外部 MCP 注册平台被发现和分发:
- **Smithery**:通过 `smithery.yaml` 中的 JSON Schema 声明必需与可选配置项(`mem0ApiKey`、`defaultUserId`、`defaultAgentId`、`defaultAppId`),并以 `stdio` 协议启动 `node build/index.js`。
- **Glama**:通过 `glama.json` 注册维护者身份(`maintainers: ["sizzlebop"]`)。
资料来源：[smithery.yaml:configSchema]()、[glama.json:maintainers]()
下面给出部署与运行时配置的整体流程示意:
```mermaid
flowchart LR
A[MCP 客户端
Cursor/Claude/RooCode] -->|读取 mcp.json| B[启动命令]
B --> C{npx / 全局 / 本地}
C --> D[mem0-mcp 进程]
D --> E{后端选择}
E -->|MEM0_API_KEY| F[Cloud V3]
E -->|SUPABASE_URL/KEY| G[Supabase pgvector]
E -->|OPENAI_API_KEY| H[Local in-memory]
F --> I[add/search/delete_memory]
G --> I
H --> I
I -->|JSON-RPC over stdio| A
```
## 常见部署问题与排查
依据社区 issue 整理出三类高频部署故障:
1. **`search_memory` 始终返回空数组 (Issue #4)**:在 v0.6.x 之前的版本中,云端模式下缺少显式 `userId` 会导致搜索失败。该问题已在后续 npm 版本中修复,但仍要求调用方明确传递 `userId` 参数,即便配置中已设置 `DEFAULT_USER_ID`。
2. **`DEFAULT_USER_ID` 等环境变量未生效 (Issue #3)**:在 v0.5.0 之前,`orgId` 与 `projectId` 参数命名错误,因为 Mem0 后端的 `org_id` 与 `project_id` 由系统自动分配、用户无法覆盖。修复后,真正用于控制作用域的字段是 `appId`(映射到 `app_id`)与 `agentId`(映射到 `agent_id`)。
资料来源：[CHANGELOG.md:[0.5.0] - BREAKING CHANGE]()
3. **连接未识别 (Issue #1)** 与 **API Key 暴露风险 (Issue #2)**:前者通常由客户端未将 `mem0-mcp` 加入 "Connected MCP Servers" 列表或命令路径错误引起;后者建议通过 shell 环境变量或 CI Secret 注入,避免将明文密钥写入 `mcp.json`。在 Cursor 等客户端中,可在 `env` 字段中引用预定义变量以减少泄露风险。
资料来源：[README.md:Configuration]()、[PARAMETER_GUIDE.md:Recommended Usage Patterns]()
## See Also
- [工具与 API 参考](tools-api-reference.md)
- [存储后端适配器架构](backend-adapters.md)
- [参数与作用域指南](parameter-guide.md)
- [CHANGELOG 版本演进](changelog.md)
---
## Troubleshooting & Community FAQ
### 相关页面
相关主题：[Core Tools, Parameters & V3 Data Flow](#page-2), [Installation, Configuration & Deployment](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md)
- [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md)
- [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md)
- [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md)
- [update-server.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/update-server.md)
- [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts)
- [ROADMAP.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/ROADMAP.md)
# Troubleshooting & Community FAQ
本页汇总 `@pinkpixel/mem0-mcp` 在实际使用过程中最常见的故障现象、复现条件、根因分析与解决方案。所有条目均来自已记录的 GitHub Issue 与项目源码变更历史,便于读者在遇到类似症状时快速定位和修复。
## 1. 搜索类故障:search_memory 返回空数组
### 症状描述
`search_memory` 调用始终返回 `[]`,即使刚刚通过 `add_memory` 成功写入的条目也无法被检索到。`add_memory` 本身工作正常。
### 根因与修复记录
此问题在 v0.7.0 之前的版本中较为普遍,主要源于 Mem0 Platform V3 协议将搜索从纯向量相似度升级为「语义 + BM25 + 实体匹配」的融合打分,且要求实体 ID 嵌套在 `filters` 字段内而非顶层字段。`资料来源:[CHANGELOG.md:5-15]()`
修复后,Issue #6 的反馈进一步指出:**即使 `DEFAULT_USER_ID` 已在 `mcp.json` 中配置,搜索仍需在工具调用时显式传入 `userId` 参数**才能检索到匹配的记忆。这是 V3 协议对作用域过滤的强制要求。
### 推荐排查步骤
1. 确认 `@pinkpixel/mem0-mcp` 已升级至 `^0.7.0` 或更高版本。
2. 在 LLM 系统提示或调用规范中强制要求传入 `userId`(即便是默认值)。
3. 若仍为空,检查 `search_memory` 的 `filters` 结构是否符合 V3 嵌套格式。
## 2. 环境变量不生效:DEFAULT_USER_ID / ORG_ID / PROJECT_ID
### 症状描述
在 Cursor 或 Claude Desktop 的 `mcp.json` 中配置了 `DEFAULT_USER_ID`、`ORG_ID`、`PROJECT_ID` 等环境变量,但 Mem0 平台查询记录显示这些值并未生效。
### 根因分析
v0.5.0 的重大重构明确指出:**`org_id` 与 `project_id` 由 Mem0 平台自动分配,用户无法通过客户端强制覆盖**。真正控制用户作用域的正确参数是 `app_id`(对应 MCP 工具的 `appId`)。`资料来源:[CHANGELOG.md:40-55]()`
此外,v0.3.9 修复了从 `org_id`/`project_id`(snake_case)到 `organizationId`/`projectId`(camelCase)的命名映射错误,这也是早期版本环境变量失效的原因之一。
### 正确的参数映射表
| 工具参数 | Mem0 API 字段 | 用途说明 |
|----------|---------------|----------|
| `userId` | `user_id` | 用户标识 |
| `agentId` | `agent_id` | LLM/Agent 标识 |
| `appId` | `app_id` | **应用/项目作用域(替代错误的 projectId)** |
| `runId` | `run_id` | 会话/运行追踪 |
`资料来源:[PARAMETER_GUIDE.md:5-20]()`
## 3. 连接与启动故障
### 症状描述
MCP 客户端(如 RooCode、Cursor)报告:`No connection found for server: Memory Management`。服务器在某个时间点之前正常工作,之后突然断开。
### 常见排查路径
- **协议通信干扰**:MCP 通过 stdout 传输协议,任何写入 stdout 的库都会破坏连接。`资料来源:[OVERVIEW.md:85-95]()`。解决方案是 SafeLogger 仅将 `mem0ai` 与项目代码的日志重定向到 stderr。
- **npx 全局安装命令**:Windows 下推荐使用 `cmd /c npx -y @pinkpixel/mem0-mcp`;Linux/macOS 可直接 `npx -y @pinkpixel/mem0-mcp`。
- **重启与重建**:若使用本地构建,需依次执行 `npm install` → `npm run build`,然后重启 MCP 客户端。
## 4. 安全配置:避免 API Key 明文暴露
### 风险提示
直接在 `mcp.json` 的 `env` 字段写入 `MEM0_API_KEY` 会将该密钥明文保存至配置文件。仓库 Issue #2 建议改用 `envFile` 机制或客户端支持的密钥引用方案,以降低泄露风险。`资料来源:[README.md:55-75]()`
### 推荐做法
```jsonc
{
"mcpServers": {
"mem0-mcp": {
"command": "npx",
"args": ["-y", "@pinkpixel/mem0-mcp"],
"envFile": "${workspaceFolder}/.env.mem0"
}
}
}
```
同时建议在 `.gitignore` 中排除该 env 文件,并定期轮换 `MEM0_API_KEY`。
## 5. 诊断流程图
```mermaid
flowchart TD
A[工具调用失败] --> B{add_memory
是否成功?}
B -- 否 --> C[检查 MEM0_API_KEY
与后端初始化]
B -- 是 --> D{search_memory
是否返回空?}
D -- 是 --> E[确认 userId
显式传入]
E --> F{仍为空?}
F -- 是 --> G[升级至 v0.7.0+
检查 filters 嵌套格式]
F -- 否 --> H[问题解决]
D -- 否 --> I{环境变量
是否生效?}
I -- 否 --> J[使用 appId 替代
projectId]
J --> K[确认 camelCase 参数名]
I -- 是 --> L{客户端是否
能连接?}
L -- 否 --> M[检查 SafeLogger
stdout 干扰]
L -- 是 --> N[正常运行]
C --> O[检查 README 配置示例]
```
## 6. 常见问题速查表
| 问题编号 | 现象 | 关键修复版本 |
|----------|------|--------------|
| #1 | 连接断开 / No connection found | SafeLogger stdout 隔离 |
| #2 | API Key 明文风险 | 改用 `envFile` |
| #3 | DEFAULT_USER_ID 无效 | v0.5.0 参数重构 |
| #4 | search_memory 返回空 | v0.7.0 V3 协议适配 |
| #6 | 搜索需显式传 userId | V3 filters 嵌套要求 |
`资料来源:[update-server.md:30-80]()` 中规划的 `get_memory_capabilities` 工具将进一步帮助客户端在运行期查询当前后端支持的特性集,从而减少类似 Issue #4/#6 的排查成本。
## See Also
- [Parameter Configuration Guide](PARAMETER_GUIDE.md) — 完整的参数映射与作用域示例
- [Changelog & Version History](CHANGELOG.md) — 各版本的破坏性变更说明
- [Architecture Overview](OVERVIEW.md) — SafeLogger 与多后端适配器原理
- [Platform V3 Update Plan](update-server.md) — 即将引入的高级工具与兼容策略
---
---
## Doramagic 踩坑日志
项目：pinkpixel-dev/mem0-mcp
摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Hi @sizzlebop ! 👋。
## 1. 安装坑 · 来源证据：Hi @sizzlebop ! 👋
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Hi @sizzlebop ! 👋
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/pinkpixel-dev/mem0-mcp/issues/6 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/pinkpixel-dev/mem0-mcp | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/pinkpixel-dev/mem0-mcp | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/pinkpixel-dev/mem0-mcp | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/pinkpixel-dev/mem0-mcp | no_demo; severity=medium
## 6. 安全/权限坑 · 来源证据：Providing API keys in mcp file is not a good security practice
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Providing API keys in mcp file is not a good security practice
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/pinkpixel-dev/mem0-mcp/issues/2 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 7. 安全/权限坑 · 来源证据：search_memory Always Returns Empty Arrays
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：search_memory Always Returns Empty Arrays
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/pinkpixel-dev/mem0-mcp/issues/4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 8. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/pinkpixel-dev/mem0-mcp | issue_or_pr_quality=unknown
## 9. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/pinkpixel-dev/mem0-mcp | release_recency=unknown