45.6KB主索引原来
24.4KB系统只装
354 份记忆文件
60KB前言每次注入
这份是活的设计文件。 Jeff 2026-09-02 定:「我要做一个更牛的记忆体,一步一步来」。 每做完一步,把「定了什么原则、改了什么、量到什么数」追加在这里。 只写设计与判据;当时怎么栽的那些故事留在各条记忆的正文里。 网页版 https://hoop-docs.pages.dev/memory(从这份 md 生成,改这份再跑
./tools/deploy_docs.sh)。
0. 现状体检(2026-09-02,全部是机器量的)
| 项 | 量到的 | 判断 |
|---|---|---|
| 记忆文件 | 354 份 / 1.8MB(6 月 15 · 7 月 127 · 8 月 199) | 在真写,曲线健康 |
| 索引一致性 | 0 孤儿 · 0 死链 · 铁律 21 个指针只有 2 个缺文件 | 纪律守住了 |
| 主索引大小 | 45.6KB,系统只装前 ~24.4KB | 🔴 后 80 行三个月没被任何会话读到,含整节「悬着的事」 |
| 前言(每次醒来注入) | 60KB / 649 行;抽 13 条铁律它重述了 11 条;10% 的行带具体日期 | 🔴 事实上的第五层,且和铁律重叠 |
| 每次醒来总读入 | ≈124KB(前言占一半) | 太重 |
| L2 里的 as-built 大文件 | >8KB 的 21 份;hoop-game-platform 23KB 而 docs 里同题 6KB |
🟠 L2 装了 L3 的东西 |
| 前言是否在 git | 不在 | 🟠 60KB 全家共用规则,零历史 |
| 描述 Jeff 本人的记忆 | 0 份(唯一 type:user 是一个暗号) |
🟡 |
根因一句话:写入有纪律,清理没机制。 354 份从没退役过一份;索引超限没人报警;前言只长不砍。 第二个根因:「每次必读」这个身份被三处同时占着(铁律、前言、索引),而设计只给了铁律。
1. 原则(定一条加一条,每条带「为什么」)
原则 ①:索引只放指针,一行不超过一句话;索引大小有闸,超了写不进去
- 为什么:系统对 MEMORY.md 的限额是它定的、改不了的(警告原话
limit: 24.4KB,我们任何文件里都没写过这个数),而且超了是静默截断。写得再好,读不到等于没写。 - 系统的设计预期本来就是「索引一行一个指针,详情在正文」—— 警告原话是
index entries are too long。我们索引里每行塞一段故事,是用歪了。 - 闸:
~/.hoop/memory_guard.py·--hook:挂在~/.claude/settings.json的PreToolUse(Edit / Write / MultiEdit),写入前算出结果大小,超 24,000 字节就 exit 2 拦下,并告诉你该往分索引放 · 无参:检查大小 / 死链 / 孤儿(分索引一起数),任一失败 exit 1 ·--self-test:六条用例故意让它红,证明有牙(铁律 3:检查命令自己也得被检查) - 分索引:
_index-*.md,主索引只留一行指过去;不是每次必读,要用了才翻。 - ⚠️ 09-02 晚补:官方文档说 MEMORY.md 的限是「前 200 行 或 前 25KB,哪个先到算哪个」 —— 第一版闸只装了字节那条。已补行数(190 行拦),自检 7/7。
各层限额(2026-09-02 查官方文档 code.claude.com/docs/en/memory,不是推测)
| 文件 | 限额 | 超了怎样 |
|---|---|---|
| MEMORY.md | 前 200 行 或 前 25KB,哪个先到 | 写入成功,超出部分下次加载直接丢;写后系统会报错要你重写 |
| CLAUDE.md(含 @ 挂载) | 硬限 4 MiB | 超过整份跳过(不是截断) |
| CLAUDE.md 软限 | 建议 <200 行 | 文档原话:越长越占上下文、遵循度越低。我们铁律+目录 ≈ 400 行,已在线外 |
| @ 挂载 | 最深 4 层 | 挂载文件全文进上下文,拆文件不省字 |
| L2 每份记忆正文 | 无 | 开工不读,按需打开 |
| 会话记录 | cleanupPeriodDays 到期自动删 |
memory/ 目录不在清理范围 |
判据:「读不到」和「读了记不牢」是两种病 —— MEMORY.md 的病是前者(静默截断),铁律+目录的病是后者(400 行,遵循度掉)。
2. 步骤日志
第一步(2026-09-02):主索引压回限额 + 装闸
- 拆出三份分索引:
_index-ui.md(14.1KB)·_index-pitfalls.md(4.0KB)·_index-status.md(5.1KB) - 「⏳ 悬着的事」从最底搬到最顶 —— 它以前排最后,所以永远是被截掉的那节
- 主索引 45,592 → 23,821 字节;357 条链接一条没丢(机器比对过);一份记忆都没删
- 闸装好,自检 6/6 绿;真实索引检查绿:0 死链 0 孤儿
- 当晚补:闸加上 200 行那条限(自检 7/7);主索引 108 行,余量 82 行
- ⚠️ 余量只有 179 字节 —— 第一步只是过线,第二步才能给出余量
第二步(待 Jeff 点头):把主索引里括号里的故事砍成一句话
- 「一犯就出事」12.9KB + 「原则」7.4KB,两节里大半字节是括号里的案例复述。案例在正文里都有。
- 预期主索引降到 ~14KB,余量 ~10KB。
- 一份记忆都不删,只改索引那一行的写法。
之后的候选(顺序待定)
- 前言瘦身:只留哨兵特有的操作,和铁律重复的换成「见铁律 N」;放进 git
- L2 里的 as-built 搬去 docs/,记忆留 5 行指路
- 退役机制:记忆加
last-verified,90 天没验的进归档节 - 补一份「Jeff 是谁」的
type:user记忆
3. 全景表:层 × 文件(2026-09-02,Jeff 要的一张表)
| 层 | 文件 | 目的 | 在哪 | 关系(谁索引它 / 它索引谁) | 谁写 | 进 git · 共享 | 什么时候读 | 大小 | 建议 |
|---|---|---|---|---|---|---|---|---|---|
| L1 | CLAUDE.md |
开工第一眼:HOOP 特有的通道/设备/开工三件事 | 仓库根 | 它 @ 挂载铁律和目录 |
人 | ✅ git · 全家全机器 | 每次开工,全文 | 80 行 / 6KB | 压到 40 行:「悬着的事」搬去 L2(它一天变三回,是记忆不是命令) |
| L1 | docs/铁律.md |
29 条一犯就出事的命令 | 仓库 | 被 CLAUDE.md 挂载;每条 ↳ 指向 L2 一份故事(23 个指针) | 人 | ✅ git · 全家全机器 | 每次开工,全文 | 165 行 / 11KB | 留命令删括号案例 → ~110 行;它是唯一的跨机器教训层,前言里的教训该并进来 |
| L1 | docs/00-目录.md |
L3 的缩影:有哪些图纸、何时翻 | 仓库 | 被 CLAUDE.md 挂载;它索引 78 份 docs | 人 | ✅ git · 全家全机器 | 每次开工,全文 | 236 行 / 25KB | 停止 @ 挂载,改成按需翻(按 Jeff 自己的判据「有目录按需翻的不进 L1」);CLAUDE.md 留 5 行指过去 |
| L1(建议新增) | .claude/rules/*.md 带 paths: |
碰到某类文件才弹出的规矩(迁移取号、相机参数别碰、热区认领) | 仓库 .claude/rules/ |
替代目录那 236 行里「动 X 前先看 Y」的那部分 | 人 | ✅ git · 全家 | 只在碰到匹配文件时 | 0 → 每份 <20 行 | 官方现成机制:该知道时才知道,不占开工的行 |
| L2 | MEMORY.md |
354 份记忆的索引,只放指针 | ~/.claude/projects/HOOP/memory/ |
索引 354 份正文 + 3 份分索引;被系统开工加载 | Claude | ❌ 本机 · 本机 13 个分身共用 | 每次开工,前 200 行/25KB | 108 行 / 24KB | 括号故事砍成一句 → ~70 行;「一犯就出事」40 行是铁律复述,改一行指过去;有闸 memory_guard.py |
| L2 | _index-ui/-pitfalls/-status.md |
分索引,主索引装不下的 | 同上 | 被 MEMORY.md 一行链到;各自索引一批正文 | Claude | ❌ 本机 | 要用了才翻 | 3 份 / 23KB | 保持;闸连它们一起查死链孤儿 |
| L2 | 354 份 xxx.md |
教训正文:判据 + Why + How to apply | 同上 | 被主/分索引链到;铁律 ↳ 指向其中 23 份 | Claude | ❌ 本机 | 要用了才翻 | 1.8MB;21 份 >8KB | as-built 那 21 份搬去 L3 留 5 行指路;加 last-verified,90 天没验进归档;补 1 份 type:user「Jeff 是谁」 |
| L3 | docs/*.md ×78 |
设计图纸、as-built、必读手册 | 仓库 docs/ |
被 00-目录 索引;部分被 L2 正文引用 | 人 + Claude | ✅ git · 全家 | 要用了才翻 | 78 份 | 加新图纸必须进目录一行(现有规矩);⚠️ 带 ⚠️ 的 14 份和现实不符,要么改对要么归档 |
| L3 | docs/*.html ×16 + hoop-docs.pages.dev |
能点着看的网页版 | 仓库 + Cloudflare Pages | 从对应 md 生成;tools/docs_index.py 登记 |
生成器 | ✅ git · 线上全家 | 要用了才看 | 16 份 | 保持「HTML 从 md 生成,不手写第二份」 |
| L4 | 会话记录 *.jsonl |
原始对话 | ~/.claude/projects/HOOP/ |
无人索引;L2 是它的出口 | 系统 | ❌ 本机 | 不读,查不到 | 1.1GB | 不动;到期系统自己删(memory/ 不在清理范围) |
| 设计外 | 哨兵前言 tools/hoop-lib/prompts/*.md(09-02 起,不再是脚本里的 PREAMBLE 常量) |
哨兵醒来怎么收发/落卡/出包 + 一堆教训故事 | ~/.hoop/ws_sentinel_generic.py |
无人索引;和铁律重叠 11/13 | 人 | ❌ 不在 git,零历史 · 本机全家 | 哨兵每次醒来,全文 | 649 行 / 60KB | 砍到 ≤150 行只留操作;教训并进铁律;进 git |
读入合计: 开工 481 + 108 = 589 行 → 目标 40 + 110 + 70 = ~220 行;哨兵醒来 1238 行 → ~370 行。
判据只有一条:整份必读的进 L1(命令);有目录、按需翻的进 L2/L3(教训、图纸)。 现在的病是两边串了味:L1 里有目录和悬着的事(按需的东西),L2 索引里有命令(铁律的复述),前言里两样都有。