Memory Lint

Memory Lint — 全面 memory 重构战役

把 2026-05-22 chris × jarvis 一整天的 memory 优化战役 codify 成可重复流程。 本 skill 是"大手术"级别，触发时用户已经接受要做深度重构。日常健康检查走 memory-gc skill。

何时触发

• 用户主动说「memory lint」「记忆大扫除」「memory 大整理」「memory 重构」
• bot 自查发现 MEMORY.md 字符数 > 23.5K（这是真正先到顶的那条线，见下） 或 sub-file 数 > 100
• 一次 memory 累积大量新内容后想做集中整理

不该触发：日常 audit（用 memory-gc）/ 单条 sub-file 改动 / 用户只是改一个文件。

核心 invariants（违反任何一条都会失败）

参见 references/invariants.md — 5 条不变量是这次战役血泪沉淀，每个 Phase 都要 cross-check。简版：

1. 索引可压，sub-file 内文必保留全部原始数据点（5.5 GB/s vs 184x 教训）
2. 死链 > 孤儿（死链主动误导，孤儿只是隐形）
3. cold ≠ garbage（pressure-driven 不是 time-driven）
4. 文件数 -25% 但工具调用 -80%（结构杠杆，优先合并主题集中的）
5. 两条上限，字符那条先到 —— 别只盯行数
   • 字符 24.4K（CC CLI 按字符截断，超出部分静默丢弃）← 真正的约束
   • 行数 200（CC CLI 只 load 前 200 行） 2026-08-10 实测：整理后 176 行 / 23.4K 字符 —— 行数余量 12%，字符余量只有 4%。 按日常写入速度，字符大概 3-5 条新条目就顶到，行数还早得很。 所以「> 195 行」这个旧触发条件在字符先到顶的情况下永远不会先触发 —— 等它响的时候，尾部内容早就被静默截掉了。

完整流程（6 phases）

Phase 1 — 健康审计 + 现状摸底

# 1.1 跑现有 audit (P3 已 patch，含 shared 死链 + archive 识别)
python3 ~/CloseCrab/scripts/memory-audit.py --json

# 1.2 集群发现 (按主题前缀分组)
bash ~/CloseCrab/skills/memory-lint/scripts/cluster-scan.sh

# 1.3 完整 health 报告
bash ~/CloseCrab/skills/memory-lint/scripts/full-health.sh

输出汇总给用户：

• MEMORY.md 行数 / sub-file 数 / orphans / dead links / shared dead links / duplicates
• 主题集群分布（哪些主题 sub-file ≥3，建议合并）
• 估算合并后压缩比

Phase 2 — 集群合并设计（必须用户确认才执行）

cluster-scan.sh 只做前缀匹配，会误聚跨主题文件（如 use-jina-not-tavily / use-coding-mcp-directly / use-monitor-not-agent 前缀都是 use 但主题完全不同）。必须 LLM judgment 二次过滤。

按主题集群提议合并方案：

合并方案模板必须含 4 个字段：

• Cluster name: 主题
• Members: sub-file list + 行数
• Merge to: new cluster file name
• Non-merge explanation (必填)：解释为啥不把这些文件合到别的现有 cluster，或者为啥这个集群可以独立成型。即使决定合并也要写"为什么是这几个文件而不是 N+1 个"

合并方案模板（给用户拍板）：

Cluster: <主题>
成员: <sub-file list, 行数>
合并后: <new cluster file name>
预估净减: -N sub-file
预估行数: <total>
内容组织: <section A / B / C / ...>

Phase 3 — Batch 合并执行

每 cluster 4 步（可参考 references/batch-templates.md）：

1. Read 所有 sub-file：for f in $cluster_files; do echo "═══ $f ═══"; cat "$f"; done
2. Write cluster file：按主题分 sections，完整复制 sub-file 内容（不要 paraphrase，遵守 invariant #1）
3. Edit MEMORY.md：原 N 行 sub-file link 改成 1 行 cluster index
4. Delete 原 sub-file：rm feedback_<old>_*.md

陷阱：

• Write 覆盖已存在文件前必须先 Read（CC tool 状态要求）
• 否则 Edit 改不动，内容会丢失（这次战役 talkshow + cert-expiry 都踩过）

Phase 4 — 孤儿处理

12 个孤儿（disk 有但 MEMORY 没 link）分流：

绝对不能：批量 mtime 删（cold ≠ garbage）。

Phase 5 — 测试（小爱回归验证）

派题给同机 bot（小爱/bunny/tiemu）：

第一轮（每 cluster 1 题）：

• Q: 用 cluster 内典型场景问题
• 验证: (a) MEMORY 索引能引导找到 cluster file (b) sub-file 内容齐全
• PASS 标准: bot 用 1 次 Read 直接找到答案 + 答案含 cluster file 里的 cite 细节

第二轮（诊断题）：

• 孤儿测试: 问内容在孤儿 sub-file 里的问题 → 看 bot 能否找到引导
• shared 死链测试: 问内容在 shared/X.md 的问题 → 看死链是否被修复
• 已合并 control 测试: 问已合到 cluster 的问题（应 PASS）
• 老古董测试: 完全没记录的问题（应 fallback 凭脑子或 grep）

诊断报告必须包含：

• 每题 bot 实际 Read 了哪些文件
• 每题答案细节是否准确
• bot 的 self-eval（找索引顺畅吗、信息丢吗）

Phase 6 — 备份 + 验证

# 1. 跑 sync-memory.sh --push（P4 已加 pre-push lint + shared sync）
bash ~/.claude/scripts/sync-memory.sh --push

# 2. 看输出最后一行确认:
#    "Audit: 🟢 健康 (no actionable issues)"
#    "Pushed to GitHub (private)" 或 "No changes to commit"

# 3. 验证 push 状态
cd ~/my-private && git log -1 --oneline -- claude-code/memory/

完整流程脚本（一键跑）

bash ~/CloseCrab/skills/memory-lint/scripts/full-lint.sh

只跑 Phase 1（不动 disk）+ 给出合并方案让用户拍板。Phase 2-6 必须手动按用户确认逐步执行（涉及删除 sub-file，不能自动批量）。

历史战役参考

完整 2026-05-22 战役过程在 git history：

• CloseCrab commits: 222a171 (audit shared dead) + 878117a (dup 降级)
• my-private memory commits 从 5fbdc29 (8:35) 到最后

战役成果：

• 141 sub-file → 76（-46%）
• MEMORY.md 200 → 164（留 36 行 buffer）
• 0 死链 / 0 孤儿
• 8 个 cluster 形成（openclaw/kilo/gbrain/wiki/bot-ops/botcore-api/memory-system/tpu-training）
• 小爱测试 7/7 + 4/4 全 PASS

Skill 互补关系