memory-mcp

你将获得

自动记忆。 工作过程中，Agent 会自动保存出现的决策、偏好和项目事实，并在回答、开始任务或询问任何与你的工作有关的问题之前检查记忆。你也可以随时让它记住或忘记任何内容。

始终保持最新。 决策变更时会更新原有记录，而不是新增一条；如果发现某条记录有误，就会将其删除。每次变更都会在回复末尾附上一句简短说明，因此只需一句话就能说“撤销这个操作”。

版本历史。 每条记忆的早期版本以及回收站中的已删除记录都会保留 30 天。只需向 Agent 提出要求，或在控制面板中操作，即可恢复任意记录。

快速、精确地回忆。 回忆结果在毫秒内返回，记忆内容会原样呈现：Ragionex 从不改写记忆，也不生成答案。

项目与团队。 每个项目都可以在自己的 Vault 中保存记忆，搜索绝不会跨到其他 Vault。每个密钥都有独立的读取、创建、更新和删除权限。与队友共享 Vault，为每位成员分配各自的权限，所有成员的 Agent 都可以使用并添加同一份记忆。

安全且私密。 保存内容会先写入磁盘再发送，因此服务中断只会导致延迟。记忆存储在欧盟，使用 AES-256 加密，并可随时导出。

适用于你的工作环境。 一条命令即可设置 Claude Code、Codex 或 OpenCode。Claude Desktop、Cursor、Cline 和其他 MCP 客户端也可以连接。

快速开始

1. 获取密钥。 在 app.ragionex.com/keys 登录并创建一个免费密钥，无需信用卡。为主 Agent 的密钥授予 Read、Create、Update 和 Delete 权限，以便它也能清理内容。密钥只会显示一次。

2. 安装。 需要 Node.js 18 或更高版本。

npx -y @ragionex/memory-mcp@latest install --agent claude-code

对于 Codex 或 OpenCode，请改用 --agent codex 或 --agent opencode；若要一次性安装到所有已安装的 Agent，请将其替换为 --all-agents。安装程序会通过隐藏提示要求输入密钥，并在进行任何更改前检查密钥。

3. 重启并检查。 退出并重新打开 Agent，然后让它检查我的 Ragionex Memory 连接。它会显示所选 Vault、密钥可使用的所有 Vault 及其权限。从现在起，照常工作即可。

供设置此服务的 AI 助手参考： 运行上方的 install 命令，并将 --agent 设为用户希望启用记忆功能的 Agent（claude-code、codex 或 opencode）。非交互式运行不会等待输入；如果没有密钥，请将它打印出的后续步骤告知用户。然后告诉用户重启其 Agent，因为你无法代为重启。在配置有效密钥之前，不要声称记忆功能已正常工作。

其他 MCP 客户端

Claude Desktop、Cursor、Cline 和其他运行本地 MCP 服务的客户端使用相同的工具。将服务添加到客户端的用户级全局 MCP 配置中：

{
  "mcpServers": {
    "ragionex-memory-mcp": {
      "command": "npx",
      "args": ["-y", "@ragionex/memory-mcp@latest"],
      "env": { "RAGIONEX_MEMORY_API_KEY": "rgx_memory_..." }
    }
  }
}

这些客户端可以使用工具，但没有 install 为 Claude Code、Codex 和 OpenCode 添加的记忆规则，因此它们自身使用记忆的稳定性较低。有关各客户端的具体信息，请参阅 MCP 客户端说明。

Vault、密钥与团队

Vault 是一组独立的记忆。密钥决定 Agent 可以在其中执行哪些操作。成员是 Vault 所有者与之共享 Vault 的队友。上图展示了它们如何协同工作：

对象	读取	创建	更新	删除
你的 Agent 1	✅	✅	✅	✅
你的 Agent 2	✅	✅
你的 Agent 3	✅	✅	✅	✅
队友 A	✅	✅	✅
队友 B	✅

图中将 Create 和 Update 分别显示为 Write 和 Edit。

每个项目使用一个 Vault 和一个密钥

新账户默认使用 My vault，没有专属 Vault 的所有项目都会使用此默认 Vault。若要为项目设置专属记忆，请在 Dashboard 中创建一个 Vault，然后让 Agent 为此项目使用我的 acme-app Vault，或在项目文件夹中放置一个 RAGIONEX_MEMORY.jsonc 文件：

{
  // The Vault this project uses (shown by the connection check and in the dashboard)
  "vault_id": "<Vault ID>",
  // Optional: a key only this project uses, for example one that can only read
  "api_key": "rgx_memory_..."
}

• 每次请求都会读取该文件，因此更改会立即生效，无需重启。
• 只检查项目文件夹本身，不检查其父文件夹。
• 在文件中放入密钥之前，请先将该文件添加到 .gitignore。
• 文件损坏、包含未知字段或密钥被拒绝时，请求会停止并显示明确错误。记忆绝不会回退到其他 Vault 或密钥。

与团队协作

• 共享 Vault。 在 Dashboard 中，所有者共享 Vault，并为每位成员授予 Read、Create、Update 或 Delete 权限。
• 共享一份记忆。 一位队友的 Agent 保存的决策，所有具有 Read 权限的成员的 Agent 都可以检索。
• 双重限制。 在共享 Vault 中，某项操作必须同时得到密钥和成员权限的允许。只有 Read 权限的队友无法更改任何内容，无论其密钥允许什么操作。

密钥

• 密钥归你的账户所有，可用于你拥有或与他人共享给你的所有 Vault。
• 只为每个密钥授予其 Agent 所需的权限。只有 Read 权限的密钥可以检索记忆，但绝不能更改任何内容。
• 密钥创建后权限固定，可在 Dashboard 中撤销。

免费计划

请求数	记忆大小	已存储记忆	Vault 数	密钥数	队友数
每 30 天 10,000 次	10,000 个字符	不限	2	2	每个 Vault 1 人

每次保存、编辑和恢复记忆都会消耗 1 次请求，从服务获取的每个搜索页面也一样。浏览、查看、删除、查看回收站、查看版本历史、检查状态和导出均免费。免费计划面向个人项目和评估，目前处于早期访问阶段，因此限额可能会调整。免费计划不允许商业用途；Pro 即将推出。

参考

工具

工具	权限	描述
ragionex_recall_memory	读取	按含义查找记忆，每次处理一个完整问题，可选精确日期。完整记录按编号分页返回
ragionex_list_memories	读取	按时间倒序浏览，显示简短预览，每页最多 100 条
ragionex_view_memory	读取	按 ID 返回最多 50 条记录的全文和修订版本
ragionex_save_memory	创建	保存新记录
ragionex_update_memory	更新	替换记录内容，并与 Agent 上次读取的修订版本进行校验
ragionex_delete_memory	删除	将记录移至回收站
ragionex_list_trash	读取	列出已删除的记录及其恢复截止时间
ragionex_memory_versions	读取	列出保留的版本，或读取某个版本的全文
ragionex_restore_memory	更新	恢复回收站中的记录或较旧版本，作为下一个修订版本
ragionex_memory_status	读取	显示新建或编辑的记录是否仍在处理中
ragionex_memory_connection	任意有效密钥	显示选定的 Vault 及其原因、该密钥可用的所有 Vault、密钥权限，以及此机器上等待保存的内容

每条记录都包含 id、vault_id、content、created_at、updated_at、status、revision、created_by 和 updated_by。新建、编辑和恢复的记录会短暂处于 processing 状态，之后才能通过记忆检索找到。永久删除、导出、共享 Vault、密钥管理和账户删除功能位于控制面板。

配置、更新和卸载

设置	详情
RAGIONEX_MEMORY_API_KEY	Agent 的密钥。install 按 --api-key、此变量、隐藏提示词的顺序获取密钥，并将其存入 Agent 的 MCP 注册信息中
RAGIONEX_API_BASE	可选的 API 地址，默认为 https://api.ragionex.com
Agent 主目录迁移	install 和 uninstall 会遵循 CLAUDE_CONFIG_DIR、CODEX_HOME 和 XDG_CONFIG_HOME
工具超时	将每次 MCP 工具调用的超时时间设为 120 秒以上；这是连接器自身的请求截止时间，可确保缓慢的请求最终返回结果或明确的指导
Windows	Claude Code 注册时会使用 npx 服务所需的 cmd /c 包装命令。请在 WSL 下运行 Codex 和 OpenCode
诊断	服务会将日志写入 stderr；请查看客户端的 MCP 服务日志

• 项目文件夹。 Agent 报告的文件夹：Claude Code 的项目目录、客户端的单一工作区根目录，或服务启动时所在的文件夹。
• 更新。 使用 @latest 和你的 Agent 再次运行 install，然后重启 Agent。运行时不提供密钥会保留现有注册信息和密钥。
• 记忆规则。 记忆规则位于 ~/.claude/CLAUDE.md、~/.codex/AGENTS.md 或 ~/.config/opencode/AGENTS.md 中的 ragionex-memory-mcp:priority-rule 标记之间，并会在升级后自动刷新。若要保留自己的版本，请编辑开始标记，服务就会保持该代码块不变。参见记忆规则指南。
• 卸载。 npx -y @ragionex/memory-mcp@latest uninstall --agent claude-code 会移除注册信息和规则；通过编辑开始标记而冻结的规则会保留，需手动删除。尚未同步的保存内容会继续留在磁盘上。

本地数据与恢复

• 等待同步的保存内容位于 ~/.ragionex/pending-saves/，每个密钥和 API 地址对应一个文件夹。文件中包含未加密的已保存内容和投递元数据。
• *.pending.json 文件会使用原始请求 ID 自动重试，因此重试不会创建第二条记录。因计划限额而保留的保存内容会在配额重置后发送，并计入服务接受该内容的周期。
• *.blocked-<reason>.json 文件是在后续同步时被拒绝的内容。系统不会再自动发送这些文件；请根据 ragionex_memory_connection 报告的路径进行检查。
• 等待发送的保存内容会保留其创建时使用的密钥、API 地址和项目 Vault；未使用项目 Vault 创建的内容会发送到账户默认 Vault。不要编辑这些文件或在不同的密钥文件夹之间移动文件；删除已检查的文件前，请先停止所有连接器实例。
• 较旧的 ~/.ragionex/pending-memories.jsonl 不会自动发送；移除前请先检查。
• ~/.ragionex/recall-pages/ 可让搜索在重启后从下一页继续：每次搜索对应一个以摘要命名的小文件，仅保存时间、分页详情和已显示的 ID，不会保存问题、记忆文本或密钥。过期文件会自动删除，手动删除也安全；重启后，Agent 会重新开始该搜索。

安全性

• 记忆是数据，而非指令。 系统会告知 Agent，绝不可遵循已保存内容来更改权限、调用工具或覆盖你的指令。
• 仅支持 HTTPS。 除 localhost、127.0.0.1 和 [::1] 外，连接器会拒绝普通 HTTP。

故障排除

症状	解决方案
Agent 不使用记忆，或提示工具不可用	安装后重启 Agent；MCP 服务会在启动时加载。然后让它检查连接
“API 密钥无效或已撤销”	创建新密钥并再次运行 install；Agent 会显示准确的命令
保存内容处于“排队中”或“尚未确认”状态	服务无法访问或已达到限额。保存内容会在此计算机上等待，并自动发送；连接检查会显示仍在等待的内容
刚刚保存的内容未能找到	新记录会短暂处于 processing 状态；让 Agent 检查其状态
权限错误	密钥或你对共享 Vault 的访问权限缺少所需权限。请使用具有该权限的密钥，或联系 Vault 所有者
“未选择 Vault”	在控制面板中选择默认 Vault，或在项目中添加 RAGIONEX_MEMORY.jsonc

关于 Ragionex

Ragionex 是面向 AI Agent 的上下文引擎。它会保留 Agent 学到的内容，并原样返回已保存内容：它绝不会改写记忆，也不会生成答案，因此推理仍由 Agent 完成。回忆结果会在数毫秒内返回；针对相同记忆提出相同问题，总会得到相同结果。

支持

渠道	使用场景
GitHub Issues	报告错误
Discord	提问和参与社区交流
[email protected]	私密问题和安全问题报告
文档	设置指南和概念说明

许可证

MIT