<div id="memory-记忆系统设计"></div>

# 阅读指南

## 定义

当前提交的 Memory 子系统是一个 Markdown workspace，包含三层现役内容：
追加式 Source 证据、模型写入的 Topic block，以及 Runtime 派生的
Core/Timeline/Recent/Relations 视图。当前实现及其事务、权限和失败契约以
[`overview.zh.md`](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 视图。阅读代码或维护文档时先看下面的实现状态。

## 设计原则

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

## 子文档

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