# 设计说明

## 它解决什么问题

不是「记不住」，而是**记得太多太长、没人愿意读**。

几乎所有 agent 记忆方案都在解决「怎么记得更多、取得更准」。记忆册反过来，只解决一件事：**让这份记忆短到有人愿意读**。一条记忆就是一句话，整本读一遍不超过两分钟。

## 与别的记忆方案的分工

记忆册只承担**长期、宏观**那一层：主人是谁、我是谁、在做什么、定过什么大方向决策。

技术实现细节、踩坑与排查、操作方法、调试过程、进度流水 —— 这些**一律不进记忆册**，由别的记忆系统（短期的、过程性的那一层）负责。

这条边界是刻意划的。混在一起时，一张「关于主人」的卡片会被二十条技术细节淹没，最后谁也不看。

## 三个关键决定

### 一、编辑，而不是记录员

早期版本是「发现新的就往后追加一条」。结果是只增不减，时间一长必然要靠人肉清理。

现在每轮改写都是**通读全文、交出改好的完整版本**：该合并的合并、该改写的改写、该删的删、该加的加。文档长度由**内容**决定，不由**历史**决定。

代价是每轮都要输出整本记忆册（token 成本更高），换来的是一份不会腐烂的文档。

### 二、分类按主题，不按信息类型

曾经按「决策 / 偏好 / 正在做的事」这类**信息类型**分顶层。结果同一个项目的信息被切成三份散在三个抽屉里——想了解一个项目得翻三处。

现在顶层按**主题**分（主人 / 我 / 在做的事），一个项目的一切都收在它自己的 `##` 小节里。判断标准只有一条：**找东西时会先想「这是哪个主题」，而不是「这算什么性质」**。

### 三、分类和小节都由模型自由增删

分类不写死在代码里——目录里有哪些 `.md`，就有哪些分类。模型觉得该给某个项目单开一节就开，觉得没用了就删掉。

代码只提供**起步用的默认分类**和**顺序提示文件**（`.order`）。

## 容量触发整理

光靠「每轮改写」不够：它只会小修小补，条数照样往上涨。所以加了两道阈值：

| 阈值 | 默认 | 触发条件 |
|---|---|---|
| `pageEntryLimit` | 12 | 单个分类超过这么多条 |
| `bookEntryLimit` | 40 | 整本超过这么多条 |

踩线就把一条**强制整理令**追加进 prompt，写明现在多少条、哪几类超了，并要求合并、缩略、用小节拆类，最后回落到上限以内。没踩线时不加这段，改写保持轻量。

## 三道防呆

1. **解析不出分类** → 什么都不写。宁可这次不改，也不写垃圾。
2. **条目骤减一半以上**（原本 ≥6 条时）→ 拒绝这次改写、保留原样，防止模型「重写」成半本。
3. **按会话存游标、失败不推进** → 同一段不会被反复改写，失败的下次会重试。

## 为什么没有构建步骤

浏览器半是手写的 `window.__ModuleLoader__.load({id, factory})` bundle，没有 JSX、没有打包器。

理由：安装路径上任何一环需要构建，都会让「装上去就能跑」变成「先配好工具链」。这个插件的界面很小，手写 `h()` 调用完全可控。