阅读指南#

定义#

当前提交的 Memory 子系统是一个 Markdown workspace，包含三层现役内容：追加式 Source 证据、模型写入的 Topic block，以及 Runtime 派生的 Core/Timeline/Recent/Relations 视图。当前实现及其事务、权限和失败契约以 overview.zh.md 为准。

下面的实体记忆和 Git-backed Session-Git/Project-Git 是未来设计，不是当前 Source/Topic 写入器的真实来源，也不是当前代码地图。

提议的实体/抽象架构#

实体记忆 (raw, git, immutable, complete)
  ├─ Session-Git    每会话一个 repo，每 turn 一 commit
  └─ Project-Git    绑用户工作目录，agent 改文件 → 自动 commit
         │
         │  提炼 (distillation)：5-stage pipeline, 带 provenance
         ▼
抽象记忆 (derived, compact, provenance-linked)
  ├─ Timeline       时间轴事件流（何时发生了什么）
  ├─ Graph          知识图谱（实体之间什么关系）
  └─ Core.md        ≤2KB 注入快照（LLM 每次都看到）
         │
         │  召回 (recall)：只注入抽象，LLM 用工具导航回实体
         ▼
LLM Context（提议的召回路径）

这张图是设计目标。当前实现不会为每个 session 创建 Git 仓库，不会把每轮自动 commit 到实体记忆，也没有 Graph 视图。阅读代码或维护文档时先看下面的实现状态。

设计原则#

Git-native（未来实体层） — 实体记忆未来可直接使用 Git；这不是当前 Source/Topic workspace 的存储契约。
Provenance-linked — 当前 Topic 层链接到 Source frame；未来实体层再增加 (project, session, commit, timestamp) 坐标。
Bi-temporal — 每条记忆记两个时间：event_time（事情发生时）和 ingestion_time（记下来时）。支持时间旅行查询和矛盾检测。
有范围的召回 — 当前 Runtime 注入现役 Core，并通过 Source/Topic workspace 上的记忆工具读取；由模型直接导航 Git 仍是提议。

子文档#

文档	内容
`overview.zh.md`	当前Source、Topic与派生视图架构，自动writer，权限边界，事务、失败行为和实现记录
`written-marker.zh.md`	记忆怎么知道哪些轮次已经写过，分四层：已替换的位置游标、references下八个框架、已实现的节点marker，以及仍延期的事件通知方案
`written-marker.html`	上述四层的可视化：序号从哪来、分叉时漏掉什么、八个框架并排、走行与三步写入的顺序、以及从记忆自身内容推导的那条路
`architecture.html`	可视化：两个写入入口、五步写入、暂存事务、写入游标、常驻块归谁维护、九个接口方法的接线状况、失败契约
`comparison.html`	可视化：`references/` 下八个框架怎么写长期记忆、怎么记住哪些还没写，八个维度逐条对照，包括分叉之后各家的游标怎么办、各家的常驻块归谁维护，以及我们的选择和两处计划中的改动落在哪一格
`adoption.html`	三层可视化：从那份对照里挑出的四条做法，放进我们的结构各要付什么代价，以及逐条判决（三条采纳，一条按实测的每轮耗时否掉）
`speaker-identity.html`	三层可视化：改之前是什么样（几个人共用一通会话、身份断在哪两处）、references下八个框架各自怎么做、我们怎么做的（两个文件，已落地），以及这个形状留下的两件事（发信人能在正文里打第二个标签、没有键可以按人过滤记忆）和收口它们的那个字段
`authority-landscape.html`	当前owner/paired权限方法、本地参考框架证据、采用/修改/拒绝记录、执行顺序可视化和实现进度
`authority-handoff.md`	已定案的权限与writer决策、延期边界、review处理结果和实现交接
基于 Git 的实体记忆：未实现提案	生命周期、回放、一致性与项目集成提案
`virtual-memory.md`	抽象记忆：Timeline + Graph + Core，按类型 × 生命周期组织

实现状态#

已提交实现保存append-only Source证据、由模型写入的Topic block，以及Runtime确定性生成的Core、Timeline、Recent和Relations视图。每条Source都带Runtime确定的authority provenance：SessionDB writer和通用memory_update事务都从持久化的轮次authority构造，不接受调用方payload里的身份字段；缺少完整authority时创建Source直接失败。自动writer读取SessionDB分支，把成功处理状态记在来源节点上，默认使用聊天agent的provider和模型，memory.writer.model只覆盖writer模型；所有修改通过暂存事务安装。

记忆工具、CLI和Web UI已经注册。已提交基线包含writer状态、一次性trusted Source backfill、memory.backend=none边界以及从SessionDB到watcher状态的组合集成测试。真实writer验收已处理2条符合写入条件的消息，此后历史backfill已在正式工作区执行完毕：154个frame中有137个被引用，共232次引用出现。

Topic block新增的Source引用必须解析到trusted frame，并且必须属于本次事务自己归档的证据，因此任何工具路径都无法引用pending Source或把无关Source挂到新段落上。写入失败归入一个封闭的MemoryWriteFailureCode枚举，状态文件、CLI、工具、API和Web UI共用同一契约；idle watcher在跨进程锁下逐条持久化终态结果；未配对群聊归档有明确的频率与存储上限。按请求方档位过滤读取已部分实现：memory.read独立成capability，读取路径接收调用方解析好的档位，pending证据支撑的block不进入召回与Core；按档位删改block正文仍见authority-handoff.md设计。越权请求hold队列、分支语义provenance、跨会话spawn关系、实体Git层、Graph视图和事件通知writer仍作为独立设计延期。

Last updated · 2026-10-10

PreviousDesign comparison NextArchitecture overview