codex-memory-curator

Codex 记忆整理器

目标

审计 Codex 记忆，将其视为由用户拥有的持久状态；分类过时、不安全、重复或位置不当的声明，并安排审查、规划、持久化和清理。即使从 Cursor 调用，也只检查 Codex 记忆/配置，不检查 Cursor 状态。

核心原则

记忆是上下文，不是真相。最新的用户请求、当前仓库文件、AGENTS.md、包文件、ADR 和实时证据优先于存储的记忆。

适用场景

• 用于审查、放置、配置、规划或清理 Codex 记忆及其持久配置。
• 用于记忆过时、冲突、敏感、杂乱、跨仓库，或导致行为退化的情况。

不适用场景

• 除非明确涉及 Codex 记忆/配置，否则不要用于常规文档、通用提示词工作或 Cursor 状态。
• 对于审查请求，请保持只读；除 Codex 记忆/配置以及解决冲突所需的最少仓库证据外，不要检查任何个人文件。

工作流选择

按以下固定顺序简要展示全部八种工作流（意图明确时可精简）。推荐与请求结果和交付方式相符的路径；若用户仅调用本工具，则推荐 review-chat，并请用户选择：

工作流	交付方式和结果
plan-run-cleanup-file	单条记录：审查、经批准的计划、备份、清理、验证。
review-chat	聊天：只读审查和建议。
review-file	单条记录：只读审查和建议。
cleanup-chat	聊天和备份：审查、高置信度的原子清理、验证。
cleanup-file	单条记录和备份：审查、高置信度的原子清理、验证。
plan-cleanup-chat	聊天：审查和经批准的计划；不执行清理。
plan-cleanup-file	单条记录：审查和经批准的计划；不执行清理。
plan-run-cleanup-chat	聊天和备份：审查、经批准的计划、清理、验证。

根据意图选择路径，而不是添加 auto 工作流：

• 直接审查默认选择 review-chat；明确要求持久化时选择 review-file。
• 明确要求清理但未指定交付方式时，选择 plan-run-cleanup-file。
• 若请求明确指定交付方式和执行意图，可选择其他匹配的路径。
• 由 Agent 发起的激活只能选择相关的只读路径。只有当现有任务已要求持久化时，才使用 review-file；绝不要推断用户要求清理。
• 若用户仅调用本工具、提示互相冲突，或对审查还是清理、聊天还是文件、是否执行、Codex 主目录或修改权限存在歧义，则展示表格并请用户选择。
• 只有当用户已要求清理已确定范围内的 Codex 记忆时，才可选择会修改内容的路径。

实质性检查开始前，完整说明所有有限选项，并注明 Selected、Reason、Codex 主目录/仓库目标、写入范围、预期产物、受保护状态、Plan 模式能力和尚未解决的审批事项。复用任务中已明确的事实和具体权限，并将已知字段简要合并说明。若选择明确，说明后继续；若有歧义，则在盘点前暂停，只询问尚未确定的选项。不要重复展示选择器，也不要再次询问已确认且未变更的选择。

选择工作流并不意味着获得以下权限：删除整个文件、进行破坏性恢复、更改配置、执行付费或外部操作、部署、发布或扩大范围。

要检查的输入

• 解析用户提供的 Codex 主目录或 ${CODEX_HOME:-$HOME/.codex}，然后检查请求的 memories 范围。仅当用户请求检查配置，或需要检查配置以解决范围内的冲突时，才检查 config.toml。
• 仅在需要核实有争议的说法时，检查当前仓库中的证据。
• 仅在分类、冲突、配置模式、存储结构和安全编辑参考资料中的决策与当前情况相关时，才加载对应资料。生成报告或计划时，加载相应的资源文件。

安全规则

• 如果处理路径尚未确定，则不要检查；除非已选定路径且用户请求授权清理确切目标范围，否则不要进行任何更改。
• 切勿在未说明的情况下删除、重写、截断或移动记忆文件。
• 在获准编辑前，备份每个确切的文件，并报告备份路径。
• 不要输出完整的机密、令牌、凭据、客户数据、私人标识符或敏感个人数据。
• 如果发现类似机密的数据，请在输出中对值进行脱敏；尽可能指出文件和行，并建议移除；如果是真实凭据，还应建议轮换。
• 如果记忆架构不明确，不要直接编辑。将其留待当前记录或聊天结果中处理。
• 将记忆文件视为生成状态，除非本地说明证明并非如此。不要重写只追加的证据来修正过时的整理后说法。
• 不要将特定仓库的假设全局套用。仓库规则应优先参考 AGENTS.md 或仓库文档。
• 不要运行大范围的破坏性命令。

工作流

每种路由都必须在规划或清理前，对明确请求的范围应用相同的审核质量。针对单个文件或声明的请求，并不授权检查整个存储区：应使用定向读取，而不是整个根目录的清点／扫描命令；只有为解决范围内的冲突时，才查阅其他证据。交付方式绝不降低审核质量：

1. 确认所选路由、Codex 主目录、仓库目标（如适用）持久化路径，以及受保护状态。按如下方式查找 Codex 主目录：

   如果已设置 ${CODEX_HOME}，则使用它；否则使用用户主目录加上 .codex。

2. 对明确涵盖整个记忆存储区的请求，在不输出内容的情况下清点所有记忆文件：

   node scripts/inventory-memories.mjs
   

   对于范围更窄的请求，跳过此全存储区命令，并通过定向读取，仅清点明确请求的路径。

3. 对整个存储区的请求，在查找敏感、过时、范围过广、本地、特定于仓库或类似配置的条目时，运行脱敏风险扫描器：

   node scripts/scan-memory-risks.mjs --json
   

   对于单文件或单声明审核，请在请求范围内进行定向读取；不要运行此全存储区扫描器，因为它没有文件选择器。退出代码 1 表示发现了问题，并不表示扫描失败。扫描器会限制返回的问题数量，且默认跳过生成的证据；仅在需要时提高 --max-findings 或添加 --include-generated-evidence。 将扫描器 JSON 用作证据；报告数量和信号最强的脱敏问题，而不是粘贴完整负载。

4. 如果请求了配置，或需要配置来解决范围内的冲突，请使用 node scripts/locate-memory-config.mjs --json 查找整个 <codex-home>/config.toml 中的记忆／配置信号。定位器只会输出行号和固定信号名称，绝不输出值。仅检查相关的有限区段，包括其表／配置文件上下文；对敏感值进行脱敏。候选匹配并非已解析的 TOML，也不能证明生效配置。

5. 将记忆模式分类为已禁用、已启用但未注入、已启用且已注入、外部上下文生成已禁用，或未知。加载 references/config-modes.md，了解确切的模式信号。

6. 如果存在多种记忆文件类型，在决定哪些内容可以安全编辑之前，先加载 references/memory-store-anatomy.md。

7. 分小段读取记忆文件；避免大量倾倒内容，并对敏感值进行脱敏。

8. 每行提取一个原子声明。分类前拆分复合条目。

9. 仅根据解决争议声明所需的当前仓库文件核实冲突。当优先级不明确时，加载 references/conflict-resolution.md。

10. 为每个原子声明恰好指定一个主要分类：KEEP、KEEP BUT REWRITE、MOVE TO AGENTS.md、MOVE TO REPO DOCS、MOVE TO SKILL、MOVE TO CONFIG、DELETE 或 ASK USER。

11. 仅将高风险条目标记为有用上下文：stale、duplicated、too-broad、too-specific、repo-specific、workflow、config、sensitive、conflicting 或 useful。

12. 为每个条目添加置信度（high、medium 或 low）和建议操作。

13. 在规划或编辑之前完成完整审核。路由交付不得降低审核质量或扩大请求范围。

路由执行

• review-chat：在聊天中返回审查结果，不创建持久化整理报告。
• review-file：持久化单条整理记录，不更改记忆或配置。
• cleanup-chat：仅从已完成的审查中提取高置信度的原子操作，备份每个确切的待修改文件，应用操作，重新读取已更改的部分，并在聊天中报告验证结果。不创建持久化整理报告。
• cleanup-file：在修改前创建整理记录；如果持久化失败，则停止。然后备份确切的文件，应用仅限高置信度的原子操作，并在同一记录中补全执行和验证信息。
• plan-cleanup-chat 和 plan-cleanup-file：进入 Plan 生命周期，与用户确定清理计划，并在获得批准后停止，不更改 Codex 状态。
• plan-run-cleanup-chat 和 plan-run-cleanup-file：进入 Plan 生命周期，确定并批准完整的清理计划，重新检查状态，退出 Plan 模式，备份确切的文件，仅执行未变更的计划，并进行验证。计划获批后，不要再笼统地询问是否清理。

直接清理（cleanup-chat 或 cleanup-file）仅限于对现有、可编辑且由运行时管理的 Codex 记忆进行高置信度的原子编辑、移动或条目删除。推迟整文件删除、新建上下文文件、配置、AGENTS.md、仓库文档、技能、仅追加的生成证据、不确定的架构、中低置信度变更以及任何范围扩展。只有当获批计划列明每个目标位置、写入路径、备份、回滚方式和单独的审批边界时，plan-run 路由才可执行范围更广的整理变更。

Plan 生命周期

在每条路由上，都要尊重当前启用或请求启用的原生 Plan 模式，以及实际写入权限：Plan 模式启用期间或权限未知时，不得写入报告、备份或清理内容。规划可以在只读状态下继续，无需手动切换模式。对于 plan-* 路由或尚未解决的重要问题，请阅读 references/plan-lifecycle.md。复用未变更的审批；仅退出模式不代表获得批准，未回答的问题也不授予任何权限。写入前重新检查状态，仅对重要变更重新确认。仅规划的路由绝不授权清理。

不要在此整理工作流中调用 codex-spec-interviewer。如果发现需要更广泛的持久规则、仓库规范或尚未解决的产品决策，请先完成所选整理路由，再将访谈工具作为单独的后续事项提出。

文件交付约定

文件路由恰好持久化一条脱敏的整理记录。优先使用仓库原生的现有报告位置；否则使用 <repo>/.agent-reports/codex-memory-curation/<UTC timestamp>-<selection-id>.md。创建新路径，不得覆盖现有内容，并将该路由的所有输出保存在该记录中。

记录包含 Review、Plan、Execution Receipt、Deferred Work、Backup 和 Verification。对于该路由未执行的阶段，注明 not applicable 并说明原因。对于 cleanup-file 和 plan-run-cleanup-file，必须在修改前创建记录；持久化失败时不得继续清理。聊天路由不创建报告文件。备份目录仍是必需的安全产物，不计作整理报告。

Explicit --backup-root requires a stable non-sensitive --backup-root-alias; file routes persist the script-reported portable storage locator and <storage-locator>/backup-manifest.json. 仅在未持久化的聊天中报告确切的绝对备份路径和清单路径，绝不可将其写入仓库产物。

分类检查

对于每条原子声明，都要检查其稳定性、适用范围、可移植性、可靠性、重复性、过时情况、敏感性、与更高优先级内容的冲突、措辞是否简洁，以及 AGENTS.md、仓库文档、技能、配置或删除是否更为精确。详细规则和示例请参阅 references/classification-rubric.md。

参考资料

仅在需要时阅读：

• 分类与冲突：references/classification-rubric.md、references/conflict-resolution.md。
• 配置与存储边界：references/config-modes.md、references/memory-store-anatomy.md。
• 安全修改与示例：references/safe-editing-procedure.md、references/example-review-report.md。
• 输出产物：assets/review-report-template.md、assets/cleanup-plan-template.md。

脚本

仅在需要时使用。所有脚本均为非交互式脚本，仅使用 Node.js 标准库，并接受 --help。

node scripts/inventory-memories.mjs [--codex-home PATH] [--json]
node scripts/locate-memory-config.mjs [--codex-home PATH] [--json]
node scripts/scan-memory-risks.mjs [--codex-home PATH] [--json] [--max-findings N] [--include-generated-evidence]
node scripts/backup-memories.mjs [--repo PATH] [--codex-home PATH] [--backup-root PATH --backup-root-alias NAME] [--include PATH ...]

• 配置定位器为只读，会扫描完整文档，包括靠后的表格以及带点号或引号的键。它用于辅助发现；注释和字符串也可能匹配，因此在分类模式前，请先解析 TOML 作用域、生效的配置文件和覆盖项。
• 清单工具为只读。扫描器为只读，默认会进行脱敏、限制发现结果数量，并跳过生成的证据（除非另行请求）；发现问题时返回退出码 1，而非表示执行失败。
• backup-memories.mjs 会创建一个不会覆盖现有文件的备份，以及 backup-manifest.json，不会编辑源文件。未脱敏的备份内容和清单必须存放在 Git 工作树之外，并且存放在解析后的 Codex memories 树之外，包括物理别名。预检会拒绝不安全的根目录以及路径中的每个符号链接组件；任何遍历错误都会在创建根目录前导致失败。编辑时使用精确的 --include 路径；不指定任何 include 时会保留旧版发现行为。调用前，请阅读 references/safe-editing-procedure.md，了解根目录安全、预检、清单核对和恢复。

输出格式

使用上文的工作流公告。在公告中，仅报告尚未解决的审批关卡；在所选路线的结果中，根据下文的路线执行和文件交付约定，报告其所需交付物和验证结果。

生成报告前，加载并遵循 assets/review-report-template.md，将其作为规范的标题和字段约定。文件路线会将该完整模板复制到唯一的整理记录中；聊天路线仅在聊天中呈现适用的部分，不创建报告文件。填写所有适用字段；对于跳过的阶段，说明原因并填写 not applicable；敏感值须脱敏。

编辑前，完成审查表和决策表。编辑后，在同一记录中补全回执，包括清单核对和未匹配路径、新路径（created-no-preimage）及回滚、备份模式和清单路径、备份完整性结果，以及行格式 | Changed path | Backup destination | Bytes | SHA-256 | Verification |。

完成标准

• 从明确授权或已解决的歧义中选择八种规范工作流之一；不得仅凭 Agent 激活推断需要清理。
• 已清点适用的记忆/配置，或报告其缺失；只有在明确授权清理敏感数据时，才可更改生成的证据。
• 每项原子声明都具有一种分类、风险标签、置信度、操作，以及适用时的更高优先级冲突证据。
• 满足计划/直接清理要求和目标边界。
• 交付内容符合规范模板；每项编辑都有精确备份、清单核对、重新读取和完整性证明。

失败模式

• 缺少记忆/配置：报告缺少的内容，以及是否可能由启用状态、应用默认值或其他 Codex 主目录所致。
• 架构未知：暂缓操作，不编辑或创建同级状态。
• 内容敏感或存在冲突：进行脱敏；引用位置和更高优先级来源；建议移除/轮换，或将其分类为改写、移动或删除。
• 持久化、备份或已批准状态复查失败：在修改前（或进一步修改前）停止，报告失败；状态发生偏移后，返回规划阶段。