claude-migrate-memory-to-doc

将 Claude Code 记忆迁移到与工具无关的文档

此技能的用途

Claude Code 的个人记忆保存在 ~/.claude/projects/<project-slug>/memory/ 中。它仅限 Claude Code 使用：不会随仓库进行版本控制，其他工具也无法查看。用户只要在同一目录中运行 Codex、Cursor 或其他 AI 命令行工具，这些工具就无法读取“用户是谁／该如何与用户协作”——尽管任何 AI 助手都应先了解用户资料和协作偏好。

此技能会将可跨工具共享的内容从记忆中移出，放到与工具无关的位置，并让记忆仅作为轻量的交接缓存。它解决的真正问题是工具锁定，而不是“记忆杂乱”。

此技能会内联运行（绝不使用 context: fork）：它会并行启动审核子 Agent，并通过 Bash 运行 codex——分叉的子 Agent 两者都无法完成。

首先：目标是什么？

目标	用户想要什么	路径
A — 解除工具锁定	其他 AI 工具也能读取相同的资料和偏好；记忆仍作为轻量的交接缓存	下方的工作流，包含所有阶段
B — 停用自动记忆	让某个项目停止使用自动记忆，并由文档接管其中的所有内容	references/retire_auto_memory.md；使用下方工作流中的第 1 阶段范围表和第 6 阶段归档规则，并且仅当用户也希望 Codex 能读取结果时，才执行第 2 和第 5 阶段

目标 B 不包含“保留在记忆中”的类别：交接状态、外部指针和待裁定事项都需要归入文档，记忆目录最终必须为空，并且要关闭项目级开关并通过对照探测验证。如果请求未说明目标，先询问用户。

核心要点——动手前请先阅读

难点不在于移动文件，而在于：

只能通过纯文本指针找到的参考文件，需要按需读取，且无法保证一定会加载——在任一工具中都是如此。

• Claude Code 仅通过 @import 语法自动预加载参考文件。纯文本指针（“参见 ~/.claude/references/user/foo.md”）只能按需读取：Agent 必须主动选择打开它。
• Codex 的限制更严格：它不会解析或跟随 CLAUDE.md 中写出的文本路径。它只会沿着 ~/.codex → git-root → cwd 链路自动注入文档文件本身（其 AGENTS.md／配置的回退文件）。Codex 绝不会自动加载其他名称的参考文件，例如位于 ~/.claude/references/ 中的文件。

因此，架构必须采用双层拆分：

层	位置	保证
必定命中——每轮都必须成立的少数事实	内联到 CLAUDE.md 正文（两种工具都会注入）	始终存在
按需获取的详细信息——完整资料、往事经验、边缘情况	references/ 文件，通过指针访问	相关时加载

只把关键事实放在参考文件中并寄希望于指针，是导致这次迁移悄无声息地失败的首要原因。请将这些事实内联。

与工具无关的架构

~/.claude/CLAUDE.md            global instructions — BOTH tools inject this.
                               Inline the hardest user facts here (a short "User context" section).
~/.claude/references/user/     SSOT for profile / preferences / methodology / personal affairs.
~/.claude/references/user-profile.md   hub: condensed core + index into the user/ files
~/.codex/AGENTS.md  ──symlink──▶  ~/.claude/CLAUDE.md
                               so Codex's GLOBAL layer injects the same file Claude Code reads.
~/.codex/config.toml           raise project_doc_max_bytes — Codex truncates docs at 32 KiB by default,
                               which silently drops the back half of a long CLAUDE.md.

范围说明：接线配置（~/.codex/ 符号链接、配置编辑和第 5 阶段验证）仅针对 Codex，且只针对 Codex 进行了验证（2026-06）。~/.claude/references/user/ 内容层可迁移到任何会自动加载项目文档的工具，但 Cursor 和其他工具需要各自的接线配置（Cursor 会读取 .cursor/rules／项目根目录中的 AGENTS.md，而不是 ~/.codex/）——此处未实现或验证。

工作流

将此清单复制到工作笔记中，并逐项勾选：

Memory → Tool-Agnostic Doc Migration:
- [ ] Phase 1: Diagnose & scope — classify every memory file by SCOPE
- [ ] Phase 2: Tool-agnostic migration — references/ + inline hardcore + symlink + config
- [ ] Phase 3: Multi-agent review — 4 parallel reviewers
- [ ] Phase 4: Fix everything review surfaced
- [ ] Phase 5: VERIFY BY RUNNING CODEX (not by reasoning)
- [ ] Phase 6: Memory cleanup — clean / thin / keep + soft-delete to backup

阶段 1 — 诊断与界定范围

预检 — 查找记忆目录。 Claude Code 的记忆位于 ~/.claude/projects/<project-slug>/memory/，其中 <project-slug> 是工作目录路径将 / 替换为 - 后的结果。用户可能在多个项目中都有记忆 — 使用 ls ~/.claude/projects/*/memory/ 列出它们，并选择（或合并）包含跨工具用户内容的项目。

列出该记忆目录下的所有文件。按范围分类，而不是看“是否杂乱”。完整的决策表，以及 Agent 无法判断私人上下文的注意事项：请阅读 references/diagnosis_and_scoping.md。

简要说明：

• 团队规则 / 标准 / SOP → 项目 CLAUDE.md 或 docs/（受版本控制，团队可见）。
• 跨工具用户档案 / 协作偏好 / 方法论 / 个人事务 → ~/.claude/references/user/（与工具无关）。这部分需要迁移。
• 临时交接快照 / 外部系统指针 → 留在记忆中。这是记忆的正当用途；不要迁移。（目标 B：改为将这些内容存入文档，见 references/retire_auto_memory.md §4。）

在称任何条目为“没有任何地方涵盖”之前，请搜索所有可能存放该内容的位置：全局和项目指令文件、~/.claude/references/、所有技能源代码库（公开和私有）、项目文档和交接资料包，以及钩子或脚本头部。在发送给任何子 Agent 的提示词中列出所有这些根目录 — Agent 只会搜索明确告知它的目录。先用一个已知存在的字符串校准每条搜索命令，再相信零结果。

不要迁移所有内容。把过时的交接状态迁入长期文档本身就是一种错误。但要检查整个目录 — 不要只看 feedback_*.md — 因为项目 SOP 和运维经验教训往往位于 project_*.md 或 architecture_*.md 文件中，应该归入代码库的文档。

此阶段还要标记私人上下文 / 个人身份信息（PII）：如果某个记忆文件将系统用户名映射到真实姓名、私人联系人或其他个人身份信息，即使与项目相关，也应留在私人记忆中。项目文档受版本控制且可能被共享；身份映射应留在精简的交接层中。

阶段 2 — 与工具无关的迁移

先备份 CLAUDE.md（cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak）— 即将编辑该文件。如果 ~/.claude/CLAUDE.md 不存在，就创建它（有些用户只有项目级文件）。

如果 command -v codex 没有输出（未安装 Codex）：只执行以下步骤 1 和 4（references/ + CLAUDE.md 内联内容），并跳过符号链接（2）、配置（3）和整个阶段 5。内容迁移仍然照常进行；请注明稍后接入 Codex 时需要添加符号链接并设置 project_doc_max_bytes。

对于每个“迁移”条目，将内容移至 ~/.claude/references/user/（按主题归入少量文件，并以 user-profile.md 作为索引页）。然后设置双层架构：

1. 将最核心的内容内联到 ~/.claude/CLAUDE.md 顶部附近的 # User context 部分中（位于前约 32 KiB 内，以便 Codex 能读取）：每轮都必须遵循的 3–6 条事实（例如如何称呼用户、硬性偏好、最重要的一条身份信息）。其他所有内容都保留为指针。
2. 建立符号链接 ~/.codex/AGENTS.md → ~/.claude/CLAUDE.md（仅当 ~/.codex/AGENTS.md 不存在或是空占位文件时 — 绝不覆盖有效文件）。
3. 如果 CLAUDE.md 超过 32 KiB，则在 ~/.codex/config.toml 中调高 project_doc_max_bytes。
4. 更新项目的知识存储规则（如果有），避免“用户偏好 → memory”与新的“用户档案 → ~/.claude/references/user/”现状相矛盾。

准确的目录布局、中心辐射式结构以及治理规则修正方法：references/tool_agnostic_migration.md。

阶段 3 — 多 Agent 审查

并行启动 4 个审查子 Agent（在一条消息中调用多个 Task）。每个 Agent 审查一个维度：内容完整性（是否遗漏或改动了事实）、交叉引用断链（删除记忆后，哪些 [[links]] 会失效）、与工具无关的链接完整性（符号链接／指针链是否确实有效；Codex 是否真的会读取它）、重复／偏移（某条参考是否重复了 CLAUDE.md 中的规则）。准确的提示词见：references/review_and_verification.md。

Agent 的发现是待验证的假设，而非定论——采取行动前，按概率 × 成本 × 是否确实会发生来筛选。

阶段 4 — 修复

处理审查发现的问题。常见的真实问题（均来自一次实际运行）：索引文件遗漏了自己的某个子文件；硬核事实只留在参考资料中（移到正文中）；仍保留的文件中有指向待删除记忆的 [[links]]（改为指向新参考资料）；治理表格中的某一行已更新，但同一章节的判断句仍与之矛盾。

阶段 5 — 运行 CODEX 验证（不要跳过，也不要交给用户）

你可能会想把这一步换成“看起来没问题”或“你之后可以自己检查”。别这么做。**在任意目录中运行 codex，并加上 --skip-git-repo-check；按会话 ID（而非修改时间）匹配会话日志；再 grep 内联的硬核章节和文件后半部分的字符串。**内联章节可能名为 # User context、# 用户上下文，或用户使用的其他本地化标题——grep 实际标题字符串，而不是写死的英文标题。若验证通过，针对该标题的 grep 结果为 1，针对文件后半部分字符串的 grep 结果也为 1（如果 CLAUDE.md > 32 KiB）。经过实际验证的准确命令块——包括 --skip-git-repo-check、会话 ID 的提取方式（它位于头部，而非尾部）、32 KiB 检查，以及 < 32 KiB 和 codex-not-installed 快捷处理方式与预期控制台输出——见 references/review_and_verification.md。请原样使用；不要在这里自行拼凑变体（这样做会导致两份内容出现偏差）。

阶段 6 — 清理记忆

对于未迁移的记忆文件，执行以下三种操作之一（决策详情见 references/diagnosis_and_scoping.md）：

• 清理 — 已过期（日期已过的交接记录）或已陈旧（应当计算而非存储的派生计数）→ 归档。
• 精简 — 重复陈述了其他位置的 SSOT 的交接记录 → 删除重复内容，仅保留指针和易变状态（例如“实例 X 仍在计费，需要关闭”）。
• 保留 — 合理的交接记录 / 已经是清晰的指针 → 保留。（Goal B 不适用：所有内容都会归档。）

更新记忆索引（例如 MEMORY.md），移除已迁移的条目并添加一个迁移指针。

移动任何内容之前，先在整个记忆目录以及项目文档 / CLAUDE.md 中搜索即将归档的文件引用。 如果仍保留的文件或活动文档链接到已归档的文件，就会留下失效引用。将这些链接改到新文档位置或纯文本指针。记忆文件之间的交叉链接并非唯一风险——项目 CLAUDE.md 和交接文档也经常通过名称引用记忆文件。

软删除，绝不硬性 rm。 将已迁移 / 清理的文件移至 memory/ 之外的带日期备份目录（例如，同级目录 ~/.claude/projects/<slug>/.memory-archive-2026-07-06/——使用实际当前日期，不要用占位符）。将归档文件放在 memory/ 内，会让它们仍被视为有效记忆，违背清理目的。更新索引指针，指向 memory/ 之外的新路径。告知用户，在确认两个工具运行正常几周后，可以 rm 删除备份。

如果迁移让你学到了新东西，就更新此技能。 如果遇到 references/failure_cases.md 中未列出的故障模式，就将其补充进去；如果某个步骤的说明不够明确，就完善 SKILL.md 检查清单。不将经验反馈到技能中的技能，会一再犯同样的错误。

切勿（每条都是在实际运行中吃过亏才学到的）

• 不要一上来就选择“删除”。 人们本能地会想删除杂乱的记忆。顺序错了：应先分类为迁移／精简／保留。大多数“杂乱”的记忆要么有可迁移的价值，要么是合理的交接内容——删除就会丢失这些价值。
• 不要以为 reference + pointer 就与工具无关。 在两种工具中，指针都是按需读取的。关键事实必须直接写入 CLAUDE.md 正文，否则它们就不会被加载，你也不会察觉。
• 不要以为 Codex 会跟随文本指针。 它读取的是 AGENTS.md/CLAUDE.md 文件本身，而不是其中写明的路径。这一点已通过官方文档和真实会话日志验证。
• 不要忘记 Codex 的 32 KiB 文档截断限制。 除非提高 project_doc_max_bytes，否则 Codex 会丢弃长篇 CLAUDE.md 的后半部分。用户可能已经在不知情的情况下，只用着半份 CLAUDE.md 好几个月。
• 修改治理表中的某一行后，不要让同一节中的判断逻辑与之矛盾。 修改一条事实后，要搜索检查整个章节。
• 删除记忆文件前，不要忘记搜索指向它的 [[cross-references]]。 如果还有文件指向已删除的文件，就会留下失效链接。
• 当内容取决于用户的私人背景时，不要让 Agent 批量决定删除或保留什么。 Agent 不知道“用户实际重视什么”；应列出候选项，让用户（或掌握完整背景的你）来决定。
• 不要让用户负责验证。 运行 codex 并搜索日志是 Agent 能完成的事——验证闭环应由你负责，而不是交还给用户。
• 不要把“符号链接存在”当作 Codex 验证。 正确的符号链接是必要条件，但并不足够；唯一的证明，是一次真实的 codex exec 会话，其运行日志中包含你内联的关键章节。
• 不要把归档文件放在 memory/ 中。 它仍会作为实时记忆被读取，从而使清理失去意义。应将它移到 memory/ 之外的同级目录。
• 不要把真实姓名身份映射或 PII 迁移到项目文档中。 项目文档受版本控制且会共享。如果记忆文件将 user3 → <a coworker's real name> 关联起来，就应将其留在私有记忆中（若 SSOT 位于其他位置，则精简为指针）——不要移到 docs/。
• 与记忆重复的现有文档，不要未经差异比对就直接覆盖。 许多记忆文件只是文档的部分副本（例如，architecture_v2_decision.md 与 docs/decisions/2026-02-21-v2-architecture.md）。只迁移独有细节；将其追加到现有文档，而不是替换文档。
• 不要只更新记忆中的链接，而忘了更新项目文档中的链接。 CLAUDE.md 和交接文档经常用文件名引用记忆文件。归档前要搜索检查这些引用。
• 不知道子 Agent 搜索过哪些根目录时，不要接受它说“找不到归属位置”。 三个盘点 Agent 都没有被告知私有技能仓库的存在，结果把两个早已有记录的条目标成了“需要迁移”。
• 不要为了废弃单个项目的记忆而全局关闭自动记忆。 全局开关会在不提示的情况下停止加载其他所有项目的记忆；应使用项目的 .claude/settings.local.json。

失败案例（完整复盘）

这些“切勿”背后的原因，以及每次实际出现的问题：references/failure_cases.md。