记忆修正：用版本化更新替代重复写入

「再存一条」的问题

只会 memory_save_atom 的 Agent 在检索到略有过时的 Atom 时，往往再写一条「修正版」：结账日改了、根因被新修复取代、决策被推翻。搜索随后返回两条矛盾记录，模型只能猜哪条才是当前真相。

修正（correct）保留同一个 atom id，原地更新正文，并把旧修订归档。检索始终指向一条 canonical 记录，而不是一堆近似重复。

version 字段与乐观并发

每条 Atom 带有单调递增的 version（从 1 起），写在 YAML frontmatter 与 archive metadata.json 中。存量无 version 字段的 Atom 视为 version 1。

修正时传入 search / list_atoms 返回的 expectedVersion。若他人已先递增版本，API 返回 409 version_conflict 及 actualVersion —— 重新拉取后再试。省略 expectedVersion 则接受后写覆盖。

REST：PATCH 修正

鉴权写入使用 PATCH /api/v1/memory/atoms/{atomId}，query 须带 memoryLibraryId。JSON 字段： • document — 修正后的完整正文 • expectedVersion — 可选乐观锁 • scope / topic / tags — 可选元数据更新

成功响应含 corrected: true，且 atom.version 递增。引擎会重算 staging 向量，L3 搜索无需另开 ingest 任务即可反映新正文。

MCP：memory_correct_atom

IDE Agent 应调用 memory_correct_atom，参数与 REST 一致：memoryLibraryId、atomId、document，以及可用的 expectedVersion。与 memory_save_atom 一样需要 memory:write。

推荐流程：memory_search 或 memory_recall → 发现过时命中 → memory_correct_atom 写入修正正文。除非刻意保留并行笔记，否则不要对同一事实再 memory_save_atom。

记忆库级自动修正策略

在控制台打开某记忆库的「设置」，开启「MCP 自动修正」。当该库为 MCP 默认库时，服务端会向 Agent 注入 CORRECT MEMORY POLICY：会话中主动修正过时 Atom，而不是重复写入。

memory_list_libraries 返回各库的 autoCorrectEnabled，无团队默认库时 Agent 也可自检策略。团队级保存策略（proactive / session_end / off）不变 —— 修正是独立的、按库开关的能力。

修订归档位置

递增 version 前，旧正文归档到 Atom 目录下 revisions/v{N}.md 与 revisions/v{N}.json。在线 .md 与 metadata.json 仍是检索真源；修订文件用于审计与人工回看，不会作为独立搜索命中。

契约版本

本能力随 REST、MCP 与 engra-memory Skill 集成版本演进；**1.4.0** 起 MCP/REST 写与修正默认异步（202 + job.id）。CI 中可用 GET /api/v1/memory/version 核对 api / mcp / skill / engine 版本钉扎。