stratagate-dsh 0.3.5 → 0.3.7

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 ### 近期对话保留细节，远期记忆逐渐简化。
 
-StrataGate 是 DeepSeek Harness 的跨会话记忆插件。近期对话保留细节，较早对话逐渐简化，需要时可以找回原文；重要决定、偏好和计划会整理为长期记忆，供后续会话使用。
+StrataGate 是 DeepSeek Harness 的跨会话记忆插件。近期对话保留细节，较早对话逐渐简化，需要时可以找回原文；重要信息整理为长期事件，知识图谱表达当前状态，主题目录帮助 Agent 了解记过哪些内容，并按需查找来源。
 
 <p align="center">
   <a href="https://github.com/diqierjia/StrataGate-AgentMemory/actions/workflows/ci.yml"><img src="https://github.com/diqierjia/StrataGate-AgentMemory/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
@@ -17,7 +17,7 @@ StrataGate 是 DeepSeek Harness 的跨会话记忆插件。近期对话保留细
 
 [English](README.md) · [DeepSeek Harness 插件说明](docs/DSH.zh-CN.md) · [架构说明](docs/ARCHITECTURE.md) · [完整评测](docs/EVALUATION.md)
 
-<strong>公开评测：</strong>在 LoCoMo 单个对话样本 `conv-26` 的 152 道题上，每个答案经过 10 次独立评审，平均判定正确率为 <strong>80.46%</strong>，Mem0 base 为 <strong>63.22%</strong>。[查看评测范围](#experimental-results)。
+<strong>公开评测：</strong>在 LoCoMo 单个对话样本 `conv-26` 的 152 道题上，每个答案经过 10 次独立评审，平均判定正确率为 <strong>80.46%</strong>，Mem0 base 为 <strong>63.22%</strong>。这组结果对应 R8 评测配置。[查看评测范围](#experimental-results)。
 
 </div>
 
@@ -61,23 +61,25 @@ StrataGate 是 DeepSeek Harness 的跨会话记忆插件。近期对话保留细
 
    ![短期记忆动画：Block 从 L5 逐渐简化到 L0，留在上下文中，并在需要时展开](docs/assets/short-term-memory-explainer-zh.gif)
 
-2. **长期记忆：用事件线保留历史，用知识图谱整理当前状态。**
+2. **长期记忆：事件保留历史，图谱整理现状，主题目录帮助查找。**
 
-   (1) **事件记录“发生过什么”。** 对话中的重要决定、偏好、计划和变化会被提取为 Event，保留来源，并区分“什么时候提到”和“什么时候发生”，供后续会话查找和追溯。→ [事件卡](#event-cards)
+   (1) **事件记录“发生过什么”。** 对话中的重要决定、偏好、要求和变化会被提取为 Event，保留来源，并区分“什么时候提到”和“什么时候发生”，供后续会话查找和追溯。→ [事件卡](#event-cards)
 
    (2) **知识图谱表达“当前是什么状态”。** 根据历史事件，整理人物、项目、组织、工具和地点的当前信息及关系。新事件可以补充或取代旧状态，历史事件及其来源仍然保留。→ [当前状态图谱](#current-state-graph)
 
-   (3) **长期权重也会衰减。** 随着对话推进，未被采用的记忆权重逐渐降低，影响检索与自动召回时的优先级；衰减后的记忆仍保留来源，可继续查证。→ [权重与采用强化](#use-only-reinforcement)
+   (3) **主题目录说明“记过哪些内容”。** 相关事件按长期主题整理为章节和小节。Agent 可以先查看目录，再按需展开主题概览，了解背景、决定、变化和待确认事项，并沿来源查找具体事件。→ [记忆目录与主题概览](docs/MEMORY_TOPICS.zh-CN.md)
 
-   (4) **支持迁移其他 AI 的记忆。** 导入内容可以转换为可追溯的事件，并用于更新知识图谱；原始导入内容仍会保留。→ [外部记忆导入](#external-memory-import)
+   (4) **长期权重也会衰减。** 随着对话推进，未被采用的记忆权重逐渐降低，影响检索与自动召回时的优先级；衰减后的记忆仍保留来源，可继续查证。→ [权重与采用强化](#use-only-reinforcement)
+
+   (5) **支持迁移其他 AI 的记忆。** 导入内容可以转换为可追溯的事件，并用于更新知识图谱；原始导入内容仍会保留。→ [外部记忆导入](#external-memory-import)
 
 3. **证据门：回答前先检查检索到的证据是否够用。**
 
-   搜索结果相关，不代表足以回答当前问题。Agent 会判断证据是否充分；不足时继续搜索、展开事件或回查原始消息，仍无法确认时明确说明不确定性。→ [证据门](#evidence-gate)
+   主题概览帮助定位内容，实际回答需要核对来源事件或原始记录。搜索结果相关，不代表足以回答当前问题。Agent 会判断证据是否充分；不足时继续搜索或展开，仍无法确认时明确说明不确定性。→ [证据门](#evidence-gate)
 
-4. **只强化实际使用的记忆。**
+4. **检索命中不会自动强化记忆。**
 
-   搜索命中或自动带入上下文不会触发强化。只有被记录为最终答案实际采用的证据，才会增加采用计数、更新衰减起点；采用越多，之后衰减越慢，避免记忆仅因频繁被搜到就不断强化自身。→ [只强化实际使用的记忆](#use-only-reinforcement)
+   搜索命中、自动带入上下文和浏览主题目录都不会触发强化。在检索后的采用流程中，被记录为最终答案实际采用的 Event 才会增加采用计数、更新衰减起点；采用越多，之后衰减越慢。主动保存记忆时，确认重复的信息也可强化已有记录。→ [权重与采用强化](#use-only-reinforcement)
 
 开始使用：→ [快速开始](#quick-start-deepseek-harness)
 
@@ -109,16 +111,18 @@ DSH_HOME/stratagate/memory.db
 
 ## 它如何工作
 
-![图 1：StrataGate 整体处理流程——记忆形成、自动激活、主动检索与证据判断](docs/assets/aaed14b0b43a76334008117f6ca104af.png)
+![图 1：StrataGate 整体处理流程——分层对话、事件、图谱与主题目录，以及检索和证据检查](docs/assets/stratagate-memory-workflow-zh-v030.jpg)
+
+图中展示的是答案采用后的 Event 强化流程；主动保存重复信息也可强化已有 Event。Block 展开改变的是展示层，目录与概览本身不作为强化证据。常驻画像单独提供，见[常驻画像说明](#persistent-profile)。
 
-1. **保存对话。** 若干轮连续对话组成一个记忆块（Block），保存为从索引到原文的六种视图。
-2. **提取长期信息。** 决定、偏好、计划或变化被整理为长期事件（Event），保留时间与来源；知识图谱据此整理当前状态。
-3. **回答时找回。** 插件自动带入少量相关记忆；信息不足时，Agent 搜索事件、图谱或原始消息，并判断证据是否够用。
-4. **记录实际使用。** 最终答案选作证据的 Event 会记录为一次“采用”，用于更新长期权重。
+1. **保存对话。** 若干轮连续对话组成一个记忆块（Block），保存为从索引到原文的六种视图。旧 Block 默认展示的内容随对话推进逐渐变简，需要细节时可以重新展开。
+2. **整理长期信息。** 有后续用途的事实、决定、偏好和要求被提取为事件（Event），保留时间、适用范围与来源。知识图谱据此整理当前状态，主题目录与概览把相关事件组织为章节和小节。
+3. **回答时找回。** 插件默认提供当前对话、已设置的常驻画像、少量相关记忆和简短主题目录。信息不足时，Agent 可直接搜索事件、图谱或原文，也可先浏览目录、展开概览，再查找来源事件。
+4. **检查证据并记录采用。** Agent 判断显式检索到的证据是否足以回答；不足时继续检索或展开，充分时据此回答，并记录实际采用的 Event，用于更新长期权重。
 
-自动召回目前最多带入 4 条 Event 和 4 个图谱节点，总预算约 900 tokens。当前会话另由分层 Block 和尚未封存的对话提供。
+自动召回最多带入 **4 条 Event 和 4 个图谱节点**，预算约 **900 tokens**；主题目录另有约 **400 tokens** 的预算，内容较多时提供分类和分页入口。常驻画像、分层 Block 和尚未封存的对话分别提供，不包含在上述两项预算中。
 
-同时提供约 400 词元的记忆目录，说明当前空间记过哪些主题；大目录可分类分页浏览。Agent 按需展开有来源的主题概览，再检索真实事件取证。主题在后台用已有事件分批整理，查看目录不调用模型、不强化记忆。→ [记忆目录与主题整合](docs/MEMORY_TOPICS.zh-CN.md)
+目录和概览在后台用已有事件分批整理。读取已有目录或概览本身不调用模型、不生成证据批次，也不强化记忆。→ [记忆目录与主题概览](docs/MEMORY_TOPICS.zh-CN.md)
 
 ## 核心设计
 
@@ -204,66 +208,101 @@ Block 的展示变化由指数衰减控制：
 
 <a id="event-cards"></a>
 
-### 2. 长期记忆：事件线保留历史，知识图谱整理当前状态
+### 2. 长期记忆：事件保留历史，图谱整理现状，主题目录帮助查找
 
-短期记忆保留一段讨论的上下文，长期记忆则把值得在后续会话中继续使用的信息提取出来。StrataGate 用 Event 记录决定、偏好、计划和变化，再根据这些事件整理知识图谱。
+短期记忆保留讨论上下文，长期记忆把有后续用途的信息整理出来。下面用项目从 npm 改用 pnpm 的示例，说明三种视图如何分工：
 
-![图 3：StrataGate 长期记忆更新——事件提取、历史关系与当前状态图谱](docs/assets/fc07e5b6e1cc07c115faa773a2718aa9.png)
+![图 3：长期记忆——Event 保留选型历史，Graph 展示当前使用 pnpm 和 CI 待验证的状态，Topic 整理主题脉络并链接来源](docs/assets/stratagate-long-term-memory-views-zh.png)
 
-**事件卡记录发生过什么，并保留来源。**
+**Event 记录发生过什么，Graph 整理当前状态，Topic 提供主题脉络和查找入口。** Graph 和 Topic 都从已有 Event 派生；具体结论仍需核对来源事件或原始记录。图中数据仅为示例。
 
-同一个 Block 可以产生多条 Event，也可以没有需要提取的长期信息。每条事件除了内容，还保存来源 Block、来源消息，以及可确定的时间信息。
+**事件记录发生过什么，并保留时间和来源。**
 
-时间信息需要区分两个含义：
+同一个 Block 可以产生多条 Event，也可以没有需要提取的信息。每条事件保留内容、适用范围、来源 Block 和消息，以及能够确定的时间信息。
 
 | 时间 | 表示什么 |
 | --- | --- |
 | 提及时间 | 这件事什么时候在对话中被说到 |
 | 发生时间 | 事情实际发生或计划发生的时间 |
 
-例如，用户在 5 月 6 日说“下周完成原型”，5 月 6 日是提及时间，“下周”描述的是计划完成时间。这条记录应保留计划性质，不能直接作为“原型已经完成”的证据。
+例如，用户在 5 月 6 日说“下周完成原型”，5 月 6 日是提及时间，“下周”描述的是计划完成时间。这条记录应保留计划性质，不能当作“原型已经完成”的证据。无法确定的时间保留原始表达和不确定性。
 
-当时间无法确定时，保留原始表达和不确定性，方便之后回到来源核对。
+**新版提取规则更重视有后续用途的用户信息。**
 
-**新事件通过补充、取代或冲突关系更新记忆。**
+用户的明确要求、纠正、评价和改变决定，只要具有独立用途，就可以成为事件候选；普通的读文件、运行工具和重复测试不会仅因发生过就逐项记录。已经确认的根因、平台限制、失败条件和重要结果仍可保留。
 
-项目讨论可能先后出现：
+提取时需要明确适用范围：单次答复要求保留在会话范围，项目要求属于项目，稳定的用户信息或明确的长期指导才使用用户范围。例如，“这张图的箭头要对齐”不能自动扩大成永久审美偏好。范围缺失或不合法时，程序会有限重试，仍无法得到合法结果就不写入该次提取结果。
 
-> “这个项目使用 npm。”
->
-> “我们改用 pnpm。”
->
-> “下周完成原型。”
+新规则用于升级后的正常提取，不会重放旧对话或统一改写已有事件。具体判断规则见[事件提取说明](docs/event-extractor.md)。
 
-这三条信息的作用不同：
+**新事件补充、取代或标记冲突，历史仍可追溯。**
 
-- “改用 pnpm”更新了包管理器选择，旧 npm 事件保留为历史。
-- “下周完成原型”补充了一项计划，不影响包管理器选择。
-- 如果出现无法同时成立、又不能确定哪条有效的说法，则保留冲突关系，供后续核实。
+项目先决定“使用 npm”，后来改为“使用 pnpm”，旧决定保留为历史，新事件更新当前选择。“迁移后的 CI 待验证”则补充一项待确认事项，不改变包管理器。如果两种说法互相矛盾、又无法确定哪条有效，就保留冲突供后续核实。
 
-旧事件的内容和来源不会被新事件覆盖，其有效状态和关联关系可以随新证据更新。因此，系统既能找到当前有效的信息，也能回答“以前是什么样、后来发生了什么变化”。
+新事件不会覆盖旧事件的内容和来源，其有效状态和关系可以随新证据更新，便于回答“以前是什么样，后来发生了什么变化”。
 
 <a id="current-state-graph"></a>
 
 **知识图谱根据事件整理当前信息和关系。**
 
-图谱将人物、项目、组织、工具和地点表示为节点，将“使用”“参与”“依赖”等联系表示为有方向的关系。节点属性和关系都保留来源 Event。
-
-在上述例子中，图谱可以把项目当前使用的包管理器更新为 pnpm，同时保留 npm 的历史状态。之后：
+图谱用节点表示人物、项目、组织、工具和地点，用关系表示“使用”“参与”“依赖”等联系，属性和关系都保留来源 Event。在上述例子中：
 
-- 问“项目现在使用什么”，可以先查当前图谱；
+- 问“项目现在用什么”，可以先查当前图谱；
 - 问“什么时候改的”，可以查变更事件；
-- 问“为什么改”，可以进一步展开事件并回查原始讨论。
+- 问“为什么改”，可以展开事件并回查原始讨论。
+
+图谱中的状态必须有来源支持。图中的“使用 pnpm”来自 Event ②，“CI 待验证”来自 Event ③；待验证不能当作已通过。只有新证据确认结果后，才更新相应状态。图谱更新失败时可以单独重试，已保存的事件和原文仍可查找。
+
+<a id="memory-topics"></a>
+
+**主题目录帮助 Agent 知道有哪些记忆，再找到具体来源。**
+
+知道关键词时，可以直接检索；只记得大概聊过某件事时，可以先看目录。一个 Topic 对应长期章节，例如图中的“项目 X”；章内小节容纳持续相关的事项，例如“依赖与构建”。具体版本、bug 和处理进度放在小节内部，避免每次变化都新建章节。
+
+目录提供主题名称和入口，按需展开的概览整理背景、进展、决定、变化和待确认问题，并保留事件来源。同名内容归入同一节，新增内容时尽量保持已有章节和小节的编号稳定。
+
+例如，用户问“之前项目技术方案讨论到哪了”，Agent 可以先找到相应主题，查看概览，再检索来源事件，核对已经确定的方案、后续变更和待决定问题。
 
-图谱中的状态需要与来源一致。“下周完成原型”直接支持的是一项计划；图中展示的“原型开发中”或“负责人”等信息，需要相应事件提供额外依据。
+**概览用于导航，回答依据仍需从来源取得。** 浏览目录和概览不产生证据批次、不强化记忆；需要引用事实时，再检索事件或展开来源，并完成证据检查。目录未整理好时，普通事件、图谱和原文检索仍可使用。
 
-图谱更新作为独立任务执行并保存进度。更新失败时，可以单独重试，已经写入的事件和原始来源仍然保留。
+工具与后台整理细节见[记忆目录与主题整合](docs/MEMORY_TOPICS.zh-CN.md)。
+
+<a id="persistent-profile"></a>
+
+**常驻画像、长期事件和当前要求分别保存。**
+
+| 用户表达 | 保存位置 | 什么时候使用 |
+| --- | --- | --- |
+| “以后默认用中文回答” | 常驻画像 Profile | 设置后跨会话自动提供 |
+| “这个项目已经改用 pnpm” | 长期事件 Event | 在相关问题中召回或检索 |
+| “这次回答简短一点” | 当前对话 | 用于本次回答，无需写入长期记忆 |
+
+“记住”一词本身不决定保存位置。明确的画像更新请求可以直接应用；由 Agent 推断的画像变化需要先说明拟修改的字段与内容，并取得用户同意。适合在相关情境中想起的信息，也可以通过主动记忆工具保存，不必等待对话封块。
+
+地点画像区分默认地点、常驻城市和当前城市。例如，常住哈尔滨、目前出差北京时，问天气会优先使用本次明确指定的地点；没有指定时参考当前城市，再参考默认地点。出差不会自动覆盖常驻城市，当前城市跨会话保留到用户修改或清空。使用说明见[插件指南](docs/DSH.zh-CN.md)。
 
 <a id="evidence-gate"></a>
 
 ### 3. 证据门：检查检索结果是否足以回答当前问题
 
-找到相关记忆之后，还需要判断它能否支持当前答案。StrataGate 通过一个固定、简短的评估结构，要求 Agent 明确说明证据是否充分，以及接下来应当做什么。
+找到相关记忆后，Agent 还需要判断它是否支持当前答案：证据够不够，还缺什么，应该直接回答还是继续查找。检索排序和记忆权重都不能当作事实正确率。
+
+例如，用户问“为什么当初改用了 pnpm”：
+
+| 步骤 | 找到的内容 | 应如何处理 |
+| --- | --- | --- |
+| 找到主题 | “项目技术选型”的概览提到换了包管理器 | 沿来源查找具体事件 |
+| 检索事件 | “项目已从 npm 改为 pnpm” | 只能确认变更，原因仍缺失，继续展开 |
+| 核对原文 | 示例原话：“安装更快，也更适合我们的多包结构” | 核对适用项目和时间后，按这段证据解释原因 |
+
+这里的原话是演示用例。若来源没有说明原因，Agent 应明确无法确认，不能根据 pnpm 的一般优点推测当时的决定。
+
+证据是否充分由模型判断，程序检查来源引用和检索流程。主题概览只提供导航线索；实际采用仍需来自经过检查的检索证据。已有上下文足以回答时，不必为了流程额外搜索。
+
+显式检索批次在最终回答前需要完成证据评估和采用记录；未使用的批次也要记录为空采用。遗漏时，插件会先要求完成收尾，再生成完整的用户答案，避免以内部状态说明结束回复。模型仍可能误判证据，无法核实时应保留不确定性。
+
+<details>
+<summary>证据评估字段与流程检查</summary>
 
 | 评估项 | 需要说明的内容 |
 | --- | --- |
@@ -273,23 +312,13 @@ Block 的展示变化由指数衰减控制：
 | `missing` | 还缺少哪些信息 |
 | `next_strategy` | 直接回答，还是继续搜索或展开 |
 
-例如，用户问：
-
-> 为什么当初改用了 pnpm？
-
-检索结果只有：
-
-> 项目已从 npm 改为 pnpm。
-
-这条结果确认了变更，却没有说明原因。Agent 应将其判断为部分充分，继续展开事件或回查原始对话，而不能仅凭工具选择推测当时的理由。
+引用必须来自指定检索批次；接受 `sufficient` 时，需要有效证据引用，并明确选择回答。采用记录只包含实际用于答案的证据，没有采用则提交空列表。接口说明见[插件指南](docs/DSH.zh-CN.md)。
 
-证据门由模型判断内容是否充分，程序负责检查引用和流程约束：被引用的证据必须来自指定检索批次；接受 `sufficient` 时，需要有效证据引用，并明确选择回答。
-
-这些检查使检索过程可以追踪和核验，但模型仍可能误判证据。没有找到足够信息时，应继续查找，或在回答中明确说明无法确认。
+</details>
 
 <a id="use-only-reinforcement"></a>
 
-### 4. 只强化实际使用的记忆：采用越多，之后衰减越慢
+### 4. 检索命中不会自动强化记忆：采用越多，之后衰减越慢
 
 长期记忆也会随对话推进而衰减。这里变化的是 Event 的权重，它参与后续召回和排序；与短期 Block 不同，Event 不会因此逐级切换 L0–L5 展示层。
 
@@ -301,9 +330,9 @@ Block 的展示变化由指数衰减控制：
 
 检索命中只说明一条记忆可能相关。系统可以记录它何时被检索，但不会因此增加采用计数，也不会重置衰减起点。
 
-自动带入上下文的记忆同样不会因为被展示而获得强化。这样可以避免某条记忆仅因偶然排在前面，就通过反复出现不断提高自身权重。
+自动带入上下文、浏览主题目录和展开概览，同样不会因为内容被展示而强化记忆。这样可以避免某条记忆仅因偶然排在前面，就通过反复出现不断提高自身权重。
 
-**记录为实际采用后，才更新权重。**
+**检索后的实际采用会更新权重。**
 
 Agent 确定用于最终回答的证据后，会提交采用回执。通过检查的 Event 增加采用计数，并把衰减起点更新到当前轮次。对于未被额外限制权重的普通活跃事件，此时权重回到 1。
 
@@ -311,6 +340,10 @@ Agent 确定用于最终回答的证据后，会提交采用回执。通过检
 
 采用依据来自 Agent 提交的证据选择。程序检查证据是否属于对应批次、是否经过充分性评估，并通过回执避免同一次操作被重复执行；没有使用的检索结果不获得这次强化。
 
+**主动保存重复信息，也可以强化已有记录。**
+
+使用 `memory_remember` 主动保存信息时，程序确认与已有主动记忆完全或近似重复，可强化已有事件，而无需再创建一张重复卡片。这属于写入时的重复处理，与搜索命中不同。
+
 **不同重要程度的记忆，可以保留不同的最低权重。**
 
 | 记忆类别 | 默认最低权重 |
@@ -337,8 +370,8 @@ Agent 确定用于最终回答的证据后，会提交采用回执。通过检
 
 其中：
 
-- `t` 是当前轮次与上次采用轮次的差，新事件从创建时开始计算；
-- `n` 是内部采用计数，初始化为 1，每次记录采用后增加 1；
+- `t` 是当前轮次与最近一次强化锚点的差，新事件从创建时开始计算；
+- `n` 是内部计数，初始化为 1；答案采用或主动记忆重复确认时增加，单纯检索不增加；
 - `floor` 是根据记忆重要程度设置的最低权重。
 
 长期权重衰减同样按对话轮次计算，而不是按现实时间计算。较低的权重可能降低一条记忆在后续召回中的优先级，但不会因衰减而删除它的历史记录。
@@ -373,6 +406,8 @@ LoCoMo 中有一道题询问 Caroline 在什么时候进行了学校演讲。检
 
 仓库公开的 R8 对比评测使用 LoCoMo 中的 `conv-26` 对话样本，包含 **419 条消息、35 个会话和 152 道问题**，覆盖 category 1–4。
 
+**以下成绩对应公开的 R8 实验配置，不是 0.3.0 主题目录或 0.3.2 新版事件提取的专项评测。** 不能据此推断这些更新的准确率、成本变化或独立收益。
+
 两个系统分别生成答案，再对每道题的答案进行 **10 次独立 Judge 评审**。这里的十次指评审重复次数，不代表十次完整系统运行。
 
 | 指标 | StrataGate | Mem0 base | 差值 |
@@ -404,11 +439,21 @@ R1–R8 的设计演变、逐题分析与后续验证方向见[完整评测](doc
 
 ## 使用范围与成本
 
-记忆可以按项目、会话或全局范围组织。知识图谱界面用于查看信息、关系与来源；多人协作编辑和跨产品云端同步不是主要功能。
+**记忆空间决定哪些对话共享记忆。** DSH 默认按项目工作目录隔离；也可按会话隔离，或使用全局共享空间。主题目录只展示当前空间内可见的事件，常驻画像则跨会话、跨记忆空间提供。配置方式见[插件指南](docs/DSH.zh-CN.md)。
+
+**回答时的上下文预算，不等于全部模型开销。** 自动召回和主题目录各有预算，常驻画像、分层 Block、当前未封存对话及后续主动检索另行提供。900 tokens 和 400 tokens 分别是相关记忆与目录的预算，不能相加后当作整个请求的固定大小。
+
+| 环节 | 是否调用模型 | 成本来自哪里 |
+| --- | --- | --- |
+| 后台摘要、事件提取、图谱、主题与画像整理 | 会 | 对话、事件或画像输入、生成结果，以及有限重试 |
+| 读取已有目录、概览或搜索已有记录 | 读取本身不调用模型 | 结果带入后续模型上下文时仍占 tokens |
+| Agent 判断证据并生成答案 | 会 | 当前上下文、取回的证据和答案生成 |
+
+分层视图减少的是回答时默认带入的历史内容。后台处理工具密集型对话时，会精简代码和过长工具记录的模型输入；完整记录仍保留在 L5。总费用需要结合后台处理、检索和回答的实际用量评估，不能由上下文变短直接推断。
 
-分层视图减少的是回答时带入的历史上下文。后台生成摘要、提取 Event 和整理图谱仍会调用模型，因此不能把上下文减少直接等同于总 Token 或费用下降；工具记录较多时，后台成本尤其需要结合实际使用量评估。
+**升级后，历史目录逐步形成。** 已有事件在后台分批整理，目录可能暂时不完整；新增或变化的事件优先处理。失败或待整理的内容仍有事件入口，普通检索继续可用。历史整理有全库共享额度、有限重试和重启恢复，不承诺固定金额；额度与恢复细节见[主题整理说明](docs/MEMORY_TOPICS.zh-CN.md)。
 
-公共 API、模型接入和评测覆盖仍在迭代，自定义集成应固定版本并验证自己的场景。证据门要求模型说明依据，但不能保证判断和答案永远正确。
+目录与概览可根据有效来源重建。来源被修改、遗忘或归档后，过期派生内容先隐藏，再后台重建。新版事件提取规则用于后续正常提取，不统一重写旧事件。功能测试检查这些流程与约束，实际提取、归类和证据判断仍取决于模型。
 
 <a id="代码入口"></a>
 <a id="code-entry-points"></a>
@@ -434,7 +479,9 @@ npm run build
 | 资源 | 内容 |
 | --- | --- |
 | [DeepSeek Harness 使用说明](docs/DSH.zh-CN.md) | 安装、配置、界面、记忆工具和恢复机制 |
-| [架构文档](docs/ARCHITECTURE.md) | 分层规则、事件与图谱、检索、证据门、权重和存储约束 |
+| [记忆目录与主题概览](docs/MEMORY_TOPICS.zh-CN.md) | 章节与小节、来源追溯、后台整理、预算和恢复 |
+| [事件提取规则](docs/event-extractor.md) | 提取判断、适用范围、重复与历史关系，以及兼容边界 |
+| [架构文档](docs/ARCHITECTURE.md) | 分层规则、事件与图谱、检索、证据门、权重、存储和核心 API |
 | [外部记忆导入](docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md) | 导出格式、导入流程和接入示例 |
 | [完整评测](docs/EVALUATION.md) | 实验协议、版本演变、失败分析和结果范围 |
 | [评测汇总数据](benchmarks/locomo-conv26-r8-final.json) | 已公开运行的结果、统计和产物信息 |
@@ -442,7 +489,7 @@ npm run build
 
 核心实现位于 `packages/core/`，DSH 适配层位于 `src/`。分层规则见 [blocks.ts](packages/core/src/blocks.ts)，长期权重见 [weights.ts](packages/core/src/weights.ts)。
 
-核心库的 `StrataGate.open()` 使用 SQLite，`StrataGate.inMemory()` 用于临时运行和测试。持久化模式下，`recordMemoryUse()` 必须提供稳定的 `receiptId`；同一次采用操作重试时复用该 ID，避免重复强化。参见[架构说明](docs/ARCHITECTURE.md)。
+核心 API 接入、持久化及采用回执的幂等处理见[架构说明](docs/ARCHITECTURE.md)，最小用法见[核心引擎示例](packages/core/examples/basic.ts)。
 
 ## 参与贡献