AL Memory（初级实验版）

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

目的

• AL 自己管自己的经历。 和用户做过什么、为什么这样决定、错在哪、后来怎么改，由 AL 自己读原文、自己提炼、自己写成剧情，并在以后修订。引擎只负责保存、关联、检索和核验原文，不替 AL 判断什么有意义。

• 本地多样性。 同一套引擎，不同的 AL 因为各自的经历和理解，长成不同的工作方式和专长。

• 未来：一个窗口里 AL 自己分类管理项目。 AL 从经历中识别项目、维护各项目的剧情主干、切换时只带眼前需要的记忆。这是方向，本版还没做到。

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

Related MCP server: Nahuali

它做什么

1. 跨窗口、跨对话，记忆都在。

2. 每条记忆指回当时对话的原文位置，打开时用哈希核验：翻到的和保存时一字不差，但不证明内容本身对。

3. 记忆分四层，从粗到细。

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

记忆怎样工作

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

1. 认路。 新窗口按开机指引读一张简短入口卡，知道自己是谁、有哪些剧情主线和未完成的事。入口是路标，不把全部历史塞进上下文。

2. 找相关经历。 根据当前问题，用关键词、标签或剧情目录缩小范围。先看故事，再按需下钻到日卡、片段；要确认当时说过什么，就打开对应 RAW 的原文。只读本次需要的部分，找不到就说明，不能用推测补历史。

3. 理解后再用。 AL 判断过去的经验是否适合当前条件，必要时查相关角色、环境、工具或经验卡。旧记忆提供背景，当前用户的要求、实际文件和验证结果仍要重新核实。

4. 把新经历留下。 工作形成一个完整片段后，AL 领取写入权，定位本次会话原文，建立 RAW，再提炼 CKP、串进 DAILY，并接到相应 STORY。剧情主干由 AL 自己写清“做了什么、为什么、结果怎样、以后怎么用”，不是机械复述聊天。

5. 修订并接续。 新结果推翻旧理解时，保留来源和修订痕迹，更新相关剧情与画像。切换或结束工作时留下进度、待办和必要的草稿；下次按入口接续。用覆盖对账发现漏记，再按需要补录。

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

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

资产：画像卡

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

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

打分

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

• 记忆重要度 importance：故事列表按它排序、可按它过滤。由 AL 给，引擎不自动判断。

• 技能经验分：写在经验卡里，表示这个方法能在多大程度上参与工作。没有自动评分器，也没有按分数放行的代码闸门，是 AL 的使用约定。

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

安装

需要 Python 3.12。

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，那是一个虚构的完整记忆库。

跑测试：

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/CONSTITUTION.md。

参与

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

许可证

MIT。