claude-memory-curator

Claude 记忆整理器

目标

审查 Claude Code 的持久上下文，将其视为用户拥有的 Agent 状态：找出过时、不安全、重复、范围过宽、相互冲突、放置不当或无法强制执行的条目；提出更合适的存放位置；并通过一套明确的约定统一处理审查、规划、持久化和清理。

范围仅限 Claude Code 的相关界面：CLAUDE.md、CLAUDE.local.md、按条件加载的 AGENTS.md、.claude/rules/、用户级 Claude 规则、设置、钩子、托管策略依据和自动记忆文件。不要将其用作 Codex、Cursor、Claude 应用或 Anthropic API Memory Stores 的整理器。

适用场景

• 用于审查、放置、规划或清理描述中提到的 Claude Code 持久上下文界面。
• 当这些界面内容过时、相互冲突、敏感、范围过宽、被忽略，或导致 Claude 重复使用旧指导时使用。

不适用场景

• 不用于 Codex、Cursor、Claude 网页版／应用、Anthropic API Memory Stores、通用提示词工程，或不涉及 Claude 持久上下文的仓库文档清理。
• 审查请求应保持只读。托管策略（包括 /etc/claude-code/CLAUDE.md 和 managed-settings.json）应视为只读，除非明确授予了具体的编辑权限。

工作流选择

按以下固定顺序提供全部八种工作流；意图明确时可精简呈现。根据用户要求的结果和交付方式推荐对应路径；对于未说明具体需求的调用，推荐 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；绝不可推断用户要求清理。
• 对于未说明具体需求的调用、相互矛盾的线索，或在审查还是清理、聊天还是文件、是否执行、目标路径或修改权限方面存在歧义时，展示此表并请用户选择。
• 仅当用户已要求清理已确定范围内的 Claude 上下文时，才可选择会修改内容的路径。

在实质性检查之前，一次性说明全部有限选项，并声明 Selected、Reason、目标路径、写入范围、预期产物、受保护状态、Plan 模式能力以及尚待批准的事项。复用任务中已确立的事实和明确权限；将已知字段合并成简短说明。如果选择明确，说明后继续操作。如果存在歧义，则在盘点前停止，只询问尚未明确的选项。不要重复展示选择器，也不要再次询问用户确认未变更的选择。

选择工作流并不代表获得了删除整个文件、破坏性恢复、编辑受管策略、执行付费或外部操作、部署、发布或扩大范围的授权。

要检查的输入

• 当 AGENTS.md 相关时，阅读 references/context-surface-anatomy.md。分别盘点文件是否存在以及是否实际加载：确认 Claude 版本、提供商和功能的可用性、设置、Hook/插件限制以及会话加载证据。对于较旧或受限的宿主，保留有效的 @AGENTS.md 导入。
• 确定仓库、Claude 主目录、已配置的自动记忆目录，以及仅适用的项目/用户指令、规则、设置、Hook、受管策略和记忆界面。
• 仅在需要核实有争议的主张时，检查当前仓库证据。
• 仅在以下参考资料中的相应决策需要时，加载位置、分类、冲突、强制执行和安全编辑参考资料。凡是要生成报告或计划产物时，都加载相应的报告或计划素材。

工作流

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

1. 确定所选路线、目标仓库、Claude 主目录、自动记忆路径、适用时的持久化路径，以及受保护状态。

2. 清点 Claude 上下文，但不转储内容：

   node scripts/inventory-claude-memory.mjs --repo .
   

   用户提供非默认位置时，添加 --claude-home PATH 或 --memory-dir PATH。结构化证据有用时，使用 --json。

3. 查找敏感、过时、范围过广、本地、特定于仓库、已忽略或容易冲突的条目时，运行经过脱敏的风险扫描器：

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

   退出代码 1 表示发现了问题，并不表示扫描失败。总结数量和最有参考价值的脱敏发现，不要粘贴完整内容。

4. 解析 .claude/rules/**/*.md 的 frontmatter 中的 paths，以免将路径范围限定的指导误认为始终加载的指导。

5. 检查可见设置中的 autoMemoryEnabled、autoMemoryDirectory、claudeMdExcludes、权限规则和钩子（当它们会影响放置位置时）。

6. 默认将受管理的策略文件和受管理的设置视为优先级更高的只读证据。

7. 将 MEMORY.md 视为自动记忆入口文件。除非用户要求审核整个记忆目录，否则将主题文件视为按需提供的详细信息。

8. 分块读取上下文文件，并对敏感值进行脱敏。

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

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

11. 为每条原子声明指定且仅指定一个主要分类：KEEP、KEEP BUT REWRITE、MOVE TO CLAUDE.md、MOVE TO CLAUDE.local.md、MOVE TO CLAUDE RULE、MOVE TO AUTO MEMORY TOPIC、MOVE TO AGENTS.md、MOVE TO REPO DOCS、MOVE TO SKILL、MOVE TO SETTINGS、MOVE TO HOOK、MOVE TO MANAGED POLICY、DELETE 或 ASK USER。

12. 将高风险条目标记为仅供参考的上下文：stale、duplicated、too-broad、too-specific、repo-specific、workflow、config、sensitive、conflicting、unenforced、managed-policy 或 useful。

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

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

路由执行

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

直接清理（cleanup-chat 或 cleanup-file）仅限于对现有、可编辑且由运行时管理的 Claude 上下文进行高置信度的原子编辑、移动或条目删除。将整文件删除、共享的 AGENTS.md、新的上下文文件、设置、钩子、托管策略、AGENTS.md、仓库文档、技能、仅通过 UI 管理的 User/Team 设置、不确定的架构、中低置信度更改以及任何范围扩展都推迟处理。仅当获批计划明确列出每个目标位置、写入路径、备份、回滚方案和单独的批准边界时，计划执行路由才能执行更广泛的整理更改。

Plan 生命周期

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

不要在此整理工作流中调用 claude-spec-interviewer。如果发现需要制定范围更广的持久规则、仓库规范或尚未解决的产品决策，请完成所选整理路由，然后将访谈工具作为单独的后续步骤提供。

文件交付约定

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

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

显式设置 --backup-root 时，必须提供稳定且不含敏感信息的 --backup-root-alias；文件路由需持久化脚本报告的可移植存储定位符以及 <storage-locator>/backup-manifest.json。仅在未持久化的聊天中报告确切的绝对备份路径和清单路径，切勿将其写入仓库产物。

安全规则

• 如果路由尚未确定，请勿检查；除非所选路由和用户请求授权清理确切的目标范围，否则请勿修改。
• 切勿悄悄删除、重写、截断或移动 Claude 上下文文件。
• 每次获批编辑前，都要备份每个确切文件，并报告备份路径。
• 请勿输出完整的密钥、令牌、凭据、客户数据、私人标识符、内部主机名或敏感个人数据。
• 如果发现类似密钥的数据，请在输出中遮盖其值；尽可能标明文件和行号，建议删除，并建议轮换真实凭据。
• 如果自动记忆主题架构不明确，请勿直接编辑。应在当前记录或聊天结果中说明并暂缓处理。
• 将 CLAUDE.md 和自动记忆视为上下文，而非强制规则。对于确定性限制，请建议使用设置或钩子。
• 不要将特定仓库的假设全局应用。对于仓库规则，优先参考项目的 CLAUDE.md、.claude/rules、AGENTS.md 或仓库文档。
• 不要运行大范围破坏性命令。

参考资料

仅在需要时阅读：

• 位置与分类：references/context-surface-anatomy.md、references/classification-rubric.md。
• 冲突与强制执行：references/conflict-resolution.md、references/settings-and-hooks.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-claude-memory.mjs [--repo PATH] [--claude-home PATH] [--memory-dir PATH] [--json]
node scripts/scan-claude-memory-risks.mjs [--repo PATH] [--claude-home PATH] [--memory-dir PATH] [--json] [--max-findings N]
node scripts/backup-claude-memory.mjs [--repo PATH] [--claude-home PATH] [--memory-dir PATH] [--backup-root PATH --backup-root-alias NAME] [--include PATH ...]

• 清单生成是只读操作。扫描器也是只读的，默认会遮盖数据、限制发现项数量；有发现项时以退出码 1 结束，而非表示执行失败。
• backup-claude-memory.mjs 会创建一个不覆盖现有文件的备份和 backup-manifest.json，且不会编辑源文件。未遮盖的备份内容和清单必须保存在 Git 工作树之外。预检会拒绝不安全的根目录和路径中的所有符号链接组件；任何遍历错误都会在创建根目录前导致失败。编辑时请使用精确的 --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 已激活就意味着授权清理。
• 已盘点适用的上下文、.claude/rules 元数据、设置和自动记忆边界，或已报告其缺失。
• 每项原子主张都有一个分类、风险标签、置信度、操作，以及适用时的高优先级冲突证据。
• 确定性限制通过设置或钩子落实；遵守 Plan 和直接清理边界。
• 聊天或文件交付符合规范模板要求；每项获批编辑都有精确文件备份、清单核对、重新读取和完整性结果。

故障模式

• 缺少界面或自动记忆路径：说明哪些内容不可用，并仅在必要时请求 /memory、claude --version 或明确指定 --memory-dir。
• 受管策略或未知架构：保持只读，并建议或暂缓手动操作。
• 敏感或冲突的内容：进行脱敏；注明位置和更高优先级的来源；建议移除或轮换，或将其分类为重写、移动、删除或交由用户决定。
• 持久化、备份或已批准状态复核失败：在修改前（或进一步修改前）停止，报告失败，并在出现偏差后返回规划阶段。