agent-memory-mcp

# agent-memory-mcp > AI 编程代理的防护措施 — 编写一次规则，所有工具都遵守，破坏性操作被阻止。 [](https://github.com/xultrax-web/agent-memory-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://nodejs.org) [](https://modelcontextprotocol.io) [](cursor://anysphere.cursor-deeplink/mcp/install?name=agent-memory&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB4dWx0cmF4LXdlYi9hZ2VudC1tZW1vcnktbWNwIl19) [](https://smithery.ai/server/@xultrax-web/agent-memory-mcp) <!-- 30-second demo: drop the clip here once recorded →  --> 您的 AI 编程代理最终会尝试 `rm -rf` 错误的文件夹，强制推送到 `main`，或删除您实际需要的 文件。**agent-memory-mcp** 是内存层，您可以在此处编写规则 **一次**，以纯 Markdown 格式 — 并 **强制执行**： - **在协议层阻止破坏性操作。** 代理提出操作；服务器检查您的规则并拒绝或颁发短期、有签名的[合规收据](docs/compliance-receipt-protocol-1.0.md)，代理必须出示该收据才能执行操作。配置文件中的软规则将被忽略 — 此功能不会。 - **一条规则，所有工具。** 保存一次，它会自动发出到 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules/` 和 `.gemini/` — Claude Code、Cursor、Cline、Copilot、Gemini 和 Windsurf 读取相同的规则，无需插件。 - **您拥有的普通文件。** `cat` 它，`grep` 它，在 vim 中编辑它，提交到 git，使用 `agent-memory sync` 在机器之间同步它。无需数据库，无需守护进程，无需云 — 如果 AI 做错了，您可以在文本编辑器中修复。 内存 — 规则、配方、决策和上下文，这些在每个会话和每个工具中都存活下来 — 是基础。**强制执行是关键。** [合规收据协议 1.0](docs/compliance-receipt-protocol-1.0.md) 的参考实现，以便其他 MCP 服务器可以采用相同的收据并互操作。 ## 快速入门 · 60 秒内保护 ```bash # 在将服务器添加到您的 MCP 客户端（参见下面的安装）后，从您的项目： agent-memory init # 投入一个启动防护包（保护 main，不允许 rm -rf，不破坏 prod 数据等） agent-memory install-hooks # 使硬规则实际阻止 Claude Code 中的操作（软规则 → 请求） ``` 您的代理现在在每个工具中都受到保护。使用 `save_rule` 编写您自己的规则 — 它们强制执行并发出到 `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / `.gemini`。 （CLI 命令假设全局安装 — `npm i -g @xultrax-web/agent-memory-mcp` — 或使用 `npx -y` 前缀。） --- ## 内存作为约束 · v0.11 → v0.13 弧线 v0.10 及以下版本提供的内容：一个优秀的基于文件的内存存储。v0.11+ 新增内容：**强制执行自身的规则**。`rule` 内存类型带有 `severity`（硬/软）、`scope`、`applies_when`、`matches` 正则模式、`enforce_on` 类别和 `last_verified` 日期。从这些信息中，服务器将配套文件投影到每个 AI 工具中，并通过加密收据阻止破坏性操作。 ### 1. 规则内存投影到每个工具 ```bash agent-memory save-rule no-emojis-ever \ --description "Never use emojis in commits, comments, or chat output." \ --severity hard \ --scope global \ --enforce-on commits,chat_responses \ --content "No emojis. Anywhere. Ever." agent-memory emit-companions # writes AGENTS.md + CLAUDE.md + .cursor/rules/*.mdc + .gemini/instructions.md ``` | 目标 | 路径 | 自动加载的工具 | | -------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | | `agents` | `AGENTS.md` | Claude Code, Codex CLI, Cursor, Aider, Devin, Copilot, Gemini CLI, Windsurf, Amazon Q | | `claude` | `CLAUDE.md` | Claude Code (5 级层次结构 · 管理/全局/项目/本地/子目录) | | `cursor` | `.cursor/rules/operator-hard.mdc` (`alwaysApply: true`) + `operator-conventions.mdc` (agent-requested) | Cursor (MDC 格式) | | `gemini` | `.gemini/instructions.md` | Gemini CLI | 设置 `AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project`，服务器会自动重新发出所有四个文件。 ### 2. `check_action` · 协议强制执行点 ```bash # 代理提出操作 · 服务器匹配规则存储 agent-memory check-action "delete the memory called old-project-notes" --type deletions # → 审批后：返回代理传递给破坏性工具的合规收据 # → 拒绝：返回结构化的 hard_violations + soft_warnings ``` MCP 形状： ```jsonc { "name": "check_action", "arguments": { "action": "delete the memory called old-project-notes", "action_type": "deletions", "session_id": "sess_abc", }, } ``` **Tier 1** （确定性，每个客户端）：操作与 `rule.matches` 正则表达式匹配，根据 `rule.enforce_on` 筛选。硬违规阻止。软违规警告。批准的操作会获得一个新鲜的收据，TTL 为 60 秒。 **Tier 2** （采样增强，v0.11.7 发货）：对于具有 `applies_when` 自然语言条件的规则，服务器使用 MCP 采样询问客户端的 LLM 提案的操作是否触发规则。如果客户端不宣传采样能力，则回落到仅 Tier 1。Claude Desktop 和 VS Code Copilot 上有效；Claude Code、Cursor、Cline 和 Codex CLI 上仅限 Tier 1 — 足以强制执行您编写的规则。 但是，`check_action` 只会阻止 **此服务器自己的** 工具。为了在代理的 **实际** 操作上强制执行您的规则 — 它运行的 shell 命令和文件写入 — **`agent-memory install-hooks`** 将 `PreToolUse` 钩子连接到 Claude Code：**硬** 规则 **拒绝** 匹配的工具调用，**软** 规则 **询问** 您。现在 `rm -rf` 或强制推送到 `main` 实际上被 **阻止**，而不仅仅是建议。运行 `agent-memory init` 以获取启动规则集。 ### 3. 合规收据 · 加密原语 收据是短暂的、签名的 bearer token，具有注意事项（Macaroon 模式 · [Birgisson 等人，NDSS 2014](https://research.google/pubs/pub41892/)）。新型协议原语：服务器颁发的令牌绑定到操作 + 会话 + 规则版本哈希 + 过期时间。篡改会破坏签名。规则更改会使所有未完成的收据失效（因为 `rules_version` 是签名有效载荷的一部分）。 ```typescript import { issueReceipt, validateReceipt } from "@xultrax-web/agent-memory-mcp"; const r = issueReceipt({ caveats: [ { type: "action", value: "delete_memory" }, { type: "session", value: "sess_abc123" }, ], ttl_seconds: 60, }); const v = validateReceipt(r, { required_caveats: [{ type: "action", value: "delete_memory" }], }); if (!v.valid) throw new Error(v.reason); ``` **需要收据的 `delete_memory` （v0.12.0 破坏性更改）：** 调用 `delete_memory` 时没有有效的收据会被拒绝。两步模式为 `check_action` → `delete_memory(name, receipt)`。签名密钥文件位于 `<MEMORY_DIR>/.keyring/hmac-key` （CRP 1.0）或 `<MEMORY_DIR>/.keyring/ed25519-priv` （CRP 1.1），POSIX 上为 `0600` 权限。收据与其特定目标绑定（用于 `delete memory <name>` 的 `action_hash` 注意事项），并且是一次性的；`.keyring/` **永远不会被提交或同步**，而 `rotate_key` 在怀疑泄漏后重新生成。 **CRP 1.1 · Ed25519 联邦（v0.13.0）：** 切换 `CRP_SIGNING_MODE=ed25519`，服务器使用非对称密钥对签名而不是 HMAC。公钥发布在 `<MEMORY_DIR>/.keyring/ed25519-pub`，因此其他 MCP 服务器可以在不共享密钥的情况下验证您的收据。该协议允许跨服务器强制执行：服务器 A 发布收据以删除“X”，服务器 B 验证并遵守它。 ### 4. `audit` · 规则存储的运行健康状况 ```bash agent-memory audit # 漂亮的彩色终端输出 agent-memory audit --json # 结构化的 JSON 用于工具 ``` 显示： - 按严重性（硬/软/未指定）划分的规则数量 - **过时的规则** · `last_verified` > 90 天，或从未验证 - **模式冲突** · 两个规则共享一个 `enforce_on` 和 `matches` 中的相同正则表达式 - **最近的拒绝** · `check_action` 调用阻止了操作（发现过于激进的规则） - **未收到的破坏性操作** · 在 v0.12+ 中应为空；非空意味着客户端在调用 `delete_memory` 时没有经过 `check_action` `healthy` 标志在没有过期规则、冲突或未收到的操作时为真。 ### 5. CRP 1.0 / 1.1 作为可移植规范 收据协议单独记录在 [docs/compliance-receipt-protocol-1.0.md](docs/compliance-receipt-protocol-1.0.md)。其他 MCP 服务器可以采用相同的格式 + 验证规则以互操作。`agent-memory-mcp` 是参考实现。该规范涵盖收据结构、规范编码、签名（1.0 的 HMAC-SHA256，1.1 的 Ed25519）、验证顺序、规则版本哈希、保留的注意事项类型、MCP 集成模式、安全考虑、跨服务器采用和测试向量。 --- ## 您获得的内容 ```text .agent-memory/ ├── MEMORY.md # 自动管理的索引 ├── user-prefers-tabs.md ├── feedback-no-emoji-in-code.md ├── project-q3-launch-frozen.md └── reference-postgres-runbook.md ``` 内存文件只是带有 YAML 前置元数据的 Markdown： ```markdown --- name: feedback-no-emoji-in-code description: 用户希望在提交、评论或输出中没有表情符号 type: feedback --- 硬规则。任何用户界面都不允许有表情符号。 **原因：** 前承包商用它们淹没了仓库；用户花了一个周末删除它们。 **如何应用：** 在提交前清理；拒绝任何自动添加它们的工具输出。 ``` 就是这种格式。没有魔法。阅读它，编辑它，发送它。 --- ## 为什么存在 大多数 MCP 客户端没有持久内存。那些有持久内存的客户端（Claude Code）将内存存储在只有该客户端可以看到的地方。官方的 `server-memory` 和其他社区替代品使用不透明的结构化后端。这对于某些工作流程来说是可以的 — 但它将您的数据放在您无法用 `cat` 读取的层后面。 我们选择 Markdown 因为： - **通用。** 每个开发者都可以阅读 Markdown。每个编辑器都支持它。每个 diff 工具都理解它。 - **可移植。** 内存随项目（默认）或随您（全局模式）移动。移动、复制、fork 它们 — 它们只是文件。 - **可检查。** 您可以通过打开文件夹来审计您的 AI 助手“知道什么”。 - **可修复。** 当内存错误时，您像修复任何文本文件一样修复它。无需 SDK、无需 API、无需 SQL。 - **版本控制。** Git 了解每次更改。没有 JSON 合并冲突。没有二进制 blob。 如果您想要向量相似性搜索、语义回忆或自动关系提取 — 请使用基于数据库的内存 MCP。它们擅长于此。如果您想要在断电后仍然可以阅读的内存，这就是为您准备的。 --- ## 安装 ### 从 npm （推荐） ```bash npx -y @xultrax-web/agent-memory-mcp ``` ### 列在 MCP 注册表中 `io.github.xultrax-web/agent-memory-mcp` · 在 https://registry.modelcontextprotocol.io 上浏览 ### 本地构建 ```bash git clone https://github.com/xultrax-web/agent-memory-mcp cd agent-memory-mcp npm install npm run build node dist/index.js ``` 服务器通过 stdio 进行 MCP 通信。您不直接运行它 — 您的 MCP 客户端启动它。 --- ## 客户端配置 每个客户端的 JSON 配置文件路径略有不同。 ### Cursor `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）： ```json { "mcpServers": { "agent-memory": { "command": "npx", "args": ["-y", "@xultrax-web/agent-memory-mcp"] } } } ``` ### Cline（VS Code 扩展） Cline → MCP 服务器 → 添加： ```json { "agent-memory": { "command": "npx", "args": ["-y", "@xultrax-web/agent-memory-mcp"] } } ``` ### VS Code（Copilot Chat） > **两个 VS Code 路径。** 上面的 Cline 部分专门针对 Cline 扩展本身（其自己的 MCP 服务器 UI）。本部分适用于 VS Code 的原生 MCP 支持 — GitHub Copilot Chat 直接读取它。选择与您的助手匹配的工具；两者可以共存。 `.vscode/mcp.json`（工作区）或通过用户设置 → 编辑 `mcp.json`: ```json { "servers": { "agent-memory": { "type": "stdio", "command": "npx", "args": ["-y", "@xultrax-web/agent-memory-mcp"] } } } ``` ### Claude Desktop `%APPDATA%\Claude\claude_desktop_config.json`（Windows）或 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）： ```json { "mcpServers": { "agent-memory": { "command": "npx", "args": ["-y", "@xultrax-web/agent-memory-mcp"] } } } ``` > **Windows 注意：** 如果 `npx` 无法干净地解析，请用 `cmd /c` 包装： > > ```json > { "command": "cmd", "args": ["/c", "npx", "-y", "@xultrax-web/agent-memory-mcp"] } > ``` ### Continue.dev `~/.continue/config.json`: ```json { "experimental": { "modelContextProtocolServers": [ { "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@xultrax-web/agent-memory-mcp"] } } ] } } ``` ### 存储范围 默认情况下，按项目（默认）：内存位于客户端启动服务器的目录下的 `./.agent-memory/`。通常这是项目根目录。 个人/全局池： ```json "env": { "AGENT_MEMORY_SCOPE": "global" } ``` 全局内存位于 `~/.agent-memory/`。 自定义路径： ```json "env": { "AGENT_MEMORY_DIR": "/abs/path/to/memory" } ``` ## 工具 | 工具 | 用途 | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `save_memory` | 创建或更新一个记忆。原子写入 + 锁定。验证名称 + 类型。更新索引。 | | `search_memories` | 模糊搜索（Fuse.js · 容错、词序容错、部分匹配）。返回 top N 及相关性评分（0-100）+ 正文片段。 | | `relevant_memories` | 与搜索相同的匹配规则，但返回完整的记忆主体作为一个 Markdown 文档。为 LLM 自动上下文构建。 | | `get_memory` | 按名称获取一个记忆。返回前置信息 + 正文。 | | `list_memories` | 列出记忆。可选按类型过滤。分页（默认 50/页）。 | | `delete_memory` | **需要回执、目标绑定、单次使用**。传递 `check_action({action:'delete memory <name>', action_type:'deletions'})` 的合规回执 — 绑定到该确切记忆（通过 `action_hash` 限制）且仅可使用一次。软删除到 `.trash/<ts>-<name>.md`。 | | `restore_memory` | 从 `.trash/` 恢复软删除的记忆。选取该名称下最近的回收站条目。 | | `doctor` | 存储完整性检查。报告孤立文件、悬挂索引条目、不可读文件。传递 `rebuild-index=true` 以从磁盘修复 `MEMORY.md`。 | | `stats` | 仪表盘：按类型计数、总大小、最大记忆、审计日志大小、回收站计数。 | | `log_events` | 读取审计事件日志的最近条目。可选 `tail`（默认 20）+ `action` 过滤。 | | `verify_memory` | 重新评估一个记忆的主张。提取 URL/日期/文件引用，标记过期日期信号，返回类型特定的验证启发式。与 `audit_stale` 提示配对。 | | `find_backlinks` | 列出通过记忆体正文中的 `[[wiki-link]]` 语法链接到给定记忆的记忆体。有助于查看“哪些引用了此记忆”。 | | `find_related` | 通过组合 outbound links、inbound backlinks、shared tags、类型匹配和内容相似性，展现与一个记忆相关的记忆体。通过关联导航记忆图。 | | `sync_status` | 报告 git-sync 状态：远程 URL、分支、未提交的本地文件、领先/落后于源。 | | `sync_push` | 提交本地记忆更改 + 推送到配置的 git 远程。自动为提交消息添加时间戳（如果未提供）。 | | `sync_pull` | 从 git 远程快速拉取。拒绝拉取如果本地更改未提交。 | | `save_rule` | **v0.11+.** 创建或更新一个带有 `severity` / `scope` / `matches` / `enforce_on` / `applies_when` / `last_verified` 的 `rule` 记忆体。自动发出伴侣文件（如果配置）。 | | `list_rules` | **v0.11+.** 列出规则记忆体，可选按严重性或强制类别过滤。 | | `emit_companions` | **v0.11.1+.** 将规则存储投影到 `AGENTS.md` + `CLAUDE.md` + `.cursor/rules/*.mdc` + `.gemini/instructions.md`。传递 `target` 以过滤。 | | `check_action` | **v0.11.3+.** Tier-1 确定性 + Tier-2 采样规则检查。返回 `{approved, hard_violations, soft_warnings, receipt?}`。协议强制执行点。 | | `audit` | **v0.11.4+.** 规则存储的运行健康检查：过期规则、模式冲突、最近拒绝、未接收的破坏性操作。返回 JSON 或美观打印。 | | `rotate_key` | **v0.14+.** 旋转接收签名 HMAC / Ed25519 密钥，使所有未过期的接收无效。密钥泄露后的补救措施。可选 `mode`：`hmac` \| `ed25519` \| `both`。 | | `init` | **v0.15+.** 安装一个启动守卫包（保护 main、不允许 rm -rf、不允许 prod 数据销毁、不允许 curl\|sh、标记秘密）并将其发出到每个工具。`force=true` 覆盖现有配置。 | | `validate_receipt` | **v0.15+.** 使用公钥验证另一个服务器的 CRP 1.1（Ed25519）接收。这是联邦的基本操作。传递 `receipt` + `public_key`（内联 PEM 或文件路径）。 | ### 提示 服务器暴露了 4 个内置的 MCP 提示，客户端（如 Claude Desktop、Cursor 等）将其作为斜杠命令显示。这些提示将记忆转化为一个主动的工作流层，而不仅仅是一个被动存储： | 提示 | 参数 | 功能 | | ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `extract_memories` | 无参数 | LLM 扫描当前对话，提出候选记忆，并为每个记忆调用 `save_memory`（选择类型 + 描述）。 | | `summarize_topic` | `topic` | LLM 通过 `relevant_memories` 拉取与主题相关的记忆，并将它们合成一个带有引用的摘要。 | | `prepare_handoff` | `project`（可选） | LLM 遍历与筛选器匹配的 project 类型记忆，并组装一个结构化的移交文档（当前状态、开放项、注意事项）。 | | `audit_stale` | 无参数 | LLM 评估 project + reference 记忆的过期情况，并生成一个分类列表（可能过期 / 值得验证 / 仍然新鲜）。 | ### 记忆类型 五种内置类型。前四种与 Claude Code 约定匹配；`rule` 是 v0.11 新增的： - **user** — 关于人的事实（角色、偏好、专业水平） - **feedback** — 助手的软性指导（偏好此样式、倾向于该方法） - **project** — 代码中没有的当前状态上下文（截止日期、正在进行的工作） - **reference** — 指向外部系统的指针（Linear 板块 URL、监控仪表盘） - **rule** — 要强制执行的约束，而不仅仅是事实。携带 `severity`、`scope`、`matches`、`enforce_on`、`applies_when`、`last_verified`。投影到伴侣文件；控制 `check_action`。 ### 标签 + 维基链接 除了类型之外，还有两种跨越组织的功能： **标签** — 前置信息中的可选 `tags: [a, b, c]` 数组。可通过 `list_memories({tags: [...]})` 和 `agent-memory list --tags "a,b"` CLI 查询。过滤器为交集 — 记忆必须具有所有列出的标签。标签名称为小写 a-z + 数字 + 连字符/下划线，最大 40 个字符。 ```markdown --- name: deploy-process description: 蓝绿生产部署 type: project tags: [deployment, production, critical] --- ``` **维基链接** — 在记忆体正文中写入 `[[memory-name]]`，它将成为一个链接。`find_backlinks` 返回引用给定记忆体的记忆体；`find_related` 排名整个图谱（出站链接、入站反向链接、共享标签、内容相似性）以便发现导航。 --- ## 命令行界面 同一个二进制文件也是一个命令行工具。在 shell 脚本、git 钩子、cron 或编辑器外的快速查找非常有用。 ```bash agent-memory save user-likes-tabs --type user --description "喜欢使用标签" --content "始终在新文件中启用标签。" agent-memory list agent-memory list --type feedback agent-memory search "标签" # 模糊搜索，top 10 按相关性 agent-memory search "depoy" --limit 5 # 容错（"depoy" → "deploy"） agent-memory relevant "部署" --max 3 # 完整的记忆体，LLM-ready agent-memory get user-likes-tabs agent-memory list --limit 20 --offset 40 # 分页 agent-memory delete user-likes-tabs # 软删除 — 移动到 .trash/ agent-memory restore user-likes-tabs # 恢复最近的回收站条目 agent-memory doctor # 检查完整性 agent-memory doctor --rebuild-index # 从磁盘修复 MEMORY.md agent-memory stats # 仪表盘：计数、大小、审计/回收站 agent-memory log # 最近 20 条审计日志条目 agent-memory log --tail 50 --action delete # 按操作、尾部大小过滤 agent-memory verify deploy-process # 提取 URL/日期/文件引用 + 过期启发式 agent-memory save my-mem --type project --description "X" --content "主体" --tags "production,critical" agent-memory list --tags "production" # 按标签过滤（交集） agent-memory backlinks deploy-process # 链接到 deploy-process 的记忆体 agent-memory related deploy-process # 排名发现：链接 + 标签 + 相似性 agent-memory sync init git@github.com:you/agent-memory.git # 多机器设置（一次性） agent-memory sync push # 提交 + 推送本地更改 agent-memory sync pull # 从远程快速拉取 agent-memory sync status # 本地 + 领先/落后状态 agent-memory ui # 启动 TUI（交互式浏览 + 编辑） # v0.11+ · 规则和强制执行 agent-memory save-rule no-emoji --severity hard --enforce-on commits,chat_responses \ --matches "emoji|:[a-z_]+:" --content "不允许表情符号。在任何地方。任何时候。" agent-memory list-rules # 仅规则记忆体 agent-memory list-rules --severity hard # 按严重性过滤 agent-memory emit-companions # 编写 AGENTS.md + CLAUDE.md + .cursor/rules + .gemini agent-memory emit-companions --target agents,claude # 过滤目标 agent-memory check-action "delete old notes" --type deletions # 返回批准 + 接收 JSON agent-memory audit # 美观的运行健康报告 agent-memory audit --json # 结构化 JSON 用于工具 ``` ### 多机器记忆（git 同步） 文件基记忆的杀手级功能：每台开发机器都有 git，markdown 合并干净。`agent-memory sync` 将 `.agent-memory/` 变成一个 git 仓库，指向一个（私有）远程仓库，您的记忆随您在桌面/笔记本/服务器之间移动。 ```bash # 一次性设置 agent-memory sync init git@github.com:you/agent-memory.git # 桌面上的一天结束 agent-memory sync push # 睡觉前使用笔记本 agent-memory sync pull # 在床上保存一个新记忆 agent-memory save bedtime-thought --type project --description "..." --content "..." agent-memory sync push # 第二天早上在桌面 agent-memory sync pull # 获取 bedtime 记忆 ``` 未同步的内容（每台机器状态，保持本地）： - `.lock` — 每进程文件锁 - `.events.jsonl` — 每台机器的审计轨迹 - `.trash/` — 软删除暂存 同步内容：每个记忆文件、`MEMORY.md` 索引以及您添加的任何 `.gitignore`。 默认情况下，提交使用身份 `agent-memory <agent-memory@local>` — 如果您希望按机器归属，请在环境中设置 `GIT_AUTHOR_EMAIL` / `GIT_COMMITTER_EMAIL`。 ### 审计日志 + 结构化日志 每次变更都会在 `.agent-memory/.events.jsonl` 中追加一行 JSON： ```jsonl {"ts":"2026-05-22T04:02:38.536Z","action":"save","name":"first-mem","type":"user","update":false,"bytes":6} {"ts":"2026-05-22T04:02:39.414Z","action":"delete","name":"second-mem","trash":"1779422559413-second-mem.md"} {"ts":"2026-05-22T04:02:39.712Z","action":"restore","name":"second-mem","binnedAt":"2026-05-22T04:02:39.413Z"} ``` 您可以以任意方式读取它：`cat`、`jq`、`log` / `log_events` 工具或将它发送到您的可观测性堆栈的侧车。 操作日志是分开的。设置 `AGENT_MEMORY_LOG=debug|info|warn|error`（默认为 `info`），结构化行流式传输到 stderr — 不会污染 MCP stdio 通道。 TTY 中默认启用颜色输出。设置 `NO_COLOR=1` 以禁用，`FORCE_COLOR=1` 以强制在管道中启用。 多行内容可以来自文件或 stdin： ```bash agent-memory save my-handoff --type project --description "Q3 移交笔记" --content-file handoff.md cat conversation.txt | agent-memory save extracted-prefs --type user --description "从聊天中提取" --stdin ``` ### 从 Claude Code 导入 如果您一直在使用 Claude Code 的内置记忆，请将其导入： ```bash # 查看将导入的内容（干运行，无写入） agent-memory import-claude-code --dry-run # 按子字符串匹配筛选到一个项目（不区分大小写） agent-memory import-claude-code --project prefixcheck --dry-run # 执行导入 agent-memory import-claude-code --project prefixcheck # 替换具有相同名称的现有记忆 agent-memory import-claude-code --project prefixcheck --overwrite ``` 导入程序遍历 `~/.claude/projects/*/memory/`，解析每个记忆的 YAML 前置信息（容错 — 格式错误的 文件不会导致运行失败），将 Claude Code 的 `metadata.type` 字段展平到顶级 `type`，并写入当前存储。除非您传递 `--overwrite`，否则具有相同名称的现有记忆将被跳过。 --- ## 为什么使用文件而非数据库 您放弃了原生语义相似性搜索和结构化实体关系查询。您获得了在每次工具更改、每次机器更换、每次“等等，这个 AI 六个月前告诉我关于这个代码库的事情是什么？”之后仍然存活的记忆存储 — 以及在断电后仍然可以读取的存储。 这笔交易是真实的。对于需要向量召回或图查询的工作流，基于数据库的内存是合适的工具。对于需要 grep、编辑、版本控制和手动审计的工作流，这是合适的。 ## 从设计之初就具备运营级别 这台服务器的设计目的是每天都可以使用，而不是仅仅演示一次。 **v0.3 版本中发布的内容：** - **原子写入** — 使用 tmp 文件 + 重命名模式。电力损失永远不会留下未完成的写入文件。 - **文件锁定** — 在每次修改时使用 `proper-lockfile` 进行锁定。多台 MCP 服务器和 CLI 访问无法损坏索引。 - **软删除** — `delete_memory` 移动到 `.trash/<timestamp>-<name>.md`。`restore_memory` 可以将其恢复。 - **索引恢复** — `agent-memory doctor` 报告孤立文件、悬空条目和解析错误。`--rebuild-index` 从磁盘重写 `MEMORY.md`。 - **模式版本控制** — 每个内存文件都包含一个 `schema: 1` 字段，以便未来格式更改可以干净地迁移。 - **符合规范的资源** — `agent-memory://index` 和 `agent-memory://memory/{name}`；客户端可以像往常一样将它们固定为始终可见的上下文。 **v0.4 版本中发布的内容：** - **仅追加事件日志** 在 `.events.jsonl` — 每次带有时间戳和 JSON 结构的修改，用于审计。 - **`agent-memory stats`** — 按类型计数的仪表板，总数/平均值/最大值，审计和垃圾计数。 - **`agent-memory log`** — 事件日志的可分页浏览器，可按操作筛选。 - **结构化 stderr 日志** — `AGENT_MEMORY_LOG=debug|info|warn|error`；可以安全地与 MCP 标准输入/输出一起使用。 - **颜色输出** — 通过 TTY 自动检测，尊重 `NO_COLOR` / `FORCE_COLOR`。 **v0.5 版本中发布的内容：** - **Fuse.js 模糊搜索** 带有字段权重（名称×3，描述×2，正文×1）。容忍输入错误，部分匹配和词序。 - **代码片段高亮** — 在每个匹配项下显示正文上下文摘录，带有 `...` 标记。 - **相关性评分** — Fuse 评分反转并缩放为 0-100 以适应人类阅读。 - **`relevant_memories(query, max=5)`** — 搜索的配套工具，返回完整的内存正文作为单个 Markdown 文档，为 LLM 自动上下文加载而构建。 - **分页** — `list_memories` 和 `search_memories` 上的 `offset` + `limit`。 **v0.6 版本中发布的内容：** - **Vitest 测试套件** — 25+ 黑盒测试覆盖 CLI + MCP 服务器路径。 - **GitHub Actions CI** — 在每个推送/拉取请求上运行测试，涵盖 Node 20/22/24。 - **[COMPATIBILITY.md](COMPATIBILITY.md)** — 已知工作的客户端矩阵 + 怪癖。 **v0.7 版本中发布的内容：活跃的上下文层：** - **MCP 提示功能** — 4 个内置工作流（`extract_memories`、`summarize_topic`、`prepare_handoff`、`audit_stale`），客户端将其作为斜杠命令显示。 - **`verify_memory` 工具** — 内存的 URL/日期/文件引用的静态分析，带有类型特定的过时启发式。加上匹配的 `agent-memory verify <name>` CLI。 - **保存时的冲突检测** — 模糊匹配新的内存与现有的内存；警告近似重复项而不阻止保存（以便 LLM 可以决定是否合并，重命名或继续）。 **v0.8 版本中发布的内容：大规模组织：** - **标签** — 前面部分可选的 `tags: [...]` 数组。可通过 `list_memories` 和 `agent-memory list --tags "a,b"` 查询。交集过滤。 - **`[[wiki-links]]`** — 在任何内存正文中写入 `[[memory-name]]`，自动检测。 - **`find_backlinks`** 工具 + `agent-memory backlinks <name>` CLI — “有哪些链接到这？” - **`find_related`** 工具 + `agent-memory related <name>` CLI — 将输出链接、共享标签、类型匹配和内容相似性组合成排名后的发现视图。 **v0.9 版本中发布的内容：护城河 — 通过 git 实现多机器内存：** - **`agent-memory sync init <remote-url>`** — 将 `.agent-memory/` 转换为 git 仓库，推送到远程。 - **`agent-memory sync push`** — 自动提交本地更改 + 推送。 - **`agent-memory sync pull`** — 从远程快速前进。 - **`agent-memory sync status`** — 本地状态 + 提交超前/落后源。 - **`agent-memory sync log`** — 跨机器内存更改的历史记录。 - **`sync_status` / `sync_push` / `sync_pull` MCP 工具** — LLM 也可以做到这一点。 - 每个机器的状态（`.lock`、`.events.jsonl`、`.trash/`）自动从同步中排除。 - 默认提交身份注入（`agent-memory@local`），因此没有 `git config --global user.email` 的机器无需设置即可工作。 **v0.10 版本中发布的内容：视觉身份（TUI）：** - **`agent-memory ui`** — 基于 Ink 的终端 UI，用于浏览、筛选、搜索和编辑内存，而无需离开终端。 - 类型筛选快捷键（0-4 循环浏览所有/用户/反馈/项目/引用） - 带有 `/` 的模糊实时搜索 - `e` 在 `$EDITOR` 中打开高亮的内存（vim/notepad/nano/whatever）— 保存到磁盘 - `d` 软删除，带有 `y/n` 确认 - 详细面板预览所选内存的正文 - 按类型编码，标签芯片内联 **v0.11 版本中发布的内容：内存作为约束：** - `rule` 内存类型，带有 `severity` / `scope` / `matches` / `enforce_on` / `applies_when` / `last_verified` - `save_rule` + `list_rules` 工具和 CLI 命令 - `emit_companions` 项目规则到 `AGENTS.md` + `CLAUDE.md` + `.cursor/rules/*.mdc` + `.gemini/instructions.md` - `AGENT_MEMORY_AUTO_EMIT_DIR` 在每次规则保存时触发重新发射 - **合规收据**（`issueReceipt` / `validateReceipt`）— 带有 Macaroon 式限制的 HMAC-SHA256 承载令牌，与 `rules_version` 绑定，因此规则更改使未完成的令牌失效 - `check_action` MCP 工具（第 1 级确定性；第 2 级采样增强，适用于 v0.11.7 及以上版本，适用于声明该功能的客户端） - `audit` 命令 — 过时规则、模式冲突、最近拒绝、未收到的破坏性操作 - [CRP 1.0 协议规范](docs/compliance-receipt-protocol-1.0.md) — 便携、厂商中立 **v0.12 版本中发布的内容：楔形（破坏性更改）：** - `delete_memory` 需要有效的收据。没有收据的调用在工具边界被拒绝。 - 两步模式是规范的：`check_action` → 收据 → `delete_memory(name, receipt)` - 审计日志不再需要一个“未收到的操作”警告类别来显示异常 — 没有异常 **v0.13 版本中发布的内容：跨服务器联合：** - CRP 1.1 · Ed25519 非对称签名（设置 `CRP_SIGNING_MODE=ed25519`） - 公钥发布在 `<MEMORY_DIR>/.keyring/ed25519-pub`，以便其他服务器在不共享密钥的情况下进行验证 - 9 个专用 Ed25519 测试，验证密钥对生成、签名和跨服务器验证路径 --- ## 路线图 ### 已发布 | 版本号 | 亮点 | | --------- | --------------------------------------------------------------------------------------------------- | | v0.1 | 五工具 MVP，文件存储，四个客户端配置片段 | | v0.2 | MCP 资源，Claude 代码导入（`agent-memory import-claude-code`），CLI 模式，预ttier 基线 | | v0.3 | 原子写入，文件锁定，软删除 + `restore_memory`，`doctor` 修复，模式版本控制 | | v0.4 | 仅追加事件日志（`.events.jsonl`），`stats` 仪表板，`log_events` 浏览器，颜色输出 | | v0.5 | Fuse.js 模糊搜索，相关性评分，正文上下文片段，`relevant_memories`，分页 | | v0.6 | 25+ Vitest 测试，GitHub Actions CI（Node 20/22/24 矩阵），`COMPATIBILITY.md` | | v0.7 | MCP 提示（4 个启动工作流），`verify_memory`，保存时的冲突检测 | | v0.8 | 标签，`[[wiki-links]]`，`find_backlinks`，`find_related` | | v0.8.1 | 受信任的发布 · 无令牌 OIDC 发布到 npm + MCP 注册表，在 git 标签上 | | v0.9 | `agent-memory sync` · 多机器内存通过 git 远程（init/push/pull/status/log） | | v0.10 | 基于 Ink 的 TUI · `agent-memory ui` 用于视觉浏览、搜索和编辑 | | v0.11.0 | `rule` 内存类型 + `AGENTS.md` 伴侣发射器 | | v0.11.1 | `CLAUDE.md` + `.cursor/rules/*.mdc` + `.gemini/instructions.md` 发射器 | | v0.11.2 | 合规收据基元 · 带有 Macaroon 式限制的 HMAC-SHA256 令牌 | | v0.11.3 | `check_action` MCP 工具（第 1 级确定性）+ 收据门控 `delete_memory`（按需） | | v0.11.4 | `audit` 命令 · 过时规则、模式冲突、最近拒绝、未收到的操作 | | v0.11.5 | CRP 1.0 协议规范 — 便携、厂商中立的强制执行基元 | | v0.11.6 | 重新定位 · “编纂你的工作方式，每个 AI 工具都遵守” | | v0.11.7 | 第 2 级采样增强的 `check_action` · LLM 在有能力的客户端上判断 `applies_when` | | **v0.12** | **删除内存时需要收据 · 破坏性更改 · 楔形成功** | | **v0.13** | **CRP 1.1 · Ed25519 非对称签名用于跨服务器联合** | ### 即将推出 - 收据门控 `restore_memory` 和 `doctor --rebuild-index`（相同的 `check_action` 流） - 联盟示例 · 第二个参考 MCP 服务器，发布并验证 CRP 1.1 收据 - 自动上下文加载 — 服务器钩子，在每个 LLM 轮次之前自动触发 `relevant_memories` - 存储内文件夹支持（`.agent-memory/work/`、`.agent-memory/personal/`） - 内存包 — 导出/导入可共享的 `.tar.gz` 内存包 - 浏览器伴侣 UI（`agent-memory web`） - TUI 润色 — 文件监视以自动刷新、内联编辑、同步作为按键绑定 ### 更进一步 可选的本地嵌入侧车（transformers.js，无 API），团队模式带有差异/合并，浏览器扩展以从 chatgpt.com / claude.ai → 内存、移动伴侣捕获。 如果您希望在下一个版本之前实现上述功能，请提交问题。 --- ## 许可证 MIT。随心所欲使用。 --- ## 作者 [@xultrax-web](https://github.com/xultrax-web) · 为了解决我一直遇到的跨客户端内存问题而构建。[PrefixCheck Labs](https://prefixcheck.com/labs/) 的一部分。 灵感来自 Anthropic 的 Claude Code 中基于文件的内存系统。