agent-memory-mcp

agent-memory-mcp

为 AI 编码 Agent 提供防护措施——规则只需编写一次，所有工具都会遵守，并阻止破坏性操作。

你的 AI 编码 Agent 迟早会试图对错误的文件夹执行 rm -rf、向 main 强制推送，或删除你真正需要的文件。agent-memory-mcp 是一个记忆层，你只需用纯 Markdown 编写一次规则，它就会_自动强制执行_：

• 在协议层阻止破坏性操作。 Agent 提出操作后，服务会根据你的规则进行检查，要么拒绝操作，要么签发一份短期有效的签名合规回执，Agent 必须出示回执才能执行操作。配置文件中的软性规则会被忽略——而它不会。
• 一条规则，适用于所有工具。 只需保存一次，它就会自动生成到 AGENTS.md、CLAUDE.md、.cursor/rules/ 和 .gemini/ 中——Claude Code、Cursor、Cline、Copilot、Gemini 和 Windsurf 无需插件即可读取相同的规则。
• 由你掌控的纯文本文件。 用 cat 查看、用 grep 搜索、用 vim 编辑、提交到 git，再用 agent-memory sync 在多台机器间同步。没有数据库、没有守护进程、没有云服务——如果 AI 出错，你可以用文本编辑器修正。

记忆——那些能在每次会话和每种工具中留存的规则、配方、决策和上下文——是基础。**强制执行才是关键。**这是合规回执协议 1.0的参考实现，其他 MCP 服务也可以采用相同的回执并实现互操作。

快速开始 · 60 秒完成防护

# After adding the server to your MCP client (see Install below), from your project:
agent-memory init            # drop in a starter guardrail pack (protect main, no rm -rf, no prod-data destruction, …)
agent-memory install-hooks   # make hard rules actually BLOCK in Claude Code (soft rules → ask)

现在，你的 Agent 已在所有工具中受到防护。使用 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（hard / soft）、scope、applies_when、matches 正则表达式模式、enforce_on 类别和 last_verified 日期。服务会据此将内容生成到各个 AI 工具的配套文件中，并通过加密回执限制破坏性操作。

1. 将规则记忆同步到每个工具

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 级层级结构 · managed/global/project/local/subdir）
cursor	.cursor/rules/operator-hard.mdc (alwaysApply: true) + operator-conventions.mdc（由 Agent 请求）	Cursor（MDC 格式）
gemini	.gemini/instructions.md	Gemini CLI

设置 AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project 后，每次保存规则时，服务都会自动重新生成这四个文件。

2. check_action · 协议强制执行点

# Agent proposes an action · server matches against rule store
agent-memory check-action "delete the memory called old-project-notes" --type deletions

# → On approval: returns a Compliance Receipt the agent passes back to destructive tools
# → On deny: returns structured hard_violations + soft_warnings

MCP 结构：

{
  "name": "check_action",
  "arguments": {
    "action": "delete the memory called old-project-notes",
    "action_type": "deletions",
    "session_id": "sess_abc",
  },
}

第 1 层（确定性检查，适用于每个客户端）：根据 rule.matches 正则表达式匹配操作，并通过 rule.enforce_on 进行筛选。硬性违规会阻止操作。软性违规会发出警告。获准的操作会获得一张新的回执，有效期为 60s。

第 2 层（通过 Sampling 增强，随 v0.11.7 发布）：对于带有 applies_when 自然语言条件的规则，服务会使用 MCP Sampling 询问客户端的大模型，判断拟执行的操作是否触发该规则。只有客户端未声明支持 Sampling 时，才会退回到第 1 层。此功能适用于 Claude Desktop 和 VS Code Copilot；在 Claude Code、Cursor、Cline 和 Codex CLI 上，你只能使用第 1 层——这足以强制执行你编写的规则。

但 check_action 只会限制_此服务自身_的工具。要在 Agent 的实际操作上强制执行规则——包括它运行的 shell 命令和文件写入——agent-memory install-hooks 会将 PreToolUse hook 接入 Claude Code：硬性规则会拒绝匹配的工具调用，软性规则会询问你。这样，rm -rf 或向 main 强制推送就会被真正_阻止_，而不只是收到提醒。请先运行 agent-memory init，以获取一套入门规则集。

3. 合规回执 · 加密原语

回执是带有附加限制（Macaroon 模式 · Birgisson 等人，NDSS 2014）的短时效签名持有者令牌。全新的协议原语：由服务端签发的令牌，绑定操作、会话、规则版本哈希和过期时间。篡改会导致签名失效。规则变更会使所有未过期的回执失效（因为 rules_version 是签名载荷的一部分）。

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 · 规则存储区的运行状况

agent-memory audit          # pretty colored terminal output
agent-memory audit --json   # structured JSON for tooling

展示内容：

• 按严重程度统计规则数（硬性 / 软性 / 未指定）
• 过期规则 · last_verified 超过 90 天，或从未验证
• 模式冲突 · 两条规则的 enforce_on 相同，且 matches 中的正则表达式相同
• 近期拒绝 · 阻止某项操作的 check_action 调用（用于发现过于激进的规则）
• 未提供回执的破坏性操作 · 在 v0.12+ 中应为空；非空表示客户端调用 delete_memory 时未先通过 check_action

仅当没有过期规则、冲突或未提供回执的操作时，healthy 标记才为 true。

5. CRP 1.0 / 1.1 作为可移植规范

回执协议以独立文档形式发布于 docs/compliance-receipt-protocol-1.0.md。其他 MCP 服务可以采用相同格式和验证规则以实现互操作 · agent-memory-mcp 是参考实现。规范涵盖：回执结构、规范编码、签名（1.0 使用 HMAC-SHA256，1.1 使用 Ed25519）、验证顺序、规则版本哈希、保留的附加限制类型、MCP 集成模式、安全注意事项、跨服务采用方式以及测试向量。

---

你将获得什么

.agent-memory/
├── MEMORY.md                           # auto-managed index
├── user-prefers-tabs.md
├── feedback-no-emoji-in-code.md
├── project-q3-launch-frozen.md
└── reference-postgres-runbook.md

记忆文件就是带有 YAML 前置内容的 Markdown：

---
name: feedback-no-emoji-in-code
description: User wants zero emoji in commits, comments, or output
type: feedback
---

Hard rule. No emoji anywhere user-facing.

**Why:** prior contractor flooded the repo with them; user spent a
weekend removing them.

**How to apply:** scrub before commit; reject any tool output that
adds them automatically.

格式就这么简单。没有魔法。读取、编辑、发布即可。

---

为什么要做这个项目

大多数 MCP 客户端没有持久化记忆。有持久化记忆的客户端（Claude Code）也会将其存储在只有该客户端能访问的位置。官方的 server-memory 和所有社区替代方案都使用不透明的结构化后端。这对某些工作流来说没问题——但这样一来，你的数据就被藏在一层无法用 cat 读取的封装后面。

我们选择 Markdown，因为：

• 通用。 每位开发者都能读懂 Markdown。每款编辑器都支持它。每种差异比较工具都能理解它。
• 可移植。 记忆可以随项目迁移（默认按项目存储），也可以随你迁移（全局模式）。移动、复制、分叉都可以——它们只是文件。
• 可检查。 打开一个文件夹，就能审查 AI 助手“知道”的内容。
• 可修复。 记忆有误时，像修改任何文本文件一样修复即可。不需要 SDK、API 或 SQL。
• 可版本控制。 Git 能理解每一项变更。没有 JSON 合并冲突，也没有二进制文件块。

如果你需要向量相似度搜索、语义回忆或自动关系提取，请使用数据库支持的记忆 MCP。它们很擅长这些。如果你需要在断电后仍然可以读取的记忆，这就是为你准备的。

---

安装

从 npm 安装（推荐）

npx -y @xultrax-web/agent-memory-mcp

已列入 MCP Registry

io.github.xultrax-web/agent-memory-mcp · 在 https://registry.modelcontextprotocol.io 浏览

本地构建

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）：

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "@xultrax-web/agent-memory-mcp"]
    }
  }
}

Cline（VS Code 扩展）

Cline → MCP Servers → Add：

{
  "agent-memory": {
    "command": "npx",
    "args": ["-y", "@xultrax-web/agent-memory-mcp"]
  }
}

VS Code（Copilot Chat）

VS Code 有两种配置路径。 上面的 Cline 部分专用于 Cline 扩展（使用其自带的 MCP 服务界面）。本部分适用于 VS Code 原生 MCP 支持——GitHub Copilot Chat 会直接读取该配置。根据你使用的助手任选其一；两种配置可以共存。

.vscode/mcp.json（工作区），或通过“用户设置”→“编辑 mcp.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）：

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "@xultrax-web/agent-memory-mcp"]
    }
  }
}

Windows 说明： 如果 npx 无法正常解析，请使用 cmd /c 封装：

{ "command": "cmd", "args": ["/c", "npx", "-y", "@xultrax-web/agent-memory-mcp"] }

Continue.dev

~/.continue/config.json：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@xultrax-web/agent-memory-mcp"]
        }
      }
    ]
  }
}

存储范围

按项目（默认）：记忆存储在相对于客户端启动服务所在位置的 ./.agent-memory/ 中。通常该位置是项目根目录。

个人／全局存储池：

"env": { "AGENT_MEMORY_SCOPE": "global" }

全局记忆存储在 ~/.agent-memory/。

自定义路径：

"env": { "AGENT_MEMORY_DIR": "/abs/path/to/memory" }

---

工具

工具	用途
save_memory	创建或更新记忆。原子写入并加锁。验证名称和类型。更新索引。
search_memories	模糊搜索（Fuse.js · 容错拼写错误、容忍词序变化、支持部分匹配）。返回相关度为 0-100 的前 N 条结果及正文片段。
relevant_memories	匹配方式与搜索相同，但以一份 Markdown 文档的形式返回完整记忆正文。专为大模型自动上下文设计。
get_memory	按名称获取一条记忆。返回 frontmatter 和正文。
list_memories	列出记忆。可选 type 筛选条件。支持分页（默认每页 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	通过组合出站链接、入站反向链接、共享标签、类型匹配和内容相似度，找出与某条记忆相关的记忆。通过关联关系浏览记忆图谱。
sync_status	报告 Git 同步状态：远程 URL、分支、未提交的本地文件，以及领先于／落后于 origin 的提交数。
sync_push	提交本地记忆更改并推送到配置的 Git 远程仓库。如果未提供提交消息，则自动添加时间戳。
sync_pull	从 Git 远程仓库执行快进拉取。如果本地更改尚未提交，则拒绝拉取。
save_rule	v0.11+。 创建或更新 rule 记忆，包含 severity / scope / matches / enforce_on / applies_when / last_verified。如果已配置，则自动生成配套文件。
list_rules	v0.11+。 仅列出规则记忆，可选按严重级别或 enforce_on 类别筛选。
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、禁止销毁生产数据、禁止 curl|sh、标记机密信息），并将其导出到每个工具。force=true 将覆盖现有内容。
validate_receipt	v0.15+。 使用另一台服务的公钥验证其 CRP 1.1（Ed25519）回执 · 联邦机制基础。传入 receipt + public_key（内联 PEM 或文件路径）。

提示词

服务会公开 4 个内置 MCP 提示词，客户端（Claude Desktop、Cursor 等）会将其显示为斜杠命令。这些提示词让记忆成为主动的工作流层，而不只是被动存储：

提示词	参数	功能
extract_memories	无	大模型扫描当前对话，提出候选记忆，并为每条记忆调用 save_memory（选择类型和描述）。
summarize_topic	topic	大模型通过 relevant_memories 提取与主题相关的记忆，并将其综合成一份带引用的摘要。
prepare_handoff	project（可选）	大模型遍历符合筛选条件的项目类型记忆，并整理出一份结构化的交接文档（当前状态、待处理事项、注意事项）。
audit_stale	无	大模型评估项目和参考记忆是否过时，并生成一份分类清单（可能已过时／值得核实／仍然有效）。

记忆类型

内置 5 种类型。前 4 种遵循 Claude Code 的惯例；rule 是 v0.11 新增的：

• user — 关于个人的信息（角色、偏好、专业水平）
• feedback — 为助手提供的软性指导（偏好这种风格、倾向于那种做法）
• project — 代码中没有的当前状态上下文（截止日期、进行中的工作）
• reference — 外部系统的链接（Linear 看板 URL、监控仪表板）
• rule — 要强制执行的约束，而不只是需要回忆的事实。包含 severity、scope、matches、enforce_on、applies_when、last_verified。会同步到配套文件；是 check_action 的门控条件。

标签 + Wiki 链接

除了类型之外，还有两项跨领域的组织功能：

标签 — frontmatter 中可选的 tags: [a, b, c] 数组。可通过 list_memories({tags: [...]}) 和 agent-memory list --tags "a,b" CLI 命令查询。筛选采用交集逻辑——记忆必须包含所有列出的标签。标签名称只能包含小写字母 a-z、数字、连字符或下划线，最多 40 个字符。

---
name: deploy-process
description: Blue-green prod deployment
type: project
tags: [deployment, production, critical]
---

Wiki 链接 — 在记忆正文任意位置写入 [[memory-name]]，即可创建链接。find_backlinks 会返回引用指定记忆的其他记忆；find_related 会对完整图谱进行排序（外链、入链反向链接、共享标签、内容相似度），用于探索导航。

---

CLI

同一个二进制文件也可用作命令行工具。它适用于 Shell 脚本、Git 钩子、cron，或在编辑器之外快速查找内容。

agent-memory save user-likes-tabs --type user --description "Prefers tabs" --content "Always use tabs in new files."
agent-memory list
agent-memory list --type feedback
agent-memory search "tabs"                    # fuzzy, top 10 by relevance
agent-memory search "depoy" --limit 5         # typo-tolerant ("depoy" → "deploy")
agent-memory relevant "deployment" --max 3    # full memory bodies, LLM-ready
agent-memory get user-likes-tabs
agent-memory list --limit 20 --offset 40      # pagination
agent-memory delete user-likes-tabs           # soft delete — moves to .trash/
agent-memory restore user-likes-tabs          # restore the most recent trash entry
agent-memory doctor                            # check integrity
agent-memory doctor --rebuild-index            # repair MEMORY.md from disk
agent-memory stats                             # dashboard: counts, sizes, audit/trash
agent-memory log                               # last 20 entries from the audit log
agent-memory log --tail 50 --action delete     # filter by action, tail size
agent-memory verify deploy-process             # extract URLs/dates/file refs + staleness heuristics
agent-memory save my-mem --type project --description "X" --content "Body" --tags "production,critical"
agent-memory list --tags "production"          # filter by tag (intersection)
agent-memory backlinks deploy-process          # memories that link to deploy-process
agent-memory related deploy-process            # ranked discovery: links + tags + similarity
agent-memory sync init [email protected]:you/agent-memory.git    # multi-machine setup (one-time)
agent-memory sync push                         # commit + push local changes
agent-memory sync pull                         # fast-forward from remote
agent-memory sync status                       # local + ahead/behind state
agent-memory ui                                # launch the TUI (browse + edit interactively)

# v0.11+ · rules and enforcement
agent-memory save-rule no-emoji --severity hard --enforce-on commits,chat_responses \
  --matches "emoji|:[a-z_]+:" --content "No emojis. Anywhere. Ever."
agent-memory list-rules                        # rule memories only
agent-memory list-rules --severity hard        # filter by severity
agent-memory emit-companions                   # write AGENTS.md + CLAUDE.md + .cursor/rules + .gemini
agent-memory emit-companions --target agents,claude   # filter targets
agent-memory check-action "delete old notes" --type deletions   # returns approval + receipt JSON
agent-memory audit                             # pretty operational health report
agent-memory audit --json                      # structured JSON for tooling

多设备记忆（Git 同步）

文件式记忆的一大优势：每台开发设备都有 Git，而且 Markdown 合并顺畅。agent-memory sync 会将 .agent-memory/ 转换为指向某个（私有）远程仓库的 Git 仓库，让你的记忆在桌面电脑、笔记本电脑和服务器之间随身同步。

# One-time setup
agent-memory sync init [email protected]:you/agent-memory.git

# End of the day on desktop
agent-memory sync push

# Pick up your laptop before bed
agent-memory sync pull

# Save a new memory while reading in bed
agent-memory save bedtime-thought --type project --description "..." --content "..."
agent-memory sync push

# Next morning at desktop
agent-memory sync pull          # picks up the bedtime memory

不会同步的内容（每台设备各自的状态，保留在本地）：

• .lock — 进程级文件锁
• .events.jsonl — 每台设备各自的审计记录
• .trash/ — 软删除暂存区

会同步的内容：所有记忆文件、MEMORY.md 索引，以及你添加的任何 .gitignore。

默认情况下，提交使用身份 agent-memory <agent-memory@local>；如果你想按设备区分提交者，请在环境中设置 GIT_AUTHOR_EMAIL / GIT_COMMITTER_EMAIL。

审计日志 + 结构化日志

每次变更都会向 .agent-memory/.events.jsonl 追加一行 JSON：

{"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：

agent-memory save my-handoff --type project --description "Q3 handoff notes" --content-file handoff.md
cat conversation.txt | agent-memory save extracted-prefs --type user --description "Pulled from chat" --stdin

从 Claude Code 导入

如果你一直在使用 Claude Code 内置的记忆功能，可以将其迁移过来：

# See what would be imported (dry run, no writes)
agent-memory import-claude-code --dry-run

# Filter to one project by substring match (case-insensitive)
agent-memory import-claude-code --project prefixcheck --dry-run

# Do the import
agent-memory import-claude-code --project prefixcheck

# Replace existing memories with the same names
agent-memory import-claude-code --project prefixcheck --overwrite

导入器会遍历 ~/.claude/projects/*/memory/，解析每条记忆的 YAML frontmatter（采用宽容模式，格式错误的文件不会导致运行中断），将 Claude Code 的 metadata.type 字段展平为顶层 type，并写入当前存储。除非传入 --overwrite，否则会跳过同名的现有记忆。

---

为什么使用文件，而不是数据库

你放弃了原生语义相似度搜索和结构化实体关系查询，换来的是一个能够经受每次工具更换、每次机器迁移，以及每次“等等，六个月前那个 AI 是怎么跟我说这个代码库的来着？”的记忆存储——即使断电后，你仍然可以读取它。

这种取舍确实存在。对于需要向量召回或图查询的工作流，基于数据库的记忆才是合适的工具。对于希望能够 grep、编辑、版本控制并手动审计记忆的工作流，这就是合适的选择。

---

以运维人员需求为核心的设计

这个服务旨在供人日常使用，而不是只在演示时表现出色。

v0.3 中已发布：

• 原子写入 — 使用临时文件 + 重命名模式。断电不会留下只写了一半的文件。
• 文件锁定 — 每次变更都使用 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 stdio 配合使用。
• 彩色输出 — 自动检测 TTY，并遵循 NO_COLOR / FORCE_COLOR 设置。

v0.5 中已发布：

• 使用字段权重（name×3、description×2、body×1）的 Fuse.js 模糊搜索。支持错别字、不完整词和词序变动。
• 片段高亮 — 每个匹配结果下方都会显示正文上下文摘录，并用 ... 标记。
• 相关性评分 — 将 Fuse 评分反转并缩放至 0-100，便于人类阅读。
• relevant_memories(query, max=5) — 与搜索工具配套的工具，以单个 markdown 文档的形式返回完整记忆正文，专为大模型自动加载上下文而构建。
• 分页 — list_memories 支持 offset + limit，search_memories 支持 limit。

v0.6 中已发布：

• Vitest 测试套件 — 25+ 个黑盒测试，覆盖 CLI + MCP 服务的执行路径。
• GitHub Actions CI — 每次推送/PR 都会在 Node 20/22/24 上运行测试。
• COMPATIBILITY.md — 已知可用的客户端矩阵 + 特殊情况。

v0.7 中已发布 · 主动上下文层：

• MCP 提示词功能 — 内置 4 种工作流（extract_memories、summarize_topic、prepare_handoff、audit_stale），客户端会将其显示为斜杠命令。
• verify_memory 工具 — 对记忆中的 URL、日期和文件引用进行静态分析，并根据类型采用相应的过时判定启发式规则。另提供匹配的 agent-memory verify <name> CLI。
• 保存时检测冲突 — 将新记忆与已有记忆进行模糊匹配；发现近似重复项时发出警告，但不会阻止保存（让大模型决定是合并、重命名还是继续操作）。

v0.8 中发布 · 面向大规模组织：

• 标签 — 可在 frontmatter 中添加可选的 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 — 查看本地状态以及领先或落后于 origin 的提交数。
• agent-memory sync log — 查看跨机器记忆更改的历史记录。
• sync_status / sync_push / sync_pull MCP 工具 — 大模型也可以执行这些操作。
• 每台机器独有的状态（.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 等）中打开高亮显示的记忆 — 保存后写回磁盘
• 按 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）— 采用 HMAC-SHA256 的 Bearer Token，并支持 Macaroon 风格的限制条件；凭证绑定到 rules_version，规则更改会使未过期的令牌失效
• check_action MCP 工具（第 1 层为确定性检查；从 v0.11.7 起，对于声明具备该功能的客户端，第 2 层会通过 Sampling 增强）
• audit 命令 — 检查过时规则、模式冲突、近期拒绝记录以及没有凭证的破坏性操作
• CRP 1.0 协议规范 — 可移植且不受供应商限制

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 Code 导入（agent-memory import-claude-code）、命令行模式、Prettier 基线
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	Trusted Publishing 已上线 · 通过无令牌 OIDC 在 git 标签触发时发布到 npm + MCP Registry
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	Compliance Receipts 基元 · 带有 Macaroon 风格 caveat 的 HMAC-SHA256 令牌
v0.11.3	check_action MCP 工具（Tier 1 确定性）+ 由凭证门控的 delete_memory（可选）
v0.11.4	audit 命令 · 过时规则、模式冲突、近期拒绝、无凭证操作
v0.11.5	CRP 1.0 协议规范 — 可移植、供应商中立的执行基元
v0.11.6	重新定位 · “将你的工作方式编码下来，让每个 AI 工具都遵守”
v0.11.7	Tier-2 Sampling 增强的 check_action · 在能力完备的客户端上由大模型判定 applies_when
v0.12	delete_memory 必须提供凭证 · 破坏性变更 · 让楔子真正有了锋芒
v0.13	CRP 1.1 · Ed25519 非对称签名，支持跨服务联邦

接下来

• 由凭证门控的 restore_memory 和 doctor --rebuild-index（使用相同的 check_action 流程）
• 联邦示例 · 第二个用于签发 + 验证 CRP 1.1 凭证的参考 MCP 服务
• 自动加载上下文 — 服务钩子，在每轮大模型对话前自动调用 relevant_memories
• 在存储中支持文件夹（.agent-memory/work/、.agent-memory/personal/）
• 记忆包 — 导出/导入可分享的 .tar.gz 精选记忆包
• 浏览器配套 UI（agent-memory web）
• TUI 优化 — 通过文件监视自动刷新、内联编辑、将同步操作设为快捷键

更长远的计划

可选的本地嵌入侧车（transformers.js，无需 API）、支持差异比较/合并的团队模式、浏览器扩展，可将 chatgpt.com / claude.ai 中的对话保存为记忆，以及移动端配套应用。

如果你希望我提前实现其中任何一项，请提交 issue。

---

许可证

MIT。随意使用。

---

作者

@xultrax-web · 为解决我一直遇到的跨客户端记忆问题而构建。属于 PrefixCheck Labs 的一部分。

灵感来自 Anthropic 的 Claude Code 中基于文件的记忆系统。