engram-memory

Engram 持久化记忆——协议

你可以使用 Engram，这是一个可跨会话和上下文压缩持续保留的记忆系统。 Agent 必须遵循此协议，无需等待激活。

可用工具

使用 Codex 实际提供的 Engram 工具及其注册名称。 以下名称是逻辑名称；工具的可用性和发现方式取决于 Codex 特定宿主的工具接口，而非通用引导流程或延迟工具拆分。

• mem_save、mem_search、mem_context、mem_session_summary

• mem_get_observation、mem_save_prompt、mem_current_project、mem_judge、mem_compare

• mem_update、mem_review、mem_pin、mem_unpin、mem_suggest_topic_key

• mem_session_start、mem_session_end、mem_doctor、mem_capture_passive

主动保存触发条件（必须执行——不要等用户提出要求）

出现以下任一情况后，立即调用 mem_save，无需等待用户要求：

做出决策或确立惯例后

• 做出架构或设计决策
• 记录或确立团队惯例
• 商定工作流变更
• 权衡取舍后选择工具或库

完成工作后

• 修复 Bug（包括根本原因）
• 以不易察觉的方式实现功能
• 创建或更新内容重要的 Notion/Jira/GitHub 文档
• 更改配置或完成环境设置

有新发现后

• 对代码库有不易察觉的新发现
• 发现陷阱、边缘情况或意外行为
• 确立模式（命名、结构、惯例）
• 了解到用户偏好或约束

用户确认或否决后

• 用户确认你提出的建议（例如“就这么做”“我们按这个来”“听起来不错”“同意”“很好”，或其他同义表达）
• 用户否决某个选项或方案（例如“不，还是选 X”“不是那个”，或其他同义表达）
• 用户表达偏好（例如“相比 Y，我更喜欢 X”“以后都按这种方式做”，或其他同义表达）
• 在你列出权衡或选项后，用户做出决定
• 讨论最终明确了方向——即使该方向由 Agent 提出

自检——每项任务结束后都要问自己：

“我或用户刚刚是否做出了决策、确认了建议、表达了偏好、修复了 Bug、发现了不易察觉的信息，或确立了惯例？如果是，现在就调用 mem_save。”

mem_save 的格式：

• title：动词 + 内容——简短且便于搜索（例如“修复 UserList 中的 N+1 查询”“选择 Zustand 而非 Redux”）
• type：bugfix | decision | architecture | discovery | pattern | config | preference
• scope：project（默认）| personal | global
• topic_key（可选，但建议为持续演进的主题设置）：稳定的键，例如 architecture/auth-model
• content： What：一句话说明做了什么 Why：说明原因（用户请求、Bug、性能等） Where：受影响的文件或路径 Learned：陷阱、边缘情况、意外发现（如无则省略）

主题更新规则（必须遵守）

• 不同主题绝不能互相覆盖（例如：架构决策与 Bug 修复）
• 如果同一主题持续演进，请使用相同的 topic_key 调用 mem_save，以更新（upsert）记忆，而不是创建新的观察记录
• 如果不确定键名，请先调用 mem_suggest_topic_key，随后始终一致地复用该键
• 如果已经知道要修正的确切 ID，请使用 mem_update

何时搜索记忆

当用户要求回忆某件事时——无论是说“记得”“回想一下”“我们做了什么”“我们是怎么解决的”，或用用户语言表达相同意思，或提及过去的工作：

1. 首先调用 mem_context——检查近期会话历史（快速、成本低）
2. 如果没找到，则使用相关关键词调用 mem_search（FTS5 全文搜索）
3. 如果找到匹配项，则使用 mem_get_observation 获取完整、未截断的内容

以下情况也要主动搜索记忆：

• 开始处理可能以前做过的事情时
• 用户提到你不了解的主题时——检查过去的会话是否涉及该主题
• 用户的第一条消息提及项目、功能或问题时——回复前，使用消息中的关键词调用 mem_search，检查是否有相关的历史工作

交付保证

记忆操作属于内部记录，绝不能出现在面向用户的答复中。完成任务答复前，先完成必需的记忆工作；然后在本轮以最终消息发送完整答复，之后不要再调用任何工具。如果记忆操作失败或需要后续处理，仍要发送答复。

会话结束流程（必需）

在结束会话或说“完成了”／“就这样”之前，你必须：

1. 按以下结构调用 mem_session_summary：

目标

[本次会话处理的内容]

指示

[发现的用户偏好或约束——若没有则跳过]

发现

• [技术发现、注意事项、不明显的经验]

已完成

• [已完成的事项及关键细节]

后续步骤

• [尚待处理的事项，供下次会话继续]

相关文件

• path/to/file — [文件用途或变更内容]

此要求不是可选项。如果跳过，下一次会话将无法了解前情。 摘要持久化不会结束会话。Codex 的 SessionEnd hook 会独立负责会话生命周期的关闭。

被动捕获——特定适配器的安全机制

完成任务或子任务时，请附上“## 关键经验：”部分，并使用编号列出要点。 自动捕获因适配器而异：Codex 的 SubagentStop hook 会转发符合条件的委托／子 Agent 输出，以便服务端提取。主 Agent 的普通答复不会通过此 hook 自动捕获；仅添加该部分并不能保证内容已保存。对于重要且已验证的知识，请优先使用 mem_save。

示例：

关键经验：

1. bcrypt 的 cost=12 是服务器性能与安全性之间的最佳平衡
2. JWT 刷新令牌需要原子轮换，以避免竞争条件

你也可以直接调用 mem_capture_passive(content)，传入包含经验部分的任意文本。 此显式提取机制是一种安全保障，不能替代 mem_save。

压缩后

如果看到有关压缩或上下文重置的消息，或者上下文中出现“FIRST ACTION REQUIRED”：

1. 立即使用压缩后的摘要内容调用 mem_session_summary——保存压缩前已完成的工作
2. 然后调用 mem_context，恢复之前会话中的其他相关上下文
3. 只有完成上述步骤后，才能继续工作

不要跳过第 1 步。否则，压缩前完成的所有工作都会从记忆中丢失。

Codex 会话绑定

Codex 为 mcp__engram__mem_* 和 mcp__plugin_engram_engram__mem_* 注册原生 PreToolUse 命令 engram hook codex-pre-tool-use。对于受支持的 Engram 写入/会话工具，它会先将权威的 Codex 主机会话解析为服务器确认的 Engram 身份，再绑定参数：写入操作使用 session_id，会话开始/结束操作使用 id。mem_session_end 使用 id，而非 session_id。请勿编造或覆盖此身份。只读工具不受影响；输入格式错误或主机解析未经确认时，会拒绝变更调用。

生命周期钩子还会在注册或续期后提供已确认的身份。对于直接/未拦截的客户端，请将此确切身份用于带会话归属的写入操作（mem_save、mem_save_prompt、mem_session_summary、mem_capture_passive）中的 session_id，以及 mem_session_end 中的 id。确认信息缺失时，切勿重建恢复会话后缀或猜测 ID。

回退方案：如果工具意外不可用，请运行 engram setup codex 并重启 Codex。此设置会修复 Codex 的权威 [mcp_servers.engram] 注册；请使用 Codex 实际公开的工具名称。