[分享创造] hongzhao：给 AI 编程智能体的纯文本记忆账本

[cmeng]

你的编程智能体每次会话都在记笔记，然后笔记烂在聊天记录里。hongzhao 给它三本能 git 管的账本。

关于名字：hongzhao 取自「雪泥鸿爪」——苏轼《和子由渑池怀旧》：「人生到处知何似，应似飞鸿踏雪泥。泥上偶然留指爪，鸿飞那复计东西。」鸿雁飞过雪泥，留下几枚爪印，然后继续飞——不驻留、不回头的部分交给智能体，留痕可考的部分交给 hongzhao 。这也正是它的定位：不替你记住一切，只把值得留下的痕迹记成一本可审计的账。

主要功能

• 三本账本：事实主张（ claim ）、项目契约、知识条目——全是 Markdown+YAML ，一个目录装完，没有服务、没有数据库。
• 两道门：写入只落候选区（compile_status: new）；你审阅、说"编译"之后，它才变成智能体能看到的有效视图。未审阅的候选，永远进不了上下文。
• 五种关系管事实演进：取代 / 覆盖 / 提炼 / 冲突 / 裁决，关系写在记录里、编译期执行；没有 expires——时间戳只能说明"何时记的"，不能证明"还对不对"。
• 确定性引擎：零 LLM 调用、零联网，运行时依赖只有 PyYAML ；compile 逐字节可复现，产物 diff 才有意义。
• 三客户端接线：Claude Code / Codex CLI / ZCode ，托管块 + 技能软链，一次安装四端生效。
• v0.2.0 新增：记忆库是独立 git 仓库时，每次编译后自动提交——历史即备份；文档中文为主、英文镜像同步。

和同类项目的区别

这个赛道我盘了 17 个开源项目，可以分成五派：数据库抽取派（ mem0 、hindsight 、zep——LLM 把会话抽成结构化记忆入库，向量/图检索，星数最高）、文件本位派（ EverOS 、memU 、agent-memory——Markdown 是唯一真相）、agent 自编辑派（ letta ）、逐字不蒸馏派（ mempalace ）、trace 评估派（ agent-beacon ）。

hongzhao 属文件本位派，但下面四件事它同时做，目前没有项目同时占：

1. 引擎零 LLM——主流派的记忆管线里住着一个 LLM ，每次"记"都是一次模型判断； hongzhao 的语义判断（该不该记、谁取代谁）只发生在写入那一刻、由你把关，编译是纯脚本确定性执行。
2. 全量人工门——mem0 抽完即生效；同族 EverOS 全自动演化（文件可手改）；最近的同类 agent-memory 只在删除时设门。hongzhao 每条候选、每道门都过人。
3. 编译逐字节可复现——不少"文件本位"项目的索引重建仍要过 LLM ，两次结果不一样； hongzhao 删光全部产物、一条命令重建，字节一致——这也是它敢默认自动 git 提交的前提。
4. 显式关系代数——五关系 + 16 行裁决表 + 合同测试矩阵；两条事实冲突时宁可暴露出来等人裁决，绝不静默"取最新"。

一句话总结差异：别派把记忆当检索问题（记什么、怎么找回来），hongzhao 把记忆当账本问题（谁批准入账、谁取代谁、怎么审计）。

安装只要一句话，把它发给你的智能体：

Read https://github.com/cmeng-CM/hongzhao/blob/main/docs/INSTALL.md and install hongzhao for me. My client is claude_code.

GitHub： https://github.com/cmeng-CM/hongzhao ｜ PyPI：pip install hongzhao（ macOS/Linux · Python 3.9+ · 唯一依赖 PyYAML ）