Symptom 1重复踩坑
「httpx 不能升级」这种事，不写下来就每次都得重新炸一次才想起来。
把踩过的坑
变成全队的开局
AI 会话天生失忆。我们用一套三层渐进索引，把 6 个人踩出来的 859 条经验压成 5.7KB 的入口，让每个人每次开工都自动带着全队的记忆。
// 数据实测于 2026-07-29 · docs/claude-memory/ 口径
859 条记忆
3 层索引 · 24 组
3.2 MB 末端
5.7 KB 入口
6 人共写
0 死链 / 0 孤儿
9 个待补的洞
SCROLL / 向下滚动
01
The Problem
失忆的不是模型，是团队
每开一个新会话，AI 的上下文都是空的。昨天讲清楚的口径、上周踩平的坑、上个月定死的约定，如果只留在某一次对话里，下一次就得从头再来一遍。
Failure Mode
更贵的是乘以人数：6 个人各开各的会话，同一个坑要踩 6 遍，同一个口径要问 6 次。知识不是没产生，是产生了却留不下、留下了却传不开。
Symptom 2口径漂移
同一个指标，这个会话算 A、那个会话算 B。等到对不上账时已经晚了。
Symptom 3信息孤岛
只有当事人知道为什么这么做，人一忙、一换，理由就没了。
Goal
把「个人的一次性经验」转成全队每次开工就自动带着的上下文——不靠记性，不靠问人，靠可检索、可继承、可审计的文件。
02
Progressive Disclosure
三层索引 · 按需展开
全部塞进上下文是不可能的——3.2MB 会把窗口撑爆。所以做成三层漏斗：只有最顶层自动加载，往下每一层都是看到触发词才展开。
Layer 1◈ 自动加载
MEMORY.md
5,692 B · 82 行
唯一每次会话自动进上下文的文件。只写协议 + 分组指针，不写任何细节。相当于一本书的目录页。
纪律线 8KB / 120 行 · 现 69%
Layer 2◈ 按触发词展开
24 个 sidecar
_index_<topic>.md
按主题分组的二级索引，每个开头有触发关键词段。聊到抖音抓取才读抓取那本，不相干的一律不碰。
警告 16KB / 硬闸 24KB
Layer 3◈ 末端知识
859 个末端文件
feedback_ / project_ / reference_
一个文件一件事，平均 3.9KB，其中 295 个还不到 2KB。真正的知识在这层，只在明确需要时才整篇读。
合计 3.2 MB · 每条尾标 (N行)
0
末端记忆文件
0
主题 sidecar 索引
0:1
压缩比：3.2MB 知识 → 5.7KB 入口
0
死链 / 孤儿（体检实测）
Key Idea
省的不是磁盘，是上下文窗口。第一层永远只花 5.7KB，剩下 3.2MB 全部按需付费——这就是整套设计能长到 859 条还不塌的根因。
03
Lifecycle
一条记忆的一生
从「刚踩完一个坑」到「队友明早开机自动读到」，中间有 7 个动作。前 5 步是写的人的纪律，后 2 步是机器兜底。
人 · 写前
先 grep 再动笔。
grep -irl <主题> docs/claude-memory/ 命中就改现有那条，不新开文件——这是防重复、防打架的第一道。
人 · 命名
三选一前缀。
feedback_（教训与行为准则）／project_（项目上下文）／reference_（外部资源指针）。前缀决定它归哪个 sidecar。
写入
一个文件一件事。平均 3.9KB。feedback 类必须带「为什么」和「怎么用」——只写结论不写理由的记忆，三个月后没人敢信。
挂索引
在对应 sidecar 加一行指针，尾部标
(N行) 让下次读的人能预估成本。不挂索引＝孤儿，永远不会被读到。
互链
用
[[name]] 连到相关记忆。允许链到还不存在的名字——那是在标记「这里以后该补一条」。
机器 · 门禁
pre-commit 自动拦。MEMORY.md 超 8KB／120 行／单行 240 字节，或任何 sidecar 链接指向不存在的文件——直接拒绝提交。
机器 · 分发
git push 即广播。
docs/claude-memory/ 是 git tracked 的，队友 pull 下来就通过 symlink 自动进他们的会话上下文。
分发机制：每台机器把 ~/.claude/projects/-Users-<user>-Akke/memory 软链到仓库里的 docs/claude-memory/ —— 一次性配置，此后记忆跟着代码走，不需要额外同步动作。
04
Taxonomy
三类记忆 · 实际长成什么样
前缀不只是命名习惯，它决定这条记忆什么时候会被想起来。实测分布高度偏向教训类——这既是好事，也埋着一个结构性的洞（见 07 节）。
feedback_踩过的坑与定下的规矩
「httpx 不能升级」「DM 返回 200 不等于送达」「persona 改名必须同步改泄漏正则」。必须写清 为什么 和 怎么用。
占比最高 · 672 条
project_系统现在长什么样
多租户改造、企微通道、云电脑派单链路这类正在进行的工作与约束，相对日期一律转成绝对日期。
123 条 · 偏薄
reference_外部资源指针
Lark Tasklist GUID、Supabase 管理 API、代理池矩阵这类查得到就行的东西，不复制内容只留指针。
64 条 · 最省
Rule
三条硬纪律：写前必 grep（防重复）、单会话最多新建 2 个文件（防灌水）、TODO 不进 memory（走 Lark Task，防过期内容常驻）。
05
Guardrails
四道自动闸 · 不靠自觉
纪律写在文档里等于没写。真正撑住这套体系的是四个会自己动的东西——两个拦在提交前，两个盯在会话边界。
Gate 1 · pre-commitcheck-memory-size.sh
提交时自动跑。MEMORY.md 超 8KB / 120 行 / 单行 240 字节 就拒绝；任何 sidecar 超 24KB 硬闸、超 16KB 警告；顺带校验每个索引链接的目标文件真实存在。逼细节往下沉，不让顶层膨胀。
husky · pnpm install 自动装
Gate 2 · 体检memory-audit.sh
一键跑 7 项：顶层体量、sidecar 体量、死链、孤儿、(N行) 标注覆盖率、触发词段完整性、末端文件过肥告警。当前结果：0 死链 0 孤儿，标注覆盖 863/887。
月度 or 觉察失衡时跑
Gate 3 · 会话启动未提交提醒
SessionStart hook 检查 docs/claude-memory/ 有没有本地未提交变更，有就在开场横幅提示「push 后队友才能看到」。防止写了却烂在自己机器上。
提醒级 · 不阻断
Gate 4 · 并发隔离worktree 自动躲开
同目录开第 2 个会话会共用 git index 和 HEAD，实测出过「改到一半的文件被别的会话 commit 走」。现在 hook 检测到就自动把新会话隔离进独立 worktree，第一个不动。
WorktreeCreate hook · ~7s
Design
四道闸只有 Gate 1 是硬拦截，其余是提醒和隔离。这是刻意的——记忆系统宁可多收一条噪音，也不能因为门槛太高让人干脆不写。
06
Collaboration
六个人，一个共脑
这套系统真正的价值不在「AI 记住了」，而在六个人写进去的东西，另外五个人不用问就能读到。贡献分布相当均匀——说明它不是某一个人的私人笔记本。
按 git 提交触及 memory 文件的次数统计（全历史）。近 30 天仍有 5 人在写——说明这是活的，不是建完就没人碰的档案馆。
0
共写成员
~0
月均新增记忆条数
0
近 30 天被更新过的条目
0%
带 [[互链]] 的文件占比
How
分发全靠 git：memory 就在仓库里，跟着代码一起 review、一起 push、一起回滚。没有第二套同步系统，也就没有第二个会失效的地方。
07
Gap Analysis · Evidence-backed
还缺什么 · 9 个洞
以下每一条都跑过命令核实，不是感觉。按「现在就在伤人 / 正在变差 / 结构性欠账」分三档。
P0 · 现在就在伤人
今天开这个会话时当场撞上了其中两条——本地那份没提交的记忆和队友已推的同名文件冲突，git pull 直接中止，整个仓库同步卡住。
P0 · 01只进不出，零归档
证据：_archive/ 2026-07-22 建好至今，里面只有一个 README，859 条没归档过一条；全目录 last-audited 标记 0 命中，无从判断上次清理是何时。
后果：过期口径和现行口径并排躺着，读到哪条算哪条。
规则写了，但从没执行过
P0 · 02同名撞车无防护
证据：本次会话开场实测——本地未提交的 feedback_wuying_wecom_stop_requires_disable.md 与队友已 push 的同名文件冲突，merge 中止。
后果：两人给同一件事写记忆，文件名一撞就卡住整仓同步，还得手工拆。
写前 grep 只防自己，防不了别人
P0 · 03写完不 push 等于没写
证据：SessionStart 只提醒有未提交变更，不阻断、不自动推；会话结束时也没有二次兜底。
后果：知识产生了却停在个人机器上，队友读不到——本次开场那条横幅就是活例。
提醒 ≠ 保证
P1 · 正在变差
系统还能跑，但检索成本在涨——再放任下去，「按需展开」省下的那点上下文，会被少数几个巨型文件一口吃掉。
P1 · 04末端文件肥大
证据：10 个超 24KB，其中 4 个超 48KB；最大的 project_akke_potential_touch_route_b.md 达 81KB，一次读进来就是两万 token 级的开销。
违反「一个文件一件事」
P1 · 05索引密度失衡
证据：_index_douyin_scraping 挂 80 条、_index_feedback_llm 挂 77 条；另一头 _index_dashboards 只有 5 条、_index_wuying_yunshouji 只有 4 条。
第二跳从「扫一眼」变「翻一屏」
P1 · 06互链率只有一半
证据：859 个文件里只有 456 个带 [[互链]]（53%），其余只能靠索引单向找到。
横向关联断裂时，读到 A 不会想起相关的 B。
孤岛不算孤儿，但一样串不起来
P2 · 结构性欠账
不紧急，但决定这套系统能不能给新人用，以及知识是不是只存在一个地方。
P2 · 07教训厚，画像薄
证据：feedback 占 78%（672 条），project 只占 14%（123 条）。
「别踩这个坑」很足，「系统现在长什么样」偏薄——新人 onboarding 主要还得啃 CLAUDE.md 一个文件。
P2 · 08知识散在 memory 之外
证据：另有 runbooks 48、requirements 47、specs 42、skills 23 份，而 MEMORY.md 里提到它们的次数是 0。
想查「怎么跑扩源」，不知道该翻记忆还是翻 runbook。
P2 · 09双记忆库切换靠自觉
证据：项目本地 859 条之外，还有跨项目全局库 485 条，规定要「手动 Read」，而 MEMORY.md 里没有任何指针指向它。
等于那 485 条默认不可见，想不起来就用不上。
08
Action Plan
补洞清单 · 按性价比排
前三条是一次性做完就长期生效的（改机制，不靠人记）；后面几条是清理和补录，可以摊进月度维护。
| 动作 | 怎么做 | 解决 |
|---|---|---|
| 写入前查重 hook | PreToolUse 拦截写入 docs/claude-memory/，自动跑同名与近似名检查，撞名直接报出已有文件路径 | P0-02 |
| 会话收尾自动推 | SessionEnd hook：memory 有未提交变更就自动 commit + push（或硬提示），把「提醒级」升到「保证级」 | P0-03 |
| 月度归档跑起来 | 挂云端 Routines 定时任务：跑 stale audit → 过期条目 mv 进 _archive/ → 给每个 sidecar 盖 last-audited | P0-01 |
| 拆 4 个巨型文件 | >48KB 的按子主题拆开，剪掉已被推翻的历史段落；route_b（81KB）优先 | P1-04 |
| 拆 2 个超载索引 | douyin_scraping（80 条）、feedback_llm（77 条）按咨询场景二分；顺手把 4~5 条的小 sidecar 并回相邻主题 | P1-05 |
| MEMORY.md 加两段指针 | 顶层补「其他知识载体」（runbooks / requirements / skills 入口）与「全局跨项目库」两个指针段，各占 2~3 行 | P2-08 / 09 |
| 补 project_ 类画像 | 按当前架构补几条「系统现在长什么样」，让新人不必只啃 CLAUDE.md | P2-07 |
| 互链补录 | 归档跑批时顺带给无 [[]] 的文件补关联，目标从 53% 提到 75%+ | P1-06 |
一句话总括：这套记忆系统的骨架是健康的——三层渐进索引把 3.2MB 压成 5.7KB 入口，0 死链 0 孤儿，6 个人在持续共写。真正的欠账只有一个词：只进不出。补上「自动归档 + 撞名预检 + 收尾必推」这三个闭环，它就能从「越长越重」变成能自我代谢的团队共脑。