内容
# mem0-mcp
自托管代理内存：一个薄的 **stdio MCP 桥接器** 到 [mem0](https://github.com/mem0ai/mem0)
开源服务器，加上 **`共享内存` 技能** ，教导代理如何使用它。
两部分：
- `src/` — MCP 桥接器 (`mem0-bridge-mcp`)，一个小型 TypeScript/Bun stdio 服务器。
- `skills/shared-memory/` — 学科技能（在重新推导之前回忆，存储持久事实）。
规格驱动开发（SDD），使用 Claude Fable 编码。
## 后端
桥接器与任何自托管的 mem0 开源服务器（FastAPI + Postgres/pgvector）通信，通过
`MEM0_API_URL` / `MEM0_API_KEY` 配置。记忆按 mem0 的 `run_id` 分隔范围：一个自动推导的
**项目** 范围（git 远程仓库名称，否则 git 顶级 / cwd）加上一个保留的 **全局** 范围
用于跨项目事实。默认搜索合并项目 + 全局。
对于调和添加和问题重写功能，服务器需要一个 LLM 和一个嵌入器
（任何 OpenAI 兼容的端点）。为了防止事实提取将技术事实重写为第三人称散文，
请在 mem0 服务器上设置 `custom_instructions` 提示（参见 mem0 文档）。
## 工具
| 工具 | 用途 |
|---|---|
| `memory_add(text, scope?)` | 存储一个持久事实；mem0 提取 + 调和它（去重 / 更新 / 删除），结果报告更改内容 |
| `memory_search(query, scope?, limit?)` | 语义回忆（`project` = 项目 + 全局合并，`global`，`all`） |
| `memory_list(scope?, limit?)` | 列出一个范围（服务器限制页面；使用搜索进行回忆） |
| `memory_update(memory_id, text)` | 通过 UUID 重写一个记忆 |
| `memory_delete(memory_id)` | 通过 UUID 删除一个记忆；不暴露批量删除 |
| `memory_reset(reset_token)` | 不可逆转地清除整个存储；令牌门控（见下文） |
破坏性安全：`memory_id` 在任何请求之前验证为 UUID，并且永远不会
遵循重定向（否则，带有斜线的 307 重定向可能会将 DELETE 重定向到服务器的删除所有路由）。
`memory_reset` 仅在发送 `X-Reset-Token` 作为 `X-Reset-Token` 时有效；
该令牌仅由人类用户知道，因此代理必须在每次重置之前请求它，并且永远不能自行清除存储。
请求在 10 秒后超时（添加 45 秒后，因为 `infer:true` 运行两个 LLM 调用）。
搜索/列表命中显示为每条记忆一行，用制表符分隔：`id score age text`。年龄
（`<1h`，`5h`，`3d`，`2mo`，来自 `updated_at`/`created_at`）使回忆时过时内容可见。
结果按时间加权分数重新排序（半衰期 90 天，底线 0.6），因此新鲜事实优先于同等相关性的过时事实，
而不会隐藏强匹配的旧条目。
**问题样式回忆（HyDE-lite）：** 在搜索之前，问题查询由 LLM 重写为一个简短的声明性陈述，
并与原始查询一起搜索（答案到答案匹配）。尽力而为：如果 LLM 被禁用、无法访问或速度慢，
搜索会静默地回退到原始查询，并且永远不会阻塞。
## 配置（环境变量）
| 变量 | 默认值 | 备注 |
|---|---|---|
| `MEM0_API_URL` | `http://localhost:8000` | mem0 开源服务器基准 URL |
| `MEM0_API_KEY` | 未设置 | 设置时作为 `X-API-Key` 发送 |
| `MEM0_DEFAULT_USER_ID` | `default` | mem0 `user_id` 所有者范围 |
| `MEM0_INSECURE_TLS` | 未设置 | `1` = 跳过自签名证书的 TLS 验证；优先使用 `NODE_EXTRA_CA_CERTS` |
| `MEM0_INFER` | `1` | `0` = 逐字存储文本，跳过 mem0 的提取 + 调和管道 |
| `MEM0_QUERY_REWRITE` | `1` | `0` = 禁用 HyDE-lite 查询重写 |
| `MEM0_REWRITE_BASE_URL` | 未设置 | OpenAI 兼容聊天基准 URL，用于重写；重写在设置前保持关闭 |
| `MEM0_REWRITE_MODEL` | 未设置 | 重写器的聊天模型 ID；重写在设置前保持关闭 |
| `MEM0_REWRITE_API_KEY` | 未设置 | 可选的聊天端点 `Bearer` 令牌 |
## 安装和运行
需要 [Bun](https://bun.sh) （可选的 `MEM0_INSECURE_TLS` 使用 Bun 的 `fetch` `tls` 扩展；
不支持纯 Node）。依赖项在 `package.json` / `bun.lock` 中声明（没有
Python `requirements.txt` — 这是一个 Bun 项目）。
```bash
bun install # 安装 @modelcontextprotocol/sdk 和开发类型
bun run src/index.ts # stdio MCP 服务器
```
## 在 Claude Code 中注册
```bash
claude mcp add mem0 \
--env MEM0_API_URL=https://your-mem0-host \
--env MEM0_API_KEY=your-key \
-- bun run /path/to/mem0-mcp/src/index.ts
```
## 验证（访问配置的服务器）
```bash
MEM0_API_URL=… MEM0_API_KEY=… bun run src/selftest.ts # 实时烟雾测试
MEM0_API_URL=… MEM0_API_KEY=… bun run src/retrieval-eval.ts # hit@k 用于问题样式查询
```
## 技能
`skills/shared-memory/SKILL.md` 被符号链接到每个代理的技能目录（Claude Code：
`~/.claude/skills/shared-memory`；Pi：`~/.pi/agent/skills/shared-memory`）。
它记录了何时回忆，如何编写自包含事实，以及服务器在添加时调和矛盾。
