内容
# 代理内存
[](https://www.npmjs.com/package/agentsmd-memory)
[](https://github.com/jryom/agentsmd-memory/actions/workflows/publish.yml)
[](./LICENSE)
用于在 `AGENTS.md` 中保存项目记忆的 MCP 服务器。零依赖。
这些工具不会编辑文件。它们解析最近的记忆文件，并返回代理执行的指令，因此每次更改 - 甚至创建文件 - 都显示为可审查的 git diff。
## 工具
- `memory_save` — 记录一个持久的事实（决定、约定、陷阱、非显而易见的命令）。
- `memory_forget` — 删除一个过时的事实。
## 安装
在 npm 上发布为 [`agentsmd-memory`](https://www.npmjs.com/package/agentsmd-memory)。通过 `npx` 运行 - 不需要全局安装。客户端的配置模式不同；请在下面扩展您的配置。对于 Windows，请将命令包装为 `cmd /c npx -y agentsmd-memory`。
<details>
<summary><b>Claude 代码</b></summary>
```sh
claude mcp add --transport stdio memory -- npx -y agentsmd-memory
```
</details>
<details>
<summary><b>Claude 桌面版 / Cursor</b></summary>
`claude_desktop_config.json` 或 `.cursor/mcp.json`:
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "agentsmd-memory"]
}
}
}
```
</details>
<details>
<summary><b>opencode</b></summary>
`~/.config/opencode/opencode.json`. 注意区别：顶级 `mcp`（不是 `mcpServers`），`command` 是一个单独的 **数组**，环境变量放在 `environment`（不是 `env`）中。
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"memory": {
"type": "local",
"command": ["npx", "-y", "agentsmd-memory"],
"enabled": true
}
},
"plugin": ["agentsmd-memory"]
}
```
建议使用 `plugin` 行 - 请参见 [opencode 插件](#opencode-plugin-recommended)。它从 npm 按名称加载，因此需要 `agentsmd-memory >= 1.2.0`；编辑后请重启 opencode。
</details>
<details>
<summary><b>GitHub Copilot — VS Code</b></summary>
`.vscode/mcp.json`（项目）或您的用户 `mcp.json`。顶级键是 `servers`，类型是 `stdio`:
```json
{
"servers": {
"memory": {
"type": "stdio",
"command": "npx",
"args": ["-y", "agentsmd-memory"]
}
}
}
```
</details>
<details>
<summary><b>GitHub Copilot — CLI</b></summary>
```sh
copilot mcp add memory -- npx -y agentsmd-memory
```
或直接编辑 `~/.copilot/mcp-config.json`。Copilot CLI 需要 `type: "local"` 和一个 `tools` 字段:
```json
{
"mcpServers": {
"memory": {
"type": "local",
"command": "npx",
"args": ["-y", "agentsmd-memory"],
"tools": ["*"]
}
}
}
```
</details>
<details>
<summary><b>GitHub Copilot — coding 代理（仓库设置）</b></summary>
仓库 → **设置 → Copilot → MCP 服务器**。与 CLI 的形状相同（`type: "local"`，需要 `tools`）。任何环境变量必须以 `COPILOT_MCP_` 为前缀。
```json
{
"mcpServers": {
"memory": {
"type": "local",
"command": "npx",
"args": ["-y", "agentsmd-memory"],
"tools": ["*"]
}
}
}
```
</details>
### opencode 插件（推荐）
这些工具是基于提示的 - 代理只有在决定这样做时才会调用它们，这通常不会在任务中发生。该软件包还附带了一个 opencode 插件，每次回合都会向系统注入一个简短的提醒，以便代理可靠地调用 `memory_save`/`memory_forget`。通过上述 opencode 配置中的 `"plugin": ["agentsmd-memory"]` 行启用它。使用 `MEMORY_NUDGE` 环境变量覆盖提醒文本。
## 配置
| 环境变量 | 默认值 | 目的 |
| --- | --- | --- |
| `MEMORY_FILE` | `AGENTS.md` | 目标文件名，例如 `CLAUDE.md`、`GEMINI.md`。仅限裸文件名。 |
| `MEMORY_NUDGE` | 内置提醒 | 仅限 opencode 插件。覆盖每回合的提醒文本。要跳过注入，请勿加载插件。 |
## 注意
- 工作区目录从 MCP 根目录解析，否则使用 `cwd` 参数，否则使用 `process.cwd()`。从那里开始，它会遍历到 git 根目录；最近存在的文件获胜。
- 这些工具永远不会写入文件。当没有内存文件时，`memory_save` 返回创建文件的指令；代理使用其自己的写入工具编写文件，因此即使引导也显示为可审查的差异。
- 保存是基于提示的；代理决定何时调用它们。捆绑的 [opencode 插件](#opencode-plugin-recommended) 每回合都会提示它。
## 开发
```sh
npm test
npx @modelcontextprotocol/inspector npx -y agentsmd-memory
```
来源：[github.com/jryom/agentsmd-memory](https://github.com/jryom/agentsmd-memory)。
## 许可证
MIT
