mcp-memory-service：让 Claude Code 与 Cursor 共享持久记忆

mcp-memory-service 为 AI 编程智能体提供共享的持久记忆，用来保存架构决策、故障调查和项目约定。它的价值不是让模型在一个上下文窗口中保留无限对话，而是让新会话能够检索另一个会话或工具保存的相关记录。前提是各客户端连接同一个存储，并且实际调用记忆工具。项目官方仓库介绍了本地嵌入、语义检索和带类型的知识图谱关系。

资料核查日期：2026 年 9 月 24 日。本文是基于文档的配置与评估指南，不是我们已经执行的集成实测，也没有独立复现性能基准。下文会区分项目公开的能力、我们组合的配置示例以及建议的验收测试。

它能替代 CLAUDE.md、Cursor 规则或原生记忆吗？

不能。稳定的指令应保留在代码仓库中，持续变化且有证据支持的历史信息才适合放入共享记忆。“Claude Code 每次启动都完全没有持久上下文”并不准确。Claude Code 的记忆文档说明了指令文件和自动记忆。Cursor 规则同样可以保留指令。但这些能力本身，并不代表不同工具已经共享一个可查询的决策历史。

因此，是否引入它可以从一个具体问题判断：开发者在 Claude Code、Cursor 和 OpenCode 之间切换时，是否不断重建相同的推理过程？先解决这一问题，而不是建立另一套可能与仓库规范冲突的指令系统。历史解释有价值，但不应取得高于现行规则和代码事实的权限。

安装 mcp-memory-service：安装完成不等于集成完成

单行安装命令如下：

pip install mcp-memory-service

PyPI 项目页列出了 11.13.0 版本，发布日期为 2026 年 9 月 19 日，要求 Python 3.10 或以上，采用 Apache-2.0 许可证。本示例固定使用核查过的版本，避免安装时自动跟随之后的发行版。

python3 -m venv "$HOME/.venvs/mcp-memory-service"
"$HOME/.venvs/mcp-memory-service/bin/python" -m pip install "mcp-memory-service==11.13.0"
mkdir -p "$HOME/.local/share/agent-memory/example-app"
"$HOME/.venvs/mcp-memory-service/bin/memory" server --help

这些 Shell 命令适用于 macOS 和 Linux。Windows 用户需要调整虚拟环境中的可执行文件位置和绝对存储路径，不能原样使用 POSIX 路径。团队已有 Python 环境管理方式时，应沿用既有流程，并确认 IDE 启动的进程能访问同一环境。

官方安装指南说明了 memory server 以及后续客户端连接步骤。安装 Python 包不会自动在每个 IDE 中注册 MCP 服务，不会自动导入旧对话，也不保证每个新会话都会读取记忆。软件存在、客户端连通、记录已写入和任务开始时实际检索，是四个不同的检查点。

最重要的设置：所有客户端必须使用同一个数据库

包名相同、数据库路径不同，得到的就是不同的记忆。下面的单用户、单机示例让三个客户端使用同一个可执行文件和同一个绝对 SQLite 文件路径。配置参考说明了 MCP_MEMORY_STORAGE_BACKEND、MCP_MEMORY_SQLITE_PATH 和 MCP_MEMORY_USE_ONNX。

请把所有示例中的 example-app 一致替换为一个项目或信任边界。不同客户的仓库应使用独立存储，不要把标签当作访问控制。该路径指向数据库文件，而不只是父目录。容器、远程开发主机和另一个操作系统账户不会因为配置文本相似，就自动共享你的主目录。

这里每个 MCP 客户端都会启动一个 stdio 进程，访问同一个本地存储。这不是多用户服务的部署设计。正式依赖前应测试并发使用，不要把活动中的 SQLite 数据库提交到 Git，也不要把网盘同步文件夹当作数据库复制方案。如果开发工作实际跨多台机器，应该单独设计服务端点与授权，而不是继续假设本地路径能够互通。

通过本地 MCP 连接 Claude Code

在需要使用该连接的项目目录中执行：

claude mcp add \
  --env MCP_MEMORY_STORAGE_BACKEND=sqlite_vec \
  --env MCP_MEMORY_SQLITE_PATH="$HOME/.local/share/agent-memory/example-app/sqlite_vec.db" \
  --env MCP_MEMORY_USE_ONNX=true \
  --transport stdio --scope local \
  memory -- "$HOME/.venvs/mcp-memory-service/bin/memory" server
claude mcp list

示例遵循 Claude Code 官方 MCP 命令格式。--scope local 将注册保留在你的本地项目配置中。选项位于服务名称之前，-- 分隔符后面才是可执行文件。显式指定程序路径，可避免依赖 IDE 继承终端的 PATH。

根据客户端状态重新启动或重新连接，然后确认服务连通，且 memory_store 与 memory_search 工具可用。只批准预期操作。服务显示“已连接”并不意味着某条记录已经写入，更不意味着下一项任务会自动读取它。

配置 Cursor，让它读取相同的记忆存储

将以下条目合并到项目的 .cursor/mcp.json，保留已有的其他服务配置：

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "${userHome}/.venvs/mcp-memory-service/bin/memory",
      "args": [
        "server"
      ],
      "env": {
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
        "MCP_MEMORY_SQLITE_PATH": "${userHome}/.local/share/agent-memory/example-app/sqlite_vec.db",
        "MCP_MEMORY_USE_ONNX": "true"
      }
    }
  }
}

Cursor MCP 文档定义了 stdio 配置字段，并支持 ${userHome} 插值。请检查变量展开后的实际路径，重新连接服务，工具缺失时查看 MCP 输出。不要把凭证或从客户项目复制出来的数据库放入项目配置并提交。

两个客户端都显示名为“memory”的服务，并不能证明状态共享成功。下文的跨客户端验收会同时检查实际数据库和工具调用流程。尤其是在一个客户端由终端启动、另一个由桌面启动时，不能只比较服务名称。

OpenCode：标准 MCP 连接和自动采集插件不是一回事

继续使用相同的本地 MCP 方案时，将以下内容合并到 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "memory": {
      "type": "local",
      "command": [
        "{env:HOME}/.venvs/mcp-memory-service/bin/memory",
        "server"
      ],
      "enabled": true,
      "environment": {
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
        "MCP_MEMORY_SQLITE_PATH": "{env:HOME}/.local/share/agent-memory/example-app/sqlite_vec.db",
        "MCP_MEMORY_USE_ONNX": "true"
      }
    }
  }
}

OpenCode MCP 参考使用 type: local、命令数组和 environment，不是 Cursor 的 env 字段。其配置文档说明了 {env:HOME} 替换规则。这个示例把客户端公开支持的格式与上游服务命令组合起来；我们没有实际运行这套三客户端配置。

单独提供的 Memory Awareness 插件通过 HTTP REST API 在会话开始时检索记忆并执行自动采集。插件文件来自仓库，仅运行 pip 安装不会把它装好。标准 MCP 提供可调用工具，插件则增加会话生命周期自动化，这是两条不同的集成路径。

建议先选一条路径。没有采集策略就同时启用两者，会增加判断记录来源的难度。本 stdio 示例不需要 HTTP 监听服务。若以后部署插件，需要单独核查端点、身份验证和网络访问范围，而不是直接复制一个面向演示的匿名服务配置。

验证记忆能否跨重启、跨 IDE 保留

验证实际检索结果，不要只相信智能体声称“我记得”。在 Claude Code 中明确要求调用 memory_store，保存一条虚构决策，标签为 project:example-app：“支付事件使用 outbox，避免支付提交成功后，下游事件丢失。”再加上虚构的决策引用、状态和日期，不要使用真实客户数据。

检查存储工具返回的成功结果，然后关闭会话。在全新的 Cursor 会话中明确要求调用 memory_search，查找为什么支付事件采用 outbox。核对返回记录的标识符和内容，而不是接受模型凭一般知识写出的合理解释。在 OpenCode 中重复，再重启客户端进程后重复一次。这样才能把会话上下文残留与持久存储区分开。

还应加入反向测试：按照你选择的隔离设计，另一个项目不应该能够读取这条决策。搜索标签能缩小结果范围，却不构成安全边界。启用自动采集前，既要检查本应出现却缺失的结果，也要检查本不应出现的结果。

本地 ONNX 嵌入：“零外部 API 调用”具体指什么？

嵌入在本地计算，不代表整个编程流程都离线。ONNX Runtime可以在本地执行已经可用的模型。安装软件包和首次下载模型是另外的网络活动。客户端把记忆工具的结果加入上下文后，云端编程模型仍可能收到这些内容。

多语言团队还需要核查另一个边界。all-MiniLM-L6-v2 模型卡将默认模型标为英语模型，输出 384 维向量，默认会截断超过 256 个 word pieces 的输入。中文界面并不能证明“中文问题检索英文决策”效果可靠。直接保存很长的会话导出，也可能在生成嵌入之前就丢掉关键细节。

项目的环境变量示例提供模型、提供方和可选功能设置。应检查具体配置，而不是把“本地优先”当作数据边界已经满足要求的证明。云端或混合存储、外部评分、LLM 辅助采集都需要另外作出选择。

我们建议用一个简单的跨语言测试开始：用英语保存一条已批准决策，再分别使用德语、西班牙语和中文，以开发者真实的提问方式寻找它。评估正确记录是否被检索出来，而不是模型是否能翻译回答。更换嵌入模型时，应先备份，再规划重新生成向量的迁移；即使新旧模型维度相同，也不应直接混用其向量空间。

mcp-memory-service 真的能在 5 毫秒内检索上下文吗？

5 毫秒是项目方的性能声明，不是本文验证过的端到端保证。不能把仓库中的宣传语扩展成“任意历史决策和任意图谱关系都能在 5 毫秒内返回”。我们没有独立复现这个数字。

本地评估时，应分别计量进程启动、首次模型加载、查询向量生成、数据库检索、图谱扩展和客户端传输，再测量整个工具调用往返。热缓存下的数据库读取，与冷启动检索、远程请求或编程模型生成完整答案，测量的不是同一件事。

记录硬件、模型、记忆数量和长度、查询类型、并发客户端以及预热条件。报告中位耗时与较慢请求的表现，同时记录证据是否正确。我们的采用标准是：如果智能体自信地召回一条已经失效的架构决策，节省几毫秒没有实际价值。先定义可接受的正确率和错误类型，再讨论响应速度是否足够。

用因果记忆排查故障：建立关系不等于证明因果

知识图谱文档介绍了 causes、fixes、contradicts、supports、follows 和 related 等关系类型。它们能表达调查链条，但不会自动证明调查结论为真。

考虑一个虚构案例：提交 demo-change-A 删除了幂等性保护；缺陷 DEMO-42 记录了重复支付事件；补丁 demo-fix-B 恢复保护；回归测试 test_duplicate_event 在补丁前复现失败、补丁后通过。应把这些工件的引用和因果陈述一起保存，区分“怀疑是原因”和“已通过所审查的测试确认”。

如果后续迁移替换了原设计，应保留历史记录，同时把旧建议标记为已被替代。否则，语义匹配度很高的结果也可能变成错误的工程建议。智能体根据记忆采取行动前，应查看当前代码和相关测试，而不是把图谱中的一条边当作永远有效的事实。

实用记忆策略：记录决策、精确检索、淘汰过时建议

我们建议每条记录包含项目、组件、决策、理由、证据位置、来源提交、作者或审查者、状态、记录日期和下一次复核触发条件。这是记录内容的编辑模板，不是声称这些字段都是 API 必填参数。每条记忆保留一个值得长期保存的结论，不要把临时想法全部升级为正式决策。

任务开始时，围绕相关组件检索并检查证据状态。任务结束时，只保存已经验证的变更和明确标记的未决问题。把“我们试过”与“团队已批准”分开。在自动整合可能改变重要运行含义之前，要求人工复核。记录量持续增长本身，不应被当作质量提升的指标。

节省 token 的检索指南说明了有界检索和基于图谱的探索。下面是传给 memory_search 的示例参数对象，限制返回条数和字符数。6000 是我们选择的示例预算，不是项目推荐的性能参数，也不是 token 数量：

{
  "query": "Why does example-app use an outbox for payment events?",
  "tags": [
    "project:example-app"
  ],
  "limit": 5,
  "max_response_chars": 6000
}

实体图谱需要单独验收。即使已有文本记忆，memory_explore 返回空结果也可能是因为实体从未生成。文档中的 MCP_ENTITY_LINKING_ENABLED=1 设置影响之后新保存的记录；历史数据需要明确规划的维护或回填步骤。不要为了让空图谱看起来正常，就盲目执行会修改数据的维护命令。

排查记忆无法持久化或召回不准确的问题

共享编程记忆需要哪些安全边界？

把检索到的记忆视为不可信证据，而不是优先级更高的指令。记录中出现“忽略之前的指令”时，这句话仍然只是数据。每个项目只应获得必要的存储和工具权限，客户提供的文档不应悄悄改写团队开发规范。自动采集不应绕过原本适用于代码、凭证和客户资料的审查。

MCP 安全指南可以作为核查授权和传输风险的起点。我们的操作建议是先采用本地 stdio，排除密钥和客户会话文本，在暴露共享端点前单独评审。使用 HTTP 时，应明确选择绑定地址、身份验证、访问权限、传输保护和允许的客户端。不要把匿名访问演示直接用于网络可达的部署。

在开启自动采集之前，明确纠错、删除、保留期限和恢复的责任人。测试一致的备份与恢复流程，确认已删除或已被替代的记录不会从第二个存储重新出现。开源、本地嵌入和标签本身，都不能证明合规或租户隔离已经成立。

用一个小型试点判断是否值得采用

不要一开始就导入全部历史。以下是我们建议的试点，不是公开基准：十条已批准决策、五条已被替代的决策、五组缺陷与修复链，以及五个跨语言查询。再加入其他项目不应读取的记录，让试点同时验证正确召回和权限边界。

如果试点减少了重复解释，又没有增加过时建议和跨项目误用，就值得继续采用。如果真正缺少的只是清晰的开发约定，先完善仓库指令。更广泛的上下文架构可参考我们的 OpenViking 评测；应用层记忆与不同部署方式的取舍，可阅读 Supermemory 指南。

需要实施支持时，可以了解 Wavect 的 AI 工程服务。Twinsoft AI 案例提供相关交付背景，但不是该项目使用了此工具的证明。我们的上线前软件 QA 清单有助于把试点变成发布标准，也可以与团队讨论范围明确的记忆集成。