MemAuthority

MemAuthority——面向 AI Agent 的 Git 支持长期记忆系统

中文

MemAuthority 是一个通过 MCP（Model Context Protocol）提供的、由 Git 支持的 AI Agent 长期记忆系统。它能让新会话、另一台机器或另一个 Agent 找回项目积累的上下文并继续工作，而不必重新摸索相同的决策和陷阱。

它不会试图记录每一个细节，而是专注于提炼：

未来的 Agent 不应再从头摸索的经验教训和结论。

明确的职责划分：

• 你 充当把关者：决定哪些内容真正值得长期保留；
• Agent 负责执行：理解、检索、总结、更新和清理记忆；
• MemAuthority 提供安全保障：确保长期记忆可靠，并能按需获取，同时防止过时写入、重复重试和更新中断。

Agent 仍然负责判断内容的含义以及是否应该更改。MemAuthority 则确保保留下来的记忆能够长期保持可靠。

---

适用对象

MemAuthority 专为重视长期记忆质量的用户设计。

你可能曾在使用各种记忆工具时感到缺乏掌控：

• 不清楚某项内容被记住的原因；
• 不确定它何时会被调用；
• 无法确认信息是否已经过时；
• 没有简便的方法进行精确编辑或删除。

或者，你可能尝试维护过记忆库，却眼看它随着时间推移变得臃肿杂乱——最终非但没有帮助 Agent，反而令它困惑。

如果你：

希望用最少的精力把关记忆质量，同时将所有日常整理工作交给 Agent。

那么 MemAuthority 很适合你。

“投入精力”并不意味着整天手动编辑文件，而是在关键时刻做出影响重大的决定：

• 这些信息值得长期保留吗？
• 什么时候应该检查或清理记忆？
• 其中是否包含敏感数据或机密信息？
• Agent 提出的整理方案是否符合你的实际意图？

所有繁重的机械性工作——格式整理、分类、归档和定向检索——都完全由 Agent 负责。

---

为什么不直接使用 MEMORY.md？

如果项目的记忆内容很少、很少变化，或者你只是不想花精力维护记忆，那么继续使用普通的 MEMORY.md 是最简单的选择。

当这个文件不再只是一份笔记，而是变成未来会话需要信赖的长期项目状态时，MemAuthority 就开始发挥作用了。

它解决的是更高阶的需求：

将长期记忆维护变成可靠、可控且经过工程化设计的工作流。

它提供的远不只是“让 Agent 编辑 Markdown”，而是一套稳健的运行架构：

• 按需精准加载：仅在任务确实需要时加载记忆，避免无关内容使上下文窗口膨胀或受到干扰；
• 职责清晰分离：明确区分交接状态、长期规则、里程碑进度和避坑事项；
• 并发与版本安全：写入前执行严格的版本检查（CAS — 比较并交换），防止旧版本在不知情的情况下覆盖新内容；
• 幂等与去重：即使因网络故障或运行中止而重试，也不会产生重复记忆；
• 收敛与完整历史：保持当前工作记忆精简紧凑，同时依靠 Git 保存完整、可审计的修订历史；
• 事务与崩溃恢复：提供明确的日志记录和恢复机制，以应对写入中断或失败。

一种有用的理解方式是：

Authority 存储未来的 Agent 现在应该继承的状态；Git 存储完整历史。

简而言之：

MEMORY.md 优先考虑简单性；MemAuthority 则优先确保项目发展壮大后，长期记忆依然可靠。

---

日常工作流

你可以用自然、简洁的指令与 Agent 交互：

1. 在任务开始时按需检索

Agent 会根据实际任务情况判断是否调用记忆，方式类似于使用 MEMORY.md；你也可以指示 Agent 读取特定记忆：

“检查此项目的 MemAuthority——只提取你需要的内容。”

MemAuthority 不强制使用固定的检索方式，因此 Agent 会选择最短、最合适的检索路径：已知位置时直接读取，未知时进行搜索；需要快速了解项目整体交接情况时使用 handoff。如果当前对话已经包含足够的上下文，就完全不必调用 MemAuthority。

2. 筛选值得记住的内容

“列出这项任务中值得长期保留的要点——我来决定保存什么。”

Agent 会提炼候选内容，由你最终决定保留、编辑还是舍弃。

3. 快速、轻松地记录

“记录这项任务。”

这是常见且省力的指令。默认情况下，Agent 会采取保守策略，将其记录为低风险的 progress 条目，而不会自行更改长期 rules。

4. 任务后的维护

“检查这项任务中实际用到的 MemAuthority 记忆。根据刚刚发生或已验证的情况更新，并删除过时内容。”

刚完成任务的 Agent 掌握着最新的代码、工具结果、运行时事实和用户决定。它只需维护自己实际读取并使用过的记忆，无须每次都扫描整个 Vault。

5. 暂存想法以备日后处理，释放上下文空间

“这个方向值得以后探索——把它放到 MemAuthority TODO 里，别让它占用我们当前的上下文。”

这里的 TODO 不是项目管理问题跟踪工具，而是：

一个暂存区，用于存放值得日后重新审视的想法，而不占用今天的认知带宽。

采取行动后，应删除 TODO 条目，并将由此得出的任何持久结论纳入长期记忆。

---

“记录此任务”——如何避免记忆膨胀？

MemAuthority 不要求你每次想记录内容时，都要斟酌“应该放进规则还是进度”。

当你给出“记录此任务”这类开放式指令时，Agent 的默认行为是：

• 默认记录到 progress；
• 仅记录本次会话中已完成的核心交付成果；
• 仅记录有意义的状态变更；
• 仅记录后续继续工作所需的关键信息。

默认应主动过滤的内容：

• 完整聊天记录、对话填充内容和客套话；
• 细致到逐项操作的行动日志和反复试错的细节；
• 没有未来复用价值的短暂失败；
• 知识库中已有记录的重复事实；
• 临时、过时、敏感或纯属推测的内容。

与此同时，Agent 不会仅仅因为某条内容“听起来很重要”，就将其提升为长期 rules 条目。真正可靠的规则、交接状态和经验教训，应通过实际工作逐步提炼。

MemAuthority 提供的系统级防护措施：

• 对所有写入内容强制使用标准架构；
• 根据记忆角色限制修改操作（基于角色的访问控制）；
• 自动扫描并拦截高置信度的机密信息和凭据；
• 使用幂等机制，防止重试不断堆积重复条目；
• 使用版本校验（CAS），避免过期版本静默覆盖更新版本；
• 在提交写入前验证候选知识库的完整性；
• 支持带日志记录且可在崩溃后恢复的事务。

目标不是“绝不产生一条低质量记录”，而是：

Agent 谨慎记录，MemAuthority 保证底层状态完整性，持续进行的实际工作不断完善并精简记忆。

一致性分为两个不同层面：

• 语义一致性：由 Agent 维护，将新任务成果与现有知识协调起来；
• 状态一致性：由 MemAuthority 强制保障，并由 Git Authority、修订版本 CAS、幂等机制和事务日志提供支持。

请记住：progress 是一种低门槛的里程碑记录入口，不是不可变的只追加档案。

---

如果我已经有 MEMORY.md 或旧版笔记，该怎么办？

无需手动重写所有内容。

对于旧版内容迁移，MemAuthority 采用了一种有原则的方法：

让 Agent 执行语义迁移，而不是为每种旧版格式都构建自定义导入器，将其导入 MemAuthority。

只要 Agent 能够读取并理解你的旧版资料，就可以从任何来源迁移：

• 现有的 MEMORY.md 文件；
• 通用 Markdown 或纯文本文档；
• JSON 导出文件；
• 系统提示词文件；
• 历史交接记录和聊天摘要；
• 存在冲突的多来源笔记；
• 大模型能够解析的任何其他文本格式。

标准迁移流程：

1. Agent 学习 MemAuthority 的结构规范和记忆标准；
2. Agent 阅读旧版笔记；
3. 对信息进行去重、合并、更新和分类；
4. 删除过时事实、冗余条目、原始日志、临时笔记和不适合的内容；
5. 将整理后的内容导出到标准的 MemAuthority 知识库结构中。

你只需这样指示 Agent：

“先阅读 MemAuthority 的记忆规范，再检查这个旧版记忆文件。对值得长期保留的内容进行去重、合并、更新和重构。删除过时、重复的内容、原始日志、临时笔记，以及不适合长期存储的内容。先提出迁移草案供我审核，再进行写入。”

迁移本质上是一项内容筛选决策，而不是机械的复制粘贴。

对于初始接入或大规模迁移，建议使用 v1 工作流：

init (initialize empty vault)
  -> Agent curates vault in detached mode
  -> validate (verify integrity & schema)
  -> Human review
  -> Git commit (commit revision)
  -> managed serve (launch MCP service)

完整指南请参阅 docs/ONBOARDING.md。

---

MemAuthority 中应该包含什么？

MemAuthority 中的长期记忆严格划分为四种角色：

handoff（交接状态）

Agent 立即接手项目所需的最精简关键上下文。 保持简洁、可执行并持续更新。切勿让它膨胀成第二份 README。

rules（长期规则）

未来 Agent 必须遵循的架构约束、既定决策和行为准则。 只记录已确定的决策，不记录冗长的辩论或历史讨论。

progress（里程碑进展）

与未来工作仍有关联的关键里程碑和状态转变。 这是记录信息时阻力最低的入口，但它不是只增不减的事务日志。

pitfalls（陷阱与经验）

未来 Agent 可能遇到的反复出现的失败模式、不易察觉的陷阱和经过验证的解决方法。 常见错误和偶发的拼写错误不应记录在这里。

一个可靠的判断方法：

了解这件事会改变未来 Agent 的决策、节省大量反复试错，或避免重复犯错吗？

如果不会，它可能就不该进入长期记忆。

---

如何避免不必要的 MemAuthority 记忆进入对话上下文？

MemAuthority 支持渐进式回忆，但不要求 Agent 遵循固定流程：

1. 如果当前对话已有足够的上下文，就完全不要调用 MemAuthority；
2. 如果不清楚是哪个项目，先定位并确认项目；
3. 如果已知确切的 URI 或章节，直接读取；
4. 如果知道项目但不清楚位置，就在该项目内搜索；
5. 如果需要快速了解整体交接情况，通常从 handoff 开始最合适；
6. Agent 自行判断哪些内容相关，并只读取真正有助于当前任务的内容。

搜索结果是坐标，不是上下文。

目标很简单：不要让无关记忆进入当前对话上下文，并由执行任务的 Agent 自行判断需要多少证据才足够。

---

多个 Agent 会造成冲突吗？

MemAuthority v1 围绕一项核心原则构建：

多 Agent，单一权威来源。

不同 Agent 或客户端可以轮流读取同一个 Managed Authority 并请求更改，而 MemAuthority 会维护一份单一、线性且确定的版本历史。v1 仍是为单个用户和单个写入者设计的，并非用于团队同时编辑的协作数据库。

如果 Agent A 更新了记忆，而 Agent B 尝试基于过期版本进行修改，MemAuthority 会明确返回冲突并拒绝写入，而不会让过期状态覆盖最新状态。

此时，Agent B 必须重新获取最新状态，并决定是合并、覆盖、中止，还是询问用户。

MemAuthority 不会判断哪种主观看法才正确。它的职责更有限：

明确指出并发冲突，避免不同的编辑悄无声息地让 Authority 变得不正确。

---

如何避免 MemAuthority 日益臃肿

Git 会忠实记录 Authority 的完整演变过程，方便随时追溯记忆；但 Agent 在实际工作中不会读取 Git 历史，只会读取当前生效的记忆。当前记忆可以自由修改，而 Git 会确保其可恢复：

• 规则变化时，直接就地更新规则；
• 状态演变时，更新交接状态；
• 内容过时且不再需要回忆时，直接删除。

---

安装

MemAuthority 需要 Git 和 Go 1.26.5 或更高版本。使用以下命令安装当前稳定版：

go install github.com/iasi777/v-memory/cmd/[email protected]

为保持兼容性，v1.x Go 模块的标识有意保留为 github.com/iasi777/v-memory，尽管规范仓库和产品名称现为 MemAuthority。GitHub 会将原仓库 URL 重定向至 iasi777/memauthority。

验证：

memauthority version

预期输出：

memauthority 1.3.2

现有自动化流程可以继续安装并调用兼容可执行文件：

go install github.com/iasi777/v-memory/cmd/[email protected]
v-memory version

目前尚未发布预构建的版本二进制文件。若要从源代码检出版本构建：

go build -trimpath -o ./memauthority ./cmd/memauthority
./memauthority version

发布 CI 会在 Linux、macOS 和 Windows 上运行测试套件、vet 和原生 CLI 构建；Linux CI 还会验证生产环境的 Linux/ARM64 目标。

---

入门

1. 初始化空保险库

memauthority init ./vault

2. 入门配置与整理

引导新保险库或迁移大型旧语料库时，让拥有文件和 Git 权限的 Agent 阅读： docs/AGENT-GUIDE.md

整理完成后，验证保险库：

memauthority validate ./vault

3. 提交并启动服务

检查更改，将其提交到 Git，然后启动托管 MCP 服务：

memauthority serve \
  --vault /absolute/path/to/vault \
  --state-dir /absolute/path/to/state \
  --write-enabled

• 省略 --write-enabled 时，服务将以只读模式运行；
• state-dir 必须位于 Vault Authority 目录之外；
• 不要同时混用分离模式（直接编辑文件）和托管模式（运行服务）；
• 当保险库没有已注册的运行时，可选的声明式运行时元数据默认关闭。大多数单机用户应保持关闭。已有 runtime_resource 的保险库会自动启用运行时工具；仅当你有意开始记录工作／部署拓扑时，才使用 --runtime-enabled。

对于本地设置，最简单的方法是让 MCP 客户端通过 stdio 直接启动该命令。

连接后，MemAuthority 会自动向 Agent 提供工具定义、输入架构、注释和资源元数据。在日常托管运行期间，无需向 Agent 重新解释参数架构。

有关跨领域使用指南（按需回忆、审慎记录、角色选择和旧版迁移），请参阅 AGENT-GUIDE.md。

若通过 HTTP 传输公开服务，请务必先查看 SECURITY.md 和已冻结的 v1.3.2 传输／身份验证规范。

构建与验证

go test ./...
go vet ./...
go mod verify
go build -trimpath -o ./memauthority ./cmd/memauthority

---

基准测试

MemAuthority 维护着一套公开、可审计的基准测试套件，用于验证真实 Agent 工作负载下的跨会话记忆可靠性。

最新测试活动：变更可用性回归（2026-09-08）

handoff-pending-01 — 跨会话项目交接与待办工作跟踪

指标	结果
总运行次数	30/30 PASS
总会话数	90/90 PASS
变更操作	共 426 次
变更错误	2 次（0.5%）
人工语义审查	30/30 已确认
独立审计	Claude Opus 5，置信度 HIGH

测试的 Agent 技术栈（每种 10 轮）：

• Codex CLI + GPT-5.6 Sol：10/10 次运行，0/136 次变更错误（0.0%）
• Codex CLI + GPT-5.6 Luna：10/10 次运行，0/138 次变更错误（0.0%）
• Pi Agent + Gemini 3.8 Flash：10/10 次运行，2/152 次变更错误（1.3%，均已恢复）

关键发现：所有受测 Agent 技术栈都成功在完全独立的会话间保留并恢复了项目状态。修正后的变更错误率为 0.5%（2/426），表明 API 易用性很高。

审计说明：原报告称有 18/426 次错误。经全面分析 MCP 日志后，修正为 2/426 次。两次错误均发生在同一次运行中，涉及同一工具和同一验证问题。Agent 成功恢复。方法说明请参阅审计文档。

📊 完整结果：benchmark/results/mutation-usability-regression/
📋 基准测试规范：benchmark/ | 完整文档
📦 下载证据：GitHub Releases（30 次完整运行，含全部产物）

---

公共契约

当前公开兼容性基线为 v1.3.2。此前发布的契约快照保持不变。

Vault 存储格式、MCP 工具、Managed 运行时行为、变更/拒绝规则、安全边界、传输/身份验证行为及兼容性政策的权威定义，均维护在 docs/contract/v1.3.2/ 下。

本 README 和用户指南仅作说明；若细节不一致，以版本化契约为准。

版本

memauthority version
memauthority --version

AI Agent Memory、Long-Term Memory、MCP Memory Server、Git-backed Memory、Agent Memory Infrastructure、Agent Continuity

对于 v1.3.2，主命令会打印 memauthority 1.3.2；兼容性命令会打印 v-memory 1.3.2。

安全

通过 HTTP 传输公开服务前，请务必阅读 SECURITY.md。

• 默认禁用写入权限；请使用 --write-enabled 显式启用；
• HTTP 变更必须严格遵守冻结版 v1 规范中的 OAuth 和安全要求；
• MemAuthority 内置高置信度机密扫描功能，但不能替代全面的机密检测工具。

相关文档

• docs/ONBOARDING.md — 快速入门、旧版迁移和初次设置指南
• docs/MCP-CONFIG.md — stdio / HTTP 连接指南和配置规范
• docs/AGENT-GUIDE.md — 关于回忆、记录、维护和迁移的 Agent 实用规则
• docs/FAQ.md — 常见问题、设计边界和权衡
• examples/README.md — 可运行的 Vault 示例和首次本地 MCP 会话
• SECURITY.md — 支持的安全范围、部署边界和私密报告渠道
• docs/contract/v1.3.2/ — 版本化 v1.3.2 公共契约

社区

MemAuthority 感谢并支持 LINUX DO 社区。

许可证

根据 Apache License 2.0 发布。详情请参阅 LICENSE。

归属和第三方声明记录在 NOTICE 和 THIRD_PARTY_NOTICES.md 中。