项目概述与架构

1. 项目定位与核心价值

agentsmd-memory 是一个零依赖的 MCP（Model Context Protocol）服务器，旨在为 AI Agent 提供持久化的项目级记忆能力。其核心设计理念是：让项目知识以一个普通的 Markdown 文件（默认为 AGENTS.md）的形式驻留在代码仓库中，与源代码一同纳入版本控制。

根据 package.json 的描述，该项目的官方定义为："Zero-dependency MCP server that gives AI agents a self-updating project memory in AGENTS.md. Returns merge instructions instead of mutating state, so every change is a reviewable diff."（一个零依赖的 MCP 服务器，通过 AGENTS.md 为 AI Agent 提供自我更新的项目记忆。它返回合并指令而非直接修改状态，因此每一次变更都是可审查的差异。） 资料来源：README.md

其最具特色、也是与传统记忆类工具最关键的区别在于——工具不直接编辑文件。README.md 中明确指出："The tools don't edit files. They resolve the nearest AGENTS.md and return merge instructions; the agent applies them with its own edit tools, so changes show up as a git diff."（工具不编辑文件，而是解析最近的 AGENTS.md 并返回合并指令，由 Agent 使用其自身的编辑工具应用这些变更，从而以 git diff 的形式呈现。） 资料来源：README.md

这种"返回指令而非副作用"的模式，使得每一次记忆的写入都是可追溯、可审查、可回滚的——天然契合 Git 工作流。

2. 系统组成与组件划分

根据 package.json 中 bin 与 main 字段的定义，项目入口分为两条路径：

资料来源：package.json

整个包是一个标准的 Node.js ES Module 工程，"type": "module"，运行时要求 Node >= 18。如其名称所强调的，没有任何运行时依赖（zero dependencies），也未引入测试框架——测试使用 Node 内置的 node --test。资料来源：package.json

服务器向 MCP 客户端暴露两个工具：

• memory_save：记录一条持久化的事实（决策、约定、踩坑、非显而易见的命令等）。
• memory_forget：移除一条过时的事实。

资料来源：README.md

3. 工作流程与数据流转

下图描绘了从 Agent 调用工具到 AGENTS.md 实际更新的完整数据流：

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as agentsmd-memory
    participant FS as 文件系统
    participant Git as 版本控制

    Agent->>MCP: 调用 memory_save / memory_forget
    MCP->>MCP: 解析工作目录(MCP roots → cwd 参数 → process.cwd())
    MCP->>FS: 向上遍历直至 Git 根目录
    MCP->>FS: 定位已存在的 AGENTS.md（最近的一个）
    alt 文件不存在
        MCP->>FS: 唯一一次直接写入: 引导初始文件
    else 文件存在
        MCP-->>Agent: 返回合并指令文本
    end
    Agent->>FS: 通过编辑工具自行应用指令
    FS->>Git: 修改自然呈现为 git diff

工作目录解析遵循三层优先级：MCP roots → cwd 参数 → process.cwd()。随后服务器向根目录方向遍历直至 Git 根，选择最近一个已存在的目标文件。资料来源：README.md

README.md 还强调：唯一的一次直接磁盘写入发生在首次 memory_save 时用于引导创建缺失的文件；其余所有变更都以文本指令的形式返回。

4. 配置、运行与开发

环境变量 MEMORY_FILE 用于指定目标文件名，默认值为 AGENTS.md，可改为 CLAUDE.md、GEMINI.md 等，但仅接受裸文件名。资料来源：README.md

开发脚本定义于 package.json：

• npm test：使用 node --test 运行测试套件；
• npm start：启动 node src/index.mjs；
• prepublishOnly：发布前自动跑测试。

调试时可使用 npx @modelcontextprotocol/inspector npx -y agentsmd-memory 启动官方可视化调试器。资料来源：package.json、README.md

设计哲学总结

agentsmd-memory 的架构将"记忆"问题巧妙转化为一个人类可审计的工作流：MCP 工具仅产出纯文本合并指令，把"是否应用变更"的最终决定权交还给 Agent 与版本控制系统。这正契合了"Agent 提出建议、代码审查者把关"的现代 AI 辅助开发范式——既不牺牲 Agent 的自主性，也不绕过工程治理。

See Also

• README.md — 完整的安装、配置与使用说明
• package.json — 项目元信息、入口与脚本
• npm 上的 agentsmd-memory — 包的发布渠道

概述

agentsmd-memory 是一个零依赖的 MCP（Model Context Protocol）服务器，它向 AI 智能体暴露两个核心工具：memory_save 与 memory_forget。这两者的共同目标是在项目的 AGENTS.md（或用户通过环境变量指定的等价文件）里维护一份可审查、可回滚的长期记忆，记录决策、规范、坑点、非显然的命令等持久性事实。资料来源：README.md

与“直接改文件”的方案不同，这两个工具始终返回合并指令（merge instructions），由智能体调用其自身的编辑工具落地；这意味着 AGENTS.md 的每一次变更都呈现在 git diff 中，可以被人类审阅。资料来源：README.md

工具职责划分

资料来源：README.md

两个工具都不直接编辑目标文件，唯一一次“写盘”发生在首次 memory_save 时——若解析路径上不存在 AGENTS.md，服务器会引导式地创建一个最小化模板（bootstrap），其余所有变更都通过返回的指令让智能体自行合并。资料来源：README.md

关键设计：指令而非写盘

整个服务器的核心理念是 instruction-only：

1. 工具调用接收到参数后，解析出目标 AGENTS.md 路径。
2. 工具不调用 fs.write 之类的 API，而是返回结构化的合并/删除指令。
3. 智能体拿到指令后，使用其自带的 Edit/Write 工具真正落地变更。
4. 由于最终落盘动作由智能体完成，差异在版本控制中以普通 diff 形式出现。资料来源：README.md

这种设计带来三个收益：

• 可审查性：人类审阅 PR 时看到的 AGENTS.md 变更与普通文档变更一致。
• 可回滚性：没有绕过 git 的隐藏写盘。
• 可控性：智能体对“是否、何时”调用工具拥有完整自主权——README 明确指出 “Saves are prompt-driven; the agent decides when to call them”。资料来源：README.md

数据流：一次 `memory_save` 调用

sequenceDiagram
    participant Agent as AI 智能体
    participant MCP as agentsmd-memory (MCP)
    participant FS as 本地文件系统
    participant Git as Git 仓库

    Agent->>MCP: 发起 memory_save 调用
    MCP->>MCP: 解析工作空间目录<br/>(MCP roots → cwd arg → process.cwd())
    MCP->>FS: 向父目录逐级查找目标文件<br/>(默认 AGENTS.md)
    alt 目标文件不存在
        MCP-->>Agent: 返回 bootstrap 指令<br/>(含最小化初始模板)
        Agent->>FS: 写入新的 AGENTS.md
    else 目标文件存在
        MCP-->>Agent: 返回 merge 指令<br/>(含插入位置与新条目)
        Agent->>FS: 按指令合并条目
    end
    FS->>Git: 变更进入工作区，呈现为 git diff

资料来源：README.md

工作空间解析顺序

服务器必须先确定要操作哪份 AGENTS.md，解析顺序在 README 中是明确规定的（也即：最具体的覆盖最宽泛的）：

1. MCP roots：由宿主 MCP 客户端注入的根目录。
2. cwd 参数：调用方显式传入的工作目录。
3. process.cwd()：服务器进程自身的当前工作目录，作为兜底。

确定起点后，服务器沿目录树向上走到 git 根，并以“最近的、已存在的目标文件”为准。资料来源：README.md

配置

服务器只暴露一个环境变量配置项：

资料来源：README.md

这一项同时影响 memory_save 的 bootstrap 行为与 memory_forget 的定位查找，因此跨编辑器的项目（例如同时支持 Claude Code 与 Cursor）可统一通过该变量收敛到同一份记忆文件。资料来源：README.md

调用与运行

服务器以本地 stdio MCP 进程方式运行，发布到 npm 后通过 npx 拉起。package.json 中 "bin" 指向 src/index.mjs，"main" 指向 src/server.mjs，"engines" 要求 Node >=18。资料来源：package.json

最小 MCP 客户端配置示例：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "agentsmd-memory"]
    }
  }
}

资料来源：README.md

不同宿主接入方式略异：opencode 使用 "type": "local" 的 mcp 配置；Claude Code 使用 claude mcp add --transport stdio memory -- npx -y agentsmd-memory；Windows 上需用 cmd /c npx -y agentsmd-memory 包裹。资料来源：README.md

常见误区

• 把它当成“自动写文件的笔记工具”：本项目从不主动落盘，仅返回指令；落盘动作来自智能体的自有工具。
• 误以为智能体必须每次都保存：README 明确写明 saves are prompt-driven，是否记录由智能体决定。
• 误把 MEMORY_FILE 当作路径：根据 README 描述，它只接受裸文件名（bare name only），用于切换 CLAUDE.md / GEMINI.md 等等价物，而不是指定子目录。

参见

• README.md — 项目总览、安装、配置
• package.json — 入口、依赖、Node 引擎要求

路径解析与配置

概述

agentsmd-memory 是一款零依赖的 MCP（Model Context Protocol）服务器，目标是在 AGENTS.md 中维护 AI 代理可访问的项目记忆。工具从不直接改写文件，而是解析出最近的目标文件后返回合并指令，再由代理使用自身编辑工具落盘——所有变更因此都以可审核的 git diff 形式呈现。资料来源：README.md:1-15

本 Wiki 页聚焦该项目的路径解析策略与配置入口，帮助读者理解其在多工作区环境下如何定位目标文件。

工作区与文件解析流程

服务器按下述顺序解析工作区目录：先取 MCP roots；否则使用 cwd 参数；最后回退到 process.cwd()。从工作区出发，沿目录向上查找直至 git 根；其中已存在的最近一个目标文件胜出。资料来源：README.md:32-37

该「最近存在者获胜」原则可保证在 monorepo 或嵌套子工程中，选择最贴近当前工作区的记忆文件，从而避免误用父目录的陈旧记录。

flowchart TD
    A[启动 MCP 服务器] --> B{MCP roots 可用?}
    B -- 是 --> C[取 roots 作为工作区]
    B -- 否 --> D{cwd 参数可用?}
    D -- 是 --> E[取 cwd 作为工作区]
    D -- 否 --> F[回退 process.cwd]
    C --> G[向上遍历至 git 根]
    E --> G
    F --> G
    G --> H{已存在目标文件?}
    H -- 是 --> I[选用最近的 AGENTS.md]
    H -- 否 --> J[引导创建缺失文件]

目标文件名与运行环境

项目通过环境变量 MEMORY_FILE 调整目标文件名，支持如 CLAUDE.md、GEMINI.md 等常见别名；该值必须为裸文件名，禁止出现路径分隔符，由前述算法决定最终落点。资料来源：README.md:27-31

package.json 同步声明运行环境与命令入口，便于 npx 等方式直接启动。type 设为 module，启用原生 ESM 加载，省去打包步骤。资料来源：package.json:5-7 engines.node 约束为 >=18，确保使用现代 Node 特性。资料来源：package.json:14-18 bin 字段把 agentsmd-memory 命令指向 src/index.mjs，与 main: src/server.mjs 配合，构成双入口（CLI + 模块加载）。scripts.test 与 scripts.prepublishOnly 均使用 node --test，零依赖即可完成回归验证。资料来源：package.json:18-22

引导写入与无副作用更新模型

服务器几乎从不主动写入文件。唯一会发生直接写入的场景，是首次调用 memory_save 时目标文件尚不存在，从而被自动引导创建（bootstrapping）。资料来源：README.md:34-37 其余所有调用——memory_save 持久化决策、约定或命令细节；memory_forget 移除陈旧条目——均仅返回合并指令，由代理自行落盘。资料来源：README.md:12-14

「调用是否发生」由代理在上下文中自行决定（prompt-driven），配置侧既不需要也无法预判保存时机。开发者使用 npm test 即可对该解析与合并逻辑进行回归验证。资料来源：package.json:18-22

参见

• README.md
• package.json

部署、运维与常见故障模式

1. 项目定位与运维边界

agentsmd-memory 是一个 零依赖 的 MCP（Model Context Protocol）服务器，核心目标是为 AI agent 提供一份"自我维护"的项目记忆文件 AGENTS.md。它的设计边界很关键：工具本身不直接编辑文件，而是返回合并指令，让 agent 用自身的文件编辑工具落地——如此所有变更都以 git diff 形式出现，便于人工审查与回滚。

资料来源：README.md:1-9

服务器只对外暴露两个工具：

• memory_save：记录一个持久化事实（决策、约定、坑点、非显然命令）。
• memory_forget：移除已过时的条目。

资料来源：README.md:11-14

2. 部署形态

仓库以 npm 包形式发布，包名 agentsmd-memory。package.json 中：

• bin.agentsmd-memory 指向 src/index.mjs，作为命令行入口。
• main 指向 src/server.mjs，作为被其它代码 import 的主模块。
• type: "module"，即纯 ESM 包。
• files 字段仅发布 src/、README.md、LICENSE。

资料来源：package.json:3-23

无需全局安装，MCP 客户端直接通过 npx 拉起。标准配置（取自 README）：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "agentsmd-memory"]
    }
  }
}

不同客户端命令略有差异：

• opencode：mcp 段中使用 "type": "local"。
• Claude Code：claude mcp add --transport stdio memory -- npx -y agentsmd-memory。
• Windows：需用 cmd /c npx -y agentsmd-memory 包装，避免裸 npx 在 cmd 解析下失败。

资料来源：README.md:16-30

3. 运行环境与配置

• Node 引擎：>=18（engines.node），低于此版本会因 ESM 与 API 差异失败。
• 依赖：零运行时依赖。
• 测试：npm test 走 Node 内置 node --test；prepublishOnly 钩子在发布前自动跑一次。
• 调试：npx @modelcontextprotocol/inspector npx -y agentsmd-memory 启动 MCP Inspector 手动连接。

资料来源：package.json:16-23、README.md:48-50

唯一的运行时配置项是环境变量 MEMORY_FILE：

资料来源：README.md:34-37

4. 工作区解析流程

README 明确说明了解析顺序，可视化为：

flowchart TD
    A[调用 memory_save / memory_forget] --> B{提供 MCP roots?}
    B -- 是 --> C[以 roots 为起点]
    B -- 否 --> D{调用方传 cwd?}
    D -- 是 --> E[以 cwd 为起点]
    D -- 否 --> F[回退到 process.cwd]
    C --> G[向上遍历到 git 根]
    E --> G
    F --> G
    G --> H{沿途已存在目标文件?}
    H -- 是 --> I[命中最近的那个]
    H -- 否 --> J[首次 memory_save 时引导创建]

要点：解析向上走到 git 根为止，并选取沿途已存在的"最近"一份；只有"bootstrap"那一次直接写盘——首次 memory_save 若文件不存在则创建，其余所有变更都走合并指令。

资料来源：README.md:39-44

5. 常见故障模式

资料来源：package.json:16-18

1. Node 版本低于 18：engines 不满足，安装或测试运行会直接报错。

资料来源：README.md:34-37

1. MEMORY_FILE 被误用为路径：README 强调"bare name only"，传 notes/AGENTS.md 等带路径的值会落到错误位置。

资料来源：README.md:39-44

1. 目录解析回退到 process.cwd()：若客户端既未声明 MCP roots、也未传 cwd，服务器只能使用当前工作目录；若 agent 实际项目在别处，记忆会被写到错误的仓库。

资料来源：README.md:39-44

1. 多层级 AGENTS.md 嵌套冲突：git 根与子目录同时存在目标文件时，解析会命中最近的那一份，子目录的指令可能与上层预期不符。

资料来源：README.md:41-44

1. 首次 bootstrap 写盘失败：唯一一次"直接写文件"发生在首次 memory_save。若目标目录只读、权限收紧或挂载在只读文件系统，bootstrap 失败会让后续所有保存操作都无处落地。

资料来源：README.md:43-44

1. 工具从未被调用：README 明确写"Saves are prompt-driven; the agent decides when to call them"。如果 agent 提示词没有引导、或模型不主动调用，记忆永远不会持久化——这是"零行为"类故障，需要从系统提示或 workflow 层面修复。

资料来源：README.md:24-30

1. Windows 下 stdio 启动失败：未用 cmd /c 包装时，裸 npx 在 Windows shell 解析下可能拿不到正确参数；遇到启动即断连，优先怀疑这一项。

资料来源：README.md:48-50

1. 本地调试缺乏 harness：仓库不依赖第三方测试框架；如需交互式调试，必须手动拉起 @modelcontextprotocol/inspector。

6. 发布与运维清单

资料来源：package.json:21-23

资料来源：package.json:6-18

• 发布前 prepublishOnly 会强制 node --test，保证发布版本通过测试。
• 运行时只读、最小权限也可运行，前提是目标目录在首次保存时可写。
• 升级时注意：仓库是 ESM 且 >=18，任何下游引入的 require() 都会失败。

See Also

• 工具语义与调用约定：见 README.md
• npm 包元信息与脚本：见 package.json

Pitfall Log / 踩坑日志

项目：jryom/agentsmd-memory

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/jryom/agentsmd-memory | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/jryom/agentsmd-memory | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/jryom/agentsmd-memory | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/jryom/agentsmd-memory | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/jryom/agentsmd-memory | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/jryom/agentsmd-memory | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/jryom/agentsmd-memory | release_recency=unknown