当 CLAUDE.md 从 30 行慢慢涨到 1000 行时AI 编码助手的行为开始变得奇怪。我让它遵守项目规范它有时会引用三个月前已经废弃的目录我反复强调不要改公共接口它还是在重构时踩了坑。问题不在模型而在于所谓的 memory。CLAUDE.md 本质上是模型的项目记忆入口但一个不会剪枝的文本文件记的东西越多优先级反而越混乱。Knowl 这个项目的核心就是解决这件事构建一套 memory that prunes itself让记忆文件学会自动淘汰过时信息。这篇文章我会按问题、设计、落地、验证和排查的顺序完整讲一遍自剪枝记忆系统的实战思路。1. CLAUDE.md 从 20 行涨到 1000 行不是文档问题是记忆系统问题1.1 模型读到的不是文件是一份上下文约束清单Claude Code、Cursor 这类 AI 编码助手加载 CLAUDE.md 时并不是把它当普通文档浏览而是会把内容注入到每次会话的初始上下文里。模型每开始一个任务都要先“过一遍”这份文件再决定怎么理解项目、怎么组织代码、避开哪些坑。所以 CLAUDE.md 本质上是一份模型工作手册。里面通常写着代码风格、目录结构、禁止事项、常用命令、用户偏好、踩坑记录。文件短的时候模型很容易逐字遵守文件长到 1000 行模型就只能抽样扫描。很多人上网找“好用的 CLAUDE.md”模板拿到手直接抄这不是不行但要注意模板越长规则越容易互相打架。比如同时写着“统一使用 src/components”和“业务逻辑放在 src/common”模型碰到具体需求时就会随机选择表现在代码里就是风格漂移。我在项目里第一次意识这个问题是文件到 600 行左右。那时发现模型开始主动遵守文件前 100 行里的规则但对后面 300 行里的临时约定几乎无感。一开始我以为是自己提示词写得不清楚后来把 CLAUDE.md 里的内容打印出来看才发现不是模型笨而是它根本没有足够的“注意力”把 1000 行规则全部变成行动约束。1.2 1000 行之后会出现的三个典型症状第一个症状是指令稀释。模型对文件开头的规则记得最牢中间和底部的大段说明经常被忽略。尤其当文件里有大量“临时约定”和“过期目录”时真实重要的规则反而被埋没。你会看到模型写出了明显违反核心规范的代码但它并不认为自己在犯错。第二个症状是 token 预算被吃掉。1000 行 Markdown 粗略估计可能消耗 8000 到 10000 个 token这会直接挤占对话历史的空间。原本能完成的长文件修改任务可能做到一半就出现上下文不足输出被截断或者模型开始“忘记”前面修改过哪些地方。第三个症状是维护冲突。只要有过两个人同时往文件里加规则就会出现重复甚至矛盾。比如“使用 src/utils”和“使用 src/common”同时存在模型不知道信谁。你改掉其中一处另一处还留在原处下次对话它又可能读到。这三个症状叠加在一起最典型的体验是模型单看每段代码都没问题但整体项目结构越来越乱且每次对话的表现不稳定。你开始觉得“这个模型怎么越用越笨”其实是记忆系统没有维护好。1.3 手动整理为什么不可持续很多人第一反应是手动把 CLAUDE.md 精简一遍。我也这么干过但效果只能维持一周。手动整理需要把每一条都读一遍判断它是当前约束还是历史遗留还要去 git log 里追是谁写的、为什么写、现在是否还有效。更麻烦的是就算你把文件整理到 200 行下一周它又会涨回去因为团队成员都会往里面加自认为重要的规则。这就是问题的本质AI 助手的记忆不是一次性的文档排版而是需要持续维护的系统。剪枝不能靠“某天大扫除”而要靠一种机制自动识别低价值记忆、归档高频记忆、保持文件体积稳定。手动整理还有另一个隐性成本删掉的东西找不回来。你以为某条过期了结果三个月后模型因为缺少这条规则踩了同样的坑。所以真正靠谱的剪枝必须伴随归档而不是直接删除。2. Knowl 这类自剪枝记忆系统的核心设计不是自动删而是分级2.1 从静态文件到动态记忆库理解 Knowl 这类项目最关键的一点是它没有打算把 CLAUDE.md 变成一份“永不变化的说明书”而是把记忆拆成长期记忆库和工作记忆两部分。工作记忆就是模型当前每次会话都读到的内容也就是精简后的 CLAUDE.md。长期记忆库则包含所有历史条目其中大部分被标记为归档或过期。真正进入工作记忆的只有 active 状态且优先级足够的条目。这就是 agent memory 领域常见的设计思路。人的记忆本来就会遗忘AI 助手也应该有“遗忘”机制。不是把 1000 行砍成 200 行就结束而是让文件体积稳定在模型能高效利用的范围内同时把删掉的内容留在可追溯的归档里。我在实际项目里把这一层想清楚后很多行为就解释通了。以前模型突然不遵守某条规则我会去改提示词。现在我会先看这条规则是否还存在于 active 列表里。如果不存在说明它被剪枝了这时候要去 archive 里查而不是抱怨模型。2.2 一条可剪枝记忆需要哪些元数据要让剪枝系统工作每条记忆不能只是一段 Markdown 文本它必须带有可计算的元数据。字段作用为什么关键id唯一标识方便日志定位、恢复、冲突检测created_at创建时间判断临时约定是否过期last_hit_at最近命中时间判断这条记忆是否真的被使用过priority高 / 中 / 低高优先级不可轻易剪statusactive / archived / expired决定是否进入最终 CLAUDE.mdscope全局 / 模块 / 目录剪枝时按范围批量处理content规则正文最终会被模型读取的内容其中 last_hit_at 最难维护。模型是否真的用到了某条规则外部很难精确判断。早期可以把它当“人工确认时间”比如每次任务结束后维护者发现这条规则确实帮助模型做对了就更新一次。后面可以靠会话日志、检索记录、规则匹配来近似更新。没有命中数据的剪枝本质上是在猜。猜也不是完全不行但至少要有 created_at 和 priority 兜底否则很容易把刚加入的新规则和长期未使用的中低优先级规则混在一起处理。2.3 剪枝策略时效性、命中率、冲突优先级一套合理的剪枝策略至少包含三层判断。第一层是时效性。带“临时”标记的约定超过设定天数后自动过期。比如“本迭代自动生成的接口文件放在 temp_api 目录”“测试环境域名下周三前切换”这类内容过了时间点就没有保留价值直接进入 expired。第二层是命中率。设定一个时间窗口比如 30 天。在这个窗口内没有被日志命中、没有被人为刷新的中低优先级条目自动降级为 archive。这是最常用的冷数据淘汰逻辑类似缓存里的 LRU 思路。第三层是冲突检测。新增规则与旧规则主题相似或直接冲突时不能两个都保留。应该把旧规则标记为 superseded或者由高优先级规则覆盖低优先级规则。没有冲突检测的剪枝系统只做“删冷门”是不够的因为两个互相矛盾的规则可以同时保持活跃模型读到就会困惑。另外一定要设置“永不剪枝”的保护清单。项目红线、安全规范、用户强偏好这些必须标记为 never_prune并且优先级为 high。不能因为某条规则一个月没被命中就把它归档否则剪枝系统会亲手毁掉最重要的约束。3. 落地一套可用的自剪枝记忆流程我的做法3.1 先把现有 CLAUDE.md 拆成结构化条目不要直接写一个剪枝脚本去扫 1000 行 Markdown那样太难了。正确做法是先做一次结构化拆分。我的拆分步骤是把原文件备份为 CLAUDE.md.bak。按语义分块项目架构、代码风格、禁止事项、常用命令、临时约定。每个分块变成记忆库里的一个条目。给每个条目加上 YAML 元数据头。单独保留一份手工维护的 CLAUDE.core.md里面只放永远不能剪的规则。一个条目的样子大致如下- id: 001 title: 前端目录约定 status: active priority: high created_at: 2025-01-06 last_hit_at: 2025-06-12 content: | src/components 存放通用组件 src/views 存放页面 src/services 存放接口请求这一步做完CLAUDE.md 就不再是手写文档而是可以交给程序处理的元数据集合。后续所有剪枝和生成逻辑都基于这些条目。3.2 让新增记忆走统一入口拆分完成后最重要的一条铁律是禁止直接手改 CLAUDE.md。所有新增记忆必须走统一入口。我的做法是维护一个 memories 目录新增记忆就是往目录里增加一个带元数据的 YAML 文件。然后由 build 脚本把所有 active 条目拼成最终生成的 CLAUDE.md。这样做有几个直接好处新增内容不会破坏现有结构。程序可以读取元数据判断哪条该进、哪条该出。原始历史留存在 memories 目录不会因为生成覆盖而丢失。CLAUDE.md 变成编译产物而不是源文件。给一个简单的 Python 构建示意实际使用时按项目环境调整# build_claude_md.py示例不是可直接运行的完整方案 import glob import yaml entries [] for path in glob.glob(memories/*.yaml): with open(path, encodingutf-8) as fp: entry yaml.safe_load(fp) if entry.get(status) active: entries.append(entry) # 高优先级在前其他条目按最后命中时间排序 entries.sort(keylambda x: ( 0 if x.get(priority) high else 1, x.get(last_hit_at, ), )) with open(CLAUDE.md, w, encodingutf-8) as fp: for entry in entries: fp.write(f## {entry[title]}\n) fp.write(entry[content].strip() \n\n)这段代码的关键点有两个过滤 status 是 active 的条目按优先级和命中时间排序。如果读者有自己的环境可以增加更多字段比如按模块拆分、按标签过滤。3.3 配置剪枝参数当记忆库条目越来越多就需要配置剪枝规则。我习惯把配置单独放一个 YAML 文件max_active_entries: 50 hit_window_days: 30 temp_expire_days: 7 never_prune_priority: high archive_dir: memories/archive逐个解释max_active_entriesactive 条目上限超过后触发降权。hit_window_days最近多少天内被命中算有效。temp_expire_days临时约定多少天后过期。never_prune_priority标记为 high 优先级的条目不可剪枝。archive_dir归档目录剪掉的内容统一放这里。不要以为配置越严格越好。小项目可以把 hit_window_days 设成 60因为规则本来就不常变迭代很快的项目可以设成 14避免旧的临时约定滞留太久。参数要根据项目节奏调整。我遇到过 build 脚本把 2000 多个 YAML 文件一次性全读进内存内存占用冲到几百 MB。后来用 memory analyzer tool 检查发现是重复加载了同一个目录列表。改成遍历一次、边读边过滤后内存占用就降下来了。所以看到脚本 out of memory 时不要只加内存先看代码里是不是把所有数据都堆到了一个列表里。3.4 接入 AI 编码助手的常见方式最简单的接入方式是把生成的 CLAUDE.md 放回项目根目录。大多数 AI 编码工具默认会读取项目根目录下的 CLAUDE.md所以不需要额外配置。如果你的工具支持自定义记忆文件路径也可以把生成文件命名为 CLAUDE.generated.md然后在配置里引用。但要注意有些工具只识别固定文件名自定义路径可能不生效。接入后建议把 active 条目控制在 300 行以内。如果生成结果超过 500 行说明剪枝阈值太宽需要重新检查 max_active_entries 和 hit_window_days。模型每次新会话都会读一遍这份文件文件越精简剩余上下文就越多处理复杂任务时越不容易截断。在 WSL 或容器环境里跑脚本时注意文件权限和 WSL 的内存限制。生成的 CLAUDE.md 建议统一使用 UTF-8 without BOM 编码某些工具遇到 BOM 会解析异常。3.5 定任务和触发频率剪枝不要实时跑也不要在模型每次调用时都重建文件。最稳定的做法是每次会话结束后运行一次 build或者设一个每日定时任务。示例 crontab0 2 * * * cd /path/to/project /usr/bin/python3 build_claude_md.py --prune如果项目用 git也可以加一个 pre-commit 钩子确保提交的 CLAUDE.md 是最新生成的。但要注意钩子会让每次提交变慢项目很大时更适合用定时任务而不是提交时构建。我目前的做法是双轨白天开发时手动执行 build 脚本夜间定时任务自动剪枝并归档。剪枝日志单独写到一个文件里哪条被归档、为什么归档都有记录。4. 验证剪枝是否有效不能只看文件行数4.1 先定义“有效”很多人看到文件从 1000 行降到 200 行就认为剪枝成功了。这个判断太早。真正要看的指标有四个关键规则命中率模型是否准确遵守了 high 优先级规则。错误复现率过去踩过的坑是否又因为记忆缺失重新出现。上下文占用CLAUDE.md 变小后长任务是否更少被截断。迭代轮数同一个需求从开始到产出可用代码的对话轮数有没有下降。我见过一种情况剪枝后文件确实变小了但模型开始频繁违反项目红线。原因是一条安全规范被当成“30 天未命中”归档了。这就是指标定义出了问题——只看体积不看规则命中等于白做。4.2 用同一任务做对比测试验证剪枝最可靠的方式是准备三个版本A原始 1000 行 CLAUDE.md。B人工精简版。CKnowl 式自动剪枝系统生成的 active 文件。然后让模型分别完成三类任务新增一个接口、重构一个模块、修复一个已知 bug。记录以下内容验证项A 原始版B 人工版C 自动剪枝版是否遵循目录结构部分是是是否触犯禁止事项是否否3 轮内完成否是是上下文是否截断是否否如果 C 和 B 表现接近但都明显好于 A说明自动剪枝能替代人工整理的大部分工作。如果 C 比 B 差不要直接否定思路优先检查剪枝配置是不是把高优先级规则误判了是不是 hit_window_days 设置太短。4.3 让失败反馈回剪枝闭环验证过程中一定会遇到模型违反旧规则的情况。这时候不要只怪模型而是回到记忆系统里查原因。排查顺序是这条规则是否还存在于 active 列表里如果不存在它被剪枝了还是 build 脚本漏了如果存在但模型没遵守它是不是排在文件太靠后的位置它是否和某条更高优先级的规则冲突找到原因后更新元数据即可。比如某条规则其实是项目红线但之前 priority 被标成 medium导致被剪枝那就改成 high并加上 never_prune。这就是让自剪枝系统越来越准的过程每一次失败都要反馈回元数据和剪枝策略。5. 常见问题与排查思路5.1 重要规范被剪掉了表现模型开始犯低级错误比如不遵守目录约定或者使用已经废弃的接口。排查顺序打开 archive 目录按时间倒序看最近归档的条目。看剪枝日志里该条目的 last_hit_at 和 priority。如果 last_hit_at 一直没更新说明“命中”统计失效需要改进统计方式。如果优先级是中或低且 30 天没命中归档是正常行为。问题不是剪枝本身而是这条规则没有被标记为高优先级。这类问题最常见的坑是“命中日志”没有真正接上。你以为模型用了这条规则但系统里没有任何记录于是它被当成冷数据淘汰。解决方法是让人工确认也写入命中日志至少在早期阶段。5.2 文件还是越来越大表现active 文件没有缩小甚至超过原来的 1000 行。常见原因有四种新增记忆没有走统一入口而是直接手改 CLAUDE.mdbuild 时被覆盖或当作冲突。high 优先级条目太多几乎全部进入 active剪枝不起作用。定时任务没有执行脚本从未运行。没有元数据的纯文本漏在系统之外无法被统计。排查时先看 build 脚本日志扫描到多少条目过滤后多少 active输出文件多大。如果扫描数量很多但 active 很少说明过滤逻辑正常问题在新增入口如果 high 优先级超过总数的一半先调整优先级标注再谈剪枝。5.3 脚本本身的资源和权限问题如果 build 脚本或者剪枝脚本报 out of memory甚至出现 memory access violation不要先怀疑系统内存不够。先用 memory analyzer tool 做一次对象分配检查重点看是不是重复读文件、一次性构建了超大列表、或者在循环里递归加载目录。我用 Python 时最容易犯的错是把整个 memories 目录一次性 glob 到内存然后循环里又反复 yaml.safe_load 同一个文件。后来改成先列出路径再逐个流式读取内存就稳了。如果在 WSL 环境里跑还要检查 WSL 的内存限制配置。不是说把所有内存都给 VM 就好而是脚本本身要按行处理避免整文件载入。文件权限问题也常见生成目录没有写权限脚本会静默失败表现为“好像没跑过”。5.4 没有代码环境时的轻量替代方案如果你不想写脚本也不想维护 YAML还有一个手工版方案为 CLAUDE.md 建一张记忆审查表。每个 section 记三列最近 30 天是否被参考过。是否与当前代码结构一致。是否被更新的规则覆盖。每周花 10 分钟过一遍把三个回答都为“否”的 section 移入 archive。另外保留一个 NEVER_PRUNED.md放真正的项目红线和安全规范。这个方法不需要任何代码但核心思路和自动剪枝一致剪枝不是删除历史而是把低价值内容从工作记忆里移走。6. 什么情况下值得上自剪枝记忆系统6.1 可以上自动剪枝的信号至少要满足下面两条才值得引入自动剪枝项目持续开发 3 个月以上。CLAUDE.md 已经超过 500 行。项目有两人以上在维护大家都会往里面加规则。模型已经出现“不遵守近期规则”的明显表现。每次开始任务前都要手动清理记忆文件。如果这些条件只满足一条先用最简单的方式手动整理不要把系统做得太重。6.2 不建议上自动剪枝的场景一次性 Demo、十几行规则的小项目、已经进入冻结期的稳定项目都不需要自剪枝记忆系统。在这些场景里引入 build 脚本、元数据、归档目录本身就是一种维护负担。你每天花在维护记忆系统上的时间可能比模型因为记忆混乱浪费的时间还多。另外如果项目只有你一个人在维护且 CLAUDE.md 稳定在 100 行以下手工修改仍然是最快的方案。自动剪枝的价值要在“手工维护成本已经明显过高”时才体现出来。6.3 我的最小化起步建议不要第一天就上完整版自动剪枝。我建议先做三分之一的工作把 CLAUDE.md 拆成 CLAUDE.core.md 和 memories 目录。只写一个 build 脚本把所有 active 条目拼成 CLAUDE.md。暂时不写自动剪枝逻辑用人工维护 last_hit_at。跑两周观察效果。两周后如果模型表现有改善再补自动剪枝和定时任务。如果两周内 build 脚本本身带来的麻烦大于收益就回到手写模式等文件再次膨胀时重新考虑。我现在的项目里根目录始终只有一份约 180 行的 CLAUDE.md里面放的是模型每次工作都必须遵守的核心约束。真正被剪掉的历史全在 archive 目录里遇到问题时还能翻出来。这个模式跑了一段时间后我才慢慢理解 Knowl 做 memory that prunes itself 的初衷AI 助手需要的不是一份越长越好的说明书而是一套能自动淘汰过期信息、保留关键约束的记忆系统。你不需要一开始就上工具但一定要先接受这个观点CLAUDE.md 是活文档不是石碑。