shared-agent-memory

# 共享智能体内存 **所有 AI 编程智能体的共享内存。** Claude Code 会话、Codex 和任何支持 MCP 的工具都可以读写相同的知识图谱 - 因此一个智能体学到的东西，其他智能体都知道。 不再需要编写移交 `.md` 文件并让下一个智能体阅读整个文件。 ``` ~/.agent-memory/memory.json ← 一个共享的大脑 ▲ ▲ 内存 MCP 服务器（每个工具一个） ▲ ▲ Claude Code Codex (+ 任何 MCP 客户端) ``` 这是在官方 [`@modelcontextprotocol/server-memory`](https://www.npmjs.com/package/@modelcontextprotocol/server-memory) 之上的一层薄而谨慎的**集成层**。 该服务器负责存储；该项目将每个智能体连接到同一个存储库，并添加一些简短的、令牌高效的指令，以便它们能够很好地使用它。 将其视为智能体的**共享情景记忆**层 - 它们在工作过程中学到的东西 - 补充您的已提交文档和代码，而不是取代它们。 ## 为什么 如果您运行多个智能体，您会遇到这种情况：每个智能体都从头开始，因此您需要手动编写上下文文件并将它们粘贴到处。 这替换为一个共享的、**可搜索的**内存。 智能体查找它们需要的几个事实 (`search_nodes`) 而不是重新读取一个不断增长的文档 - 即使使用几个月后，它仍然保持快速和廉价。 ## 编辑协调 当您在同一个仓库中运行 Claude Code 和 Codex 时，共享内存是不够的：两个智能体仍然可以打开同一个文件并无意中覆盖彼此的工作。 可选的协调层为它们提供了一个共享的工作台和活动编辑的警告钩子。 一旦打开： ```bash shared-agent-memory coordination on ``` 然后智能体可以声明它们期望编辑的文件： ```bash shared-agent-memory claim lib/board.js bin/cli.js --as codex --note "wire CLI" shared-agent-memory board shared-agent-memory release --as codex ``` 协调板将文件路径声明存储在 `~/.agent-memory/activity.jsonl` 中。 声明是建议性的，而不是锁定，并且在 2 小时后自动过期，因此崩溃的会话不会永久锁定文件。 `coordination on` 为 Claude 和 Codex 添加了一个单独的标记包装指令块，并为 `Edit|Write|MultiEdit` 安装了一个幂等 Claude Code `PreToolUse` 钩子，而不会覆盖现有的钩子。 在 Claude 编辑文件之前，钩子会检查协调板并在另一个智能体已声明相同文件时添加警告上下文： ```text 注意：lib/board.js 与正在进行的共享智能体内存声明重叠。 - codex 声称 lib/board.js（4m old）- wire CLI ``` 默认情况下，钩子在 `warn` 模式下运行，因此它**不会**阻止编辑。 它只是为智能体提供足够的上下文，以便在触摸同一个文件之前进行协调。 使用 `shared-agent-memory coordination off` 删除协调指令块和该项目的钩子。 ## 安装 **需要 Node 18+** （您的智能体已经使用的 `npx` 相同的运行时）。 您不需要发布任何内容 - 它直接从 GitHub 运行。 ```bash # 一行代码 npx github:dan-calin/shared-agent-memory install # 或克隆并运行 git clone https://github.com/dan-calin/shared-agent-memory cd shared-agent-memory node bin/cli.js install ``` 在 Windows 上，如果您在本地克隆了此仓库，并且 `shared-agent-memory` 未被识别为命令，请从仓库文件夹通过 Node 运行 CLI： ```bat cd "C:\Users\Roxan\Desktop\AI Link\shared-agent-memory" node .\bin\cli.js install node .\bin\cli.js status ``` 要使更短的 `shared-agent-memory ...` 命令在任何文件夹中都有效，请全局链接本地包： ```bat cd "C:\Users\Roxan\Desktop\AI Link\shared-agent-memory" npm install -g . shared-agent-memory install ``` 安装程序**自动检测**您拥有的智能体，并为每个智能体： - 注册共享内存 MCP 服务器， - 将其指向一个共享文件 (`~/.agent-memory/memory.json`)， - 添加一个小的指令块，以便智能体知道如何使用它。 然后**重启您的智能体**（它们在启动时读取 MCP 配置和指令）。 ## 用法 大多数情况下，您不需要做任何事情 - 智能体会自动使用内存： - **任务开始** → 它们会搜索相关的先前上下文的 `search_nodes`。 - **任务结束** → 它们会保存关于发生了什么变化的一行注释。 您只需： - **强制保存：** *"记住我们正在使用 Postgres，而不是 SQLite。"* - **询问已知信息：** *"您对计费模块了解什么？"* ### 示例：移交 1. Codex 重构您的付款重试逻辑并保存 - 在实体 `tradebot/billing.py` 下 - 注释 `retry → exponential backoff (codex, 2026-07-01 14:32)`。 2. 明天，一个全新的 **Claude Code** 会话被要求扩展计费。 它首先搜索内存，查看 Codex 的注释并在此基础上构建 - 无需重新解释。 ## 命令 以下示例使用已安装的 `shared-agent-memory` 命令。 如果您尚未全局链接或安装它，请从仓库文件夹运行相同的命令，如 `node bin/cli.js <command>` 或使用 `npx github:dan-calin/shared-agent-memory <command>`。 ``` shared-agent-memory install 配置检测到的智能体以共享内存 shared-agent-memory instructions 打印要自己粘贴的指令块（s） shared-agent-memory coordination 打开/关闭/状态可选的编辑协调 shared-agent-memory claim 在共享协调板上声明文件 shared-agent-memory release 释放此智能体的活动协调声明 shared-agent-memory board 显示活动协调声明 shared-agent-memory doctor 检查/修复内存文件的格式 shared-agent-memory status 显示当前配置 shared-agent-memory uninstall 删除服务器 + 指令块 shared-agent-memory help 完整帮助 ``` 选项：`--claude-only`、`--codex-only`、`--manual`、`--memory-dir <path>`、`--as <agent>`、`--note <text>`、`--mode <warn|block>`、`--dry-run` 和 `--purge`（卸载：还删除内存存储）。 ### 指令去哪里（以及如何保持控制） 默认情况下，`install` 会在您的**全局**指令文件中写入一个**标记包装**块（`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md`）。 它只会添加或更新*它自己的*块 - 那些文件中的其他内容永远不会被触摸，因此您的个人指令是安全的。 如果您更喜欢自己放置它们？ 有两个选项： - **`install --manual`** - 配置 MCP 服务器但**打印**块而不是写入它，这样您可以将其粘贴到您想要的任何地方。 - **`instructions`** - 随时重新打印块（s），并提供放置指导。 将块粘贴到**全局**文件（适用于每个项目）或**项目范围**的 `CLAUDE.md` / `AGENTS.md`（仅适用于该仓库）。 ## 它是如何工作的 - **存储：** `@modelcontextprotocol/server-memory`，一个知识图谱，由*实体*（命名为 `project/file-or-feature`）和简短的*观察*组成，以及它们之间的*关系*（`serviceA --depends-on--> db`），因此回忆是关系感知的，而不是仅仅基于关键词匹配。 - **共享：** 每个智能体的 MCP 配置都会启动具有相同 `MEMORY_FILE_PATH` 的服务器，因此它们都读取/写入一个纯 JSON 文件。 - **纪律：** 安装的指令强制执行令牌效率 - 使用几个关键词进行搜索（从不转储整个图谱），按项目范围限定实体以使搜索保持相关，并为每个工作单元保存一行。 参见 [`templates/memory-readme.md`](templates/memory-readme.md)，了解数据模型和 [`examples/manual-agent-instructions.md`](examples/manual-agent-instructions.md)，了解复制粘贴片段以手动连接其他工具。 ## 为什么使用服务器而不是普通文件？ 一个公平的问题 - 一些团队将内存作为普通文件进行 grep，并在会话开始时进行参数化，并认为“内存服务”是一种脆弱的依赖。 这个项目解决了这个问题： - **在底层，它确实是一个普通文件。** `~/.agent-memory/memory.json` 是人类可读的、可 diff 的和 git-able 的（NDJSON - 每行一个记录）。 即使服务器从未运行，您也可以 `cat`、grep 或仔细手动编辑它。 如果手动编辑曾经损坏了格式，`shared-agent-memory doctor` 会修复它。 - **“服务器”不是一个守护进程。** 每个智能体都会按需通过 `npx` 启动 `@modelcontextprotocol/server-memory`，并在会话结束后退出 - 没有需要运行、监控或部署的东西。 - **您获得的好处超过 grep：** 一个结构化的查询接口 (`search_nodes`) 和真正的关系 (`A --depends-on--> B`)，每个 MCP 智能体都理解，而不是每个智能体都发明自己的文件格式。 - **诚实的成本：** 它需要 Node，并且第一次运行会进行 `npx` 获取。 在一个锁定的或离线的 CI 盒中，直接读取 JSON 文件。 ## 版本控制和治理 因为存储是一个单一的 JSON 文件，所以您可以免费获得历史记录和回滚： 将 `~/.agent-memory/` 置于 git 下。 如果智能体写入错误的内容，`git revert` 它。 Diffs 显示每个智能体学习了什么以及何时学习。 ## 设计目标和非目标 **目标：** 跨工具、本地、拥有自己的数据、零基础设施和按构造的令牌效率。 **非目标（按设计）：** - **没有外部源的自动摄入** （Drive、APIs、tickets）。 智能体会记录它们所学的内容；这不是一个爬虫。 - **没有信念建模** - 置信度、衰减或矛盾解决。 条目是你可以用手动修剪的事实。 （可能未来的工作；参见路线图。） - **没有托管服务或团队 RBAC。** 对于托管的多租户内存，请参见下面的替代方案。 ## 替代方案 如果您的需求超出了共享文件，那么存在更重的内存平台 - [Mem0](https://mem0.ai)、[Zep](https://www.getzep.com) 和 [Cognee](https://www.cognee.ai) 提供托管存储、范围划分和衰减； [engram](https://github.com/Harshitk-cp/engram) 是一个开源的“基于信念的内存” HTTP 服务。 `shared-agent-memory` 故意停留在相反的一端：没有基础设施、一个文件、今天适用于 Claude Code 和 Codex。 ## 路线图 - 可选的修剪/陈旧帮助程序（一个 `prune` 命令）。 - 更多开箱即用的智能体（Cursor、Windsurf、...）。 - 可选的每个项目内存存储作为一个一流的标志。 ## 支持的智能体 | 智能体 | 配置文件 | | --- | --- | | Claude Code | `~/.claude.json` （MCP 服务器）+ `~/.claude/CLAUDE.md` （指令） | | Codex CLI | `~/.codex/config.toml` （MCP 服务器）+ `~/.codex/AGENTS.md` （指令） | | 其他 | 将其 MCP 配置指向相同的 `MEMORY_FILE_PATH` （参见示例） | 希望有另一个智能体开箱即用？ PRs 欢迎 - 在 `lib/` 下添加一个模块，镜像 `lib/claude.js`。 ## 卸载 ```bash shared-agent-memory uninstall # 删除服务器 + 指令，保持内存 shared-agent-memory uninstall --purge # 还删除 ~/.agent-memory ``` ## 常见问题 **我的内存会被发送到任何地方吗？** 否。 它是一个本地 JSON 文件。 除非您自己同步该文件，否则没有任何内容离开您的机器。 **它是否将不同的项目分开？** 一个共享存储库保存所有内容；项目通过**命名**分开 - 实体是 `project/file-or-feature`，并且按项目名称搜索（例如 `miko`）仅返回该项目的文件。 通用术语（例如 `auth`）可以跨项目共享 - 这是权衡取舍，以便在需要时提供跨项目知识。 **自动保存是否总是触发？** 它是指令驱动的（智能体决定），因此是可靠的但不是保证的。 手动 *"记住 X"* 命令是始终存在的备用方案。 **Windows？** 是的 - Windows、macOS 和 Linux。 在 Windows 上，服务器通过 `cmd /c npx` 自动启动。 **内存服务器是否抛出 JSON 解析错误？** 存储库是 NDJSON（每行一个对象）；某些内容将其打印为漂亮的格式。 运行 `shared-agent-memory doctor` 以修复它 - 它会备份原始文件。 ## 致谢 基于官方 [`@modelcontextprotocol/server-memory`](https://www.npmjs.com/package/@modelcontextprotocol/server-memory)。 该项目只是使其在智能体之间共享并易于安装。 ## 许可证 [MIT](LICENSE)