# AL Memory（初级实验版）

给 AI 助手（下称 AL）一套本地长期记忆，让它靠自己的记忆管理自己的人生。

## 目的

- **AL 自己管自己的经历。** 和用户做过什么、为什么这样决定、错在哪、后来怎么改，由 AL 自己读原文、自己提炼、自己写成剧情，并在以后修订。引擎只负责保存、关联、检索和核验原文，不替 AL 判断什么有意义。
- **本地多样性。** 同一套引擎，不同的 AL 因为各自的经历和理解，长成不同的工作方式和专长。
- **未来：一个窗口里 AL 自己分类管理项目。** AL 从经历中识别项目、维护各项目的剧情主干、切换时只带眼前需要的记忆。这是方向，本版还没做到。

整理和使用记忆要消耗模型 Token。装上程序不等于自动有记忆，也不代表免费；按需增量整理，别反复重写全部历史。"人生"指持续、可追溯的经历记录，不是对意识的断言。

## 它做什么

1. 跨窗口、跨对话，记忆都在。
2. 每条记忆指回当时对话的原文位置，打开时用哈希核验：翻到的和保存时一字不差，但不证明内容本身对。
3. 记忆分四层，从粗到细。

| 层 | 是什么 |
|---|---|
| RAW 原文 | 一轮对话的坐标、哈希、摘录，不复制全文 |
| CKP 片段 | 一件小事：事实、原话、AL 的回答和想法、以后为什么翻它 |
| DAILY 日卡 | 一天的片段按时间串起来 |
| STORY 故事 | 一件事的来龙去脉，跨天跨月，持续追加 |

故事挂日卡，日卡挂片段，片段挂原文。

## 记忆怎样工作

**AL 带着当前问题找记忆，像查资料一样先找目录、再读剧情，需要核实才翻原文；做完事情，再把新的经历和理解写回去。** 引擎提供工具，这个循环由 AL 主动完成，不是安装后自动运行的流水线。

1. **认路。** 新窗口按开机指引读一张简短入口卡，知道自己是谁、有哪些剧情主线和未完成的事。入口是路标，不把全部历史塞进上下文。
2. **找相关经历。** 根据当前问题，用关键词、标签或剧情目录缩小范围。先看故事，再按需下钻到日卡、片段；要确认当时说过什么，就打开对应 RAW 的原文。只读本次需要的部分，找不到就说明，不能用推测补历史。
3. **理解后再用。** AL 判断过去的经验是否适合当前条件，必要时查相关角色、环境、工具或经验卡。旧记忆提供背景，当前用户的要求、实际文件和验证结果仍要重新核实。
4. **把新经历留下。** 工作形成一个完整片段后，AL 领取写入权，定位本次会话原文，建立 RAW，再提炼 CKP、串进 DAILY，并接到相应 STORY。剧情主干由 AL 自己写清“做了什么、为什么、结果怎样、以后怎么用”，不是机械复述聊天。
5. **修订并接续。** 新结果推翻旧理解时，保留来源和修订痕迹，更新相关剧情与画像。切换或结束工作时留下进度、待办和必要的草稿；下次按入口接续。用覆盖对账发现漏记，再按需要补录。

写入从细到粗：**原文 → 片段 → 日卡 → 剧情**。回忆从粗到细：**目录 → 剧情 → 日卡 → 片段 → 原文**，不要求每次把整条链都读完。角色、环境和经验卡是可关联的长期背景。

当前 MCP 是被动工具，不会自行向对话推送整套记忆。开机读什么由客户端指引决定，后续查什么、写什么由 AL 判断；记忆缺失、维护成本和 Token 消耗也因此需要在实际使用中持续观察。

## 资产：画像卡

剧情记"发生了什么"，画像记"和谁、在什么环境、用什么资源"。这些是带标签的故事卡，AL 自己建、自己维护，不是另外的数据库。

| 类别 | 存什么 |
|---|---|
| 角色资源库 | 用户、AL 自身、长期协作者的身份、分工、偏好、合作经验 |
| 环境资源库 | 设备、系统、路径、软件版本、运行条件，注明核验时间 |
| 工具资源 | 可用工具和资料的位置、使用条件、验证过的做法和限制 |
| 经验卡 | 成功方法、失败原因、适用条件、证据、验证状态和分数 |

只给反复出现、影响长期判断的对象建卡。开机只读入口卡，其他画像按需打开。

## 打分

两种分数，用途不同，不要混。

- **记忆重要度** `importance`：故事列表按它排序、可按它过滤。由 AL 给，引擎不自动判断。
- **技能经验分**：写在经验卡里，表示这个方法能在多大程度上参与工作。没有自动评分器，也没有按分数放行的代码闸门，是 AL 的使用约定。

| 分数 | 规则 |
|---|---|
| 未检验、候选 | 只当参考，不进默认判断 |
| 60–69 | 留作学习线索 |
| 70–79 | 卡住时可试，检查结果 |
| 80–89 | 优先参考，结合当前条件 |
| 90–100 | 真实项目验证过、条件适用时直接采用 |

分数要附在哪验证、何时验证、适用条件和失败边界。它是采用权限，不是荣誉。

## 安装

需要 Python 3.12。

```bash
git clone <仓库地址>
cd al-memory
python -m venv .venv
.venv/Scripts/python -m pip install .        # macOS/Linux: .venv/bin/python
.venv/Scripts/python -m scripts.init_vault --vault-root <源码之外的记忆库目录>
```

接进 Claude Code：把 `examples/mcp.json` 里的两处路径换成你的虚拟环境 Python 和记忆库目录，放进 `.mcp.json`；把 `examples/CLAUDE.md` 复制到项目根目录当开机路标。

想先看效果，把 `--vault-root` 指向 `examples/sample_vault`，那是一个虚构的完整记忆库。

跑测试：

```bash
python -m unittest discover -s tests -t .
```

## 日常

- 开机：`open_story` 读入口卡，再按卡号往下翻。
- 写：先 `claim_write_lease`，再 `write_raw` / `write_checkpoint` / `write_daily` / `write_story`。铺原文必须传 `source_file`。
- 查：`search_memory`、`list_stories`、`open_raw`。
- 查欠账：`check_coverage`。

`_system/memory.sqlite3` 存着原文条目和层间链接，要备份：`python -m tools.backup_vault backup ...`。原文文件会被客户端清理，定期跑 `python -m tools.mirror_sources --vault-root <记忆库>` 做镜像。

## 现状

- 本版只在 Claude Code 上验证过；其他客户端要自己适配。
- 引擎不会自动记，AL 不写就没有。
- 检索是关键词加标签，没有语义检索。

完整说明、设计原则、目录规划、评分约定见 [docs/详细说明.md](docs/详细说明.md)。最高边界见 [docs/CONSTITUTION.md](docs/CONSTITUTION.md)。

## 参与

支持中文。用 Issues 留言，用 Pull Request 提交改动，改动附测试。别在留言和提交里放真实记忆、密钥和他人资料。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

[MIT](LICENSE)。