stratagate-dsh 0.2.71 → 0.2.73

package/README.zh-CN.md

@@ -4,9 +4,9 @@
 
 # StrataGate
 
-### 保留原始证据的长期记忆。
+### 近期对话保留细节，远期记忆逐渐简化。
 
-StrataGate 让长期运行的 AI Agent 跨会话记住信息，同时避免把每条记忆都当成不需要核对的事实。
+StrataGate 让 AI Agent 的短期记忆随对话推进逐渐变得简略，需要时可重新展开、找回原始细节；重要信息则沉淀为事件与知识图谱，持续记录历史变化与当前状态，供后续会话使用。
 
 [![CI](https://github.com/diqierjia/StrataGate-AgentMemory/actions/workflows/ci.yml/badge.svg)](https://github.com/diqierjia/StrataGate-AgentMemory/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/stratagate-dsh.svg)](https://www.npmjs.com/package/stratagate-dsh)
@@ -21,17 +21,35 @@ StrataGate 让长期运行的 AI Agent 跨会话记住信息，同时避免把
 
 </div>
 
-> <strong>简单来说：</strong>StrataGate 不仅记住发生了什么，也保留这些记忆来自哪里；Agent 使用记忆前，还要先判断现有证据够不够。
+> **简单来说：** StrataGate 让近期对话保留细节，让较早的对话随对话推进逐渐简化；重要信息则整理为事件与知识图谱，供后续会话使用。原始记录始终保留，需要时可以重新展开、核对细节。
 
 ## 为什么选择 StrataGate？
 
-- **自动、本地优先的跨会话记忆。** 主 Agent 已完成的对话和工具结果会自动写入本地 SQLite，不需要另建记忆服务器。→ [快速开始](#quick-start-deepseek-harness)
-- **分层保存，上下文不会一直变长。** 最近的对话保留细节，较早的内容逐渐变成简短索引；只有证据不足时才向下展开。→ [分层记忆](#layered-memory)
-- **每条事件都带来源和时间。** 长期记忆不仅记录内容，也能说明来自哪段对话，并区分“什么时候提到”和“什么时候发生”。→ [事件卡](#event-cards)
-- **用知识图谱表示当前状态。** 带来源的事件可以整理成人物、项目、组织、工具和地点目前的状态。→ [当前状态图谱](#current-state-graph)
-- **回答前先检查证据是否够用。** 搜索结果相关，不代表足以回答；Agent 可能需要继续搜索、展开结果或回查原始消息。→ [证据门](#evidence-gate)
-- **搜索命中不会自动强化记忆。** 只有最终答案真正采用的证据，才会更新长期权重，避免越常搜到就越容易再次搜到。→ [只强化实际使用的记忆](#use-only-reinforcement)
-- **导入其他 AI 的记忆时保留原文。** 结构化记忆可以转换成可追溯的事件，原始导入内容仍会永久保存。→ [外部记忆导入](#external-memory-import)
+1. **短期记忆：随对话推进逐渐模糊，需要时重新展开。**
+
+   (1) **近期详细，远期简略。** 同一段对话保存为 L0–L5 六种详细程度的视图。随着后续对话积累，较早的记忆逐渐从完整对话变为关键事实、简短摘要和标题索引，减少历史内容对上下文的占用。→ [分层记忆](#layered-memory)
+
+   (2) **展示变简，原始记录保留。** 完整的 L5 原始消息与工具记录始终保存。需要核对细节时，Agent 可以按需展开，找回当时的原话和上下文。→ [分层记忆](#layered-memory)
+
+2. **长期记忆：用事件线保留历史，用知识图谱整理当前状态。**
+
+   (1) **事件记录“发生过什么”。** 对话中的重要决定、偏好、计划和变化会被提取为 Event，保留来源，并区分“什么时候提到”和“什么时候发生”，供后续会话查找和追溯。→ [事件卡](#event-cards)
+
+   (2) **知识图谱表达“当前是什么状态”。** 根据历史事件，整理人物、项目、组织、工具和地点的当前信息及关系。新事件可以补充或取代旧状态，历史事件及其来源仍然保留。→ [当前状态图谱](#current-state-graph)
+
+   (3) **长期权重也会衰减。** 随着对话推进，未被采用的记忆权重逐渐降低，影响检索与自动召回时的优先级；衰减后的记忆仍保留来源，可继续查证。→ [权重与采用强化](#use-only-reinforcement)
+
+   (4) **支持迁移其他 AI 的记忆。** 导入内容可以转换为可追溯的事件，并用于更新知识图谱；原始导入内容仍会保留。→ [外部记忆导入](#external-memory-import)
+
+3. **证据门：回答前先检查检索到的证据是否够用。**
+
+   搜索结果相关，不代表足以回答当前问题。Agent 会判断证据是否充分；不足时继续搜索、展开事件或回查原始消息，仍无法确认时明确说明不确定性。→ [证据门](#evidence-gate)
+
+4. **只强化实际使用的记忆。**
+
+   搜索命中或自动带入上下文不会触发强化。只有被记录为最终答案实际采用的证据，才会增加采用计数、更新衰减起点；采用越多，之后衰减越慢，避免记忆仅因频繁被搜到就不断强化自身。→ [只强化实际使用的记忆](#use-only-reinforcement)
+
+开始使用：→ [快速开始](#quick-start-deepseek-harness)
 
 ## 选择适合你的入口
 
@@ -62,207 +80,284 @@ DSH_HOME/stratagate/memory.db
 
 ## 这些设计要解决什么问题
 
-长期运行的 Agent 不只是需要“存下更多内容”，还需要在回答时找回**正确、完整、可核对**的证据。
+随着对话不断积累，AI Agent 需要在有限的上下文中，同时处理眼前的任务、之前的讨论和长期有效的信息。
 
-只保留摘要，容易丢失日期、限定条件和原话；只做相似度检索，可能找到相关内容，却不是问题真正询问的事件；把每次搜索命中都当作有效记忆，还会形成自我强化的检索反馈。
-
-StrataGate 围绕四个核心问题设计长期记忆：
+近期讨论通常需要完整细节，较早的对话则可以先保留简短概括，等到需要时再展开。与此同时，用户偏好、项目决定和任务计划还会发生变化，需要区分历史记录与当前状态。StrataGate 围绕这些需求，分别管理短期记忆的展示、长期记忆的更新，以及检索后的判断和使用反馈。
 
 | 常见问题 | StrataGate 的处理方式 |
 | --- | --- |
-| 历史越来越长，无法全部放入上下文 | 将对话保存为 L0–L5 分层视图，旧记忆默认只显示较浅层级 |
-| 摘要遗漏了日期、原话或限定条件 | L5 原始消息始终保留，任何派生记忆都能回到来源 |
-| 搜到了相关内容，但证据不足以回答 | 使用证据门判断是否充分；不足时换策略、展开事件或回查原文 |
-| 高频检索结果不断强化自身 | 只有真正被答案采用的记忆才会更新长期权重 |
+| 对话越来越长，历史细节持续占用上下文 | 将同一段对话保存为 L0–L5 分层视图；随着后续对话积累，较早的内容默认展示得更简略，需要时再展开 |
+| 重要信息分散在不同对话中，旧决定与新状态容易混淆 | 提取带来源和时间的 Event，用事件线保留历史，再通过知识图谱整理当前状态 |
+| 搜到了相关内容，却缺少回答问题所需的关键细节 | 通过证据门评估当前材料；不足时继续搜索、展开记忆或回查原文 |
+| 记忆仅因频繁被搜到，就不断获得更高权重 | 将检索与采用分开：长期权重随对话推进衰减，只有记录为实际采用的记忆才触发强化 |
 
-StrataGate 的目标不是让 Agent 每次检索更多，而是让它知道：**当前证据是否足够，以及下一步应该去哪里找。**
+短期记忆衰减，让旧对话逐渐减少在当前上下文中呈现的细节；长期记忆及其权重机制，帮助 Agent 在后续会话中找回仍然有用的信息。两者都保留来源，使简化后的内容能够继续追溯和核对。
 
-## 实验结果
+<a id="how-stratagate-works"></a>
 
-当前公开对比覆盖 LoCoMo `conv-26`：
+## 它如何工作
 
-- 419 条消息；
-- 35 个会话；
-- category 1–4 的 152 道问题；
-- 每道题进行 10 次独立 Judge 评审。
+![图 1：StrataGate 整体处理流程——记忆形成、自动激活、主动检索与证据判断](docs/assets/aaed14b0b43a76334008117f6ca104af.png)
 
-| 指标 | StrataGate | Mem0 base | 差值 |
-| --- | ---: | ---: | ---: |
-| 10 次评审平均准确率 | **80.46%** | 63.22% | **+17.24 个百分点** |
-| 多数票正确 | **121 / 152（79.61%）** | 96 / 152（63.16%） | **+25 题** |
-| Temporal | **74.86%** | 34.59% | **+40.27 个百分点** |
-| Single-hop | **89.29%** | 75.14% | **+14.14 个百分点** |
-| Multi-hop | **66.56%** | 61.56% | +5.00 个百分点 |
-| Open-domain | 83.08% | **84.62%** | -1.54 个百分点 |
+*图 1 中的四次检索预算为示例评测配置；具体检索循环和预算由接入方控制。*
 
-最大的差距出现在时间类问题。这个结果与 StrataGate 显式保存事件发生时间、保留来源时间戳并支持原文核对的设计一致，但它不是单组件消融实验，不能把全部差距归因于某一个字段或检索步骤。
+StrataGate 的工作过程分为记忆形成、回答时找回，以及采用后的反馈。
 
-两边使用相同的问题、顺序、答案模型、Judge 模型、Judge prompt、解析器和重复次数，并且都重新构建了记忆。两边的记忆抽取、检索实现、embedding 和回答上下文不同，因此这里比较的是两个**完整系统配置**。
+### 1. 对话积累，形成分层短期记忆
 
-这只是 `conv-26` 上的一次单会话对比，不代表完整 LoCoMo 成绩。完整协议、逐题结果、Judge 波动和产物哈希见：
+每轮完成的对话及工具记录会先保存。DeepSeek Harness 插件默认每 **6 轮**封存一个 Block，用户可以调整这一大小；尚未达到边界的内容继续保留在当前对话中。
 
-- [`docs/EVALUATION.md`](docs/EVALUATION.md)
-- [`benchmarks/locomo-conv26-r8-final.json`](benchmarks/locomo-conv26-r8-final.json)
+每个 Block 保存 L0–L5 六种详细程度的视图，从标题索引、简短摘要到完整原始记录。后台处理完成后，Block 才开始参与衰减：随着同一会话中的后续就绪 Block 增加，较早的 Block 默认展示层逐渐变浅。
 
-<a id="how-stratagate-works"></a>
+这个过程减少的是当前上下文中呈现的历史细节，完整的 L5 原始记录仍然保留。→ [分层记忆](#layered-memory)
 
-## 它如何工作
+### 2. 重要信息沉淀为 Event，并更新知识图谱
+
+对话中值得长期保留的决定、偏好、计划和变化，会被提取为 Event。每条事件记录内容、时间和来源，供之后的会话查找。
+
+知识图谱再根据这些事件，整理人物、项目、工具等实体的当前信息和关系。新事件可以补充或取代旧状态，历史事件及其来源继续保留。→ [事件卡](#event-cards) · [当前状态图谱](#current-state-graph)
+
+### 3. 回答前自动带入相关记忆，需要时主动检索
+
+每次主模型调用前，插件会根据当前问题和最近的对话，自动带入少量相关的长期 Event 与图谱信息，为回答提供背景。
+
+当前 DSH 实现最多带入 **4 条 Event 和 4 个图谱节点**，并受约 **900 tokens** 的总预算限制。当前会话的历史则通过分层 Block 和尚未封存的对话提供。
+
+如果已有上下文足够，Agent 可以直接回答；如果还缺少信息，就通过记忆工具搜索事件、图谱或原始消息，并按需展开更详细的内容。
+
+### 4. 主动检索后，检查证据是否足以回答
+
+找到相关记忆后，Agent 需要判断它是否真正回答了当前问题：哪些证据可以使用，还缺少什么，以及是否需要继续查找。
 
-![StrataGate 工作流程：分层记忆、事件卡与证据门](docs/assets/stratagate-how-it-works.zh-CN.png)
+例如，“项目使用 pnpm”可以回答当前采用什么工具，但不足以回答“当初为什么选择 pnpm”。遇到这种情况，Agent 应展开相关事件或回查原始讨论。
 
-正常的记忆过程可以分成五步：
+证据门要求模型明确给出这份判断，并由代码检查证据引用和流程约束。证据仍然不足时，Agent 需要继续查找，或明确说明无法确认。→ [证据门](#evidence-gate)
 
-1. **先保存来源。** 任何摘要产生之前，已完成的消息和工具结果都会先保存在本地。
-2. **生成更小的视图。** StrataGate 会整理出分层摘要、记录“发生了什么”的事件，以及描述当前状态的图谱事实。
-3. **先搜索短记录。** Agent 从简短结果开始，只有需要更多细节时，才展开事件、图谱节点或原始 Block。
-4. **回答前检查证据。** 证据门判断现有结果是否充分；如果不够，Agent 必须继续搜索或返回原始消息。
-5. **只强化真正用过的记忆。** 只有最终答案确实采用的记忆，才会获得长期权重。
+### 5. 记录实际采用的证据，更新长期权重
 
-例如，用户说“这个项目使用 pnpm”。StrataGate 会保留原始对话，建立一条可以追溯来源的事件，并在以后的对话中用“项目使用 pnpm”这条简短信息提供背景。如果答案依赖原话或当时的讨论，Agent 可以从事件返回原始消息，而不是只相信缩短后的内容。[查看一条完整的检索示例](#一次真实的检索)。
+搜索命中或自动带入上下文，不会触发记忆强化。
+
+当 Agent 确定哪些证据用于最终回答时，会提交采用回执。被记录为实际采用的 Event 更新采用计数和衰减起点；采用次数越多，之后衰减越慢。没有采用的搜索结果不会获得这次强化。→ [只强化实际使用的记忆](#use-only-reinforcement)
+
+例如，用户先决定“项目使用 npm”，后来改为“项目使用 pnpm”。StrataGate 会保留这两次决定，并在知识图谱中更新当前选择。之后询问“现在用什么”，可以从当前状态中找到答案；询问“什么时候改的、为什么改”，则可以沿 Event 回到当时的对话，核对时间和原因。
+
+[查看一次从事件卡回查原始消息的检索示例](#一次真实的检索)。
 
 ## 核心设计
 
+StrataGate 分别管理对话的展示层级、长期信息的更新、检索证据的判断，以及记忆被采用后的反馈。
+
+其中，**短期记忆衰减决定旧对话展示得多详细，长期记忆权重影响信息在后续召回中的优先级**。这两种变化都不会因衰减而删除原始来源。
+
 <a id="layered-memory"></a>
 
-### 1. 分层记忆：压缩视图，不丢来源
+### 1. 短期记忆：随对话推进逐渐简化，需要时重新展开
+
+近期讨论通常需要保留完整细节，较早的对话则可以先以简短形式留在上下文中。StrataGate 为同一段对话保存多种详细程度的视图，并随着后续对话积累，逐渐减少旧对话默认呈现的内容。
 
-默认每 12 轮完整对话封存为一个记忆块。尚未达到边界的消息保留在 open tail 中，不会提前压缩或抽取。
+![图 2：StrataGate 短期记忆——L0–L5 分层视图、展示衰减与按需展开](docs/assets/41fc676096d0a13337a1c03aaf8f499b.png)
 
-这是核心库的默认值。DeepSeek Harness 插件为了更及时地产生 Event，默认每 6 轮封存一个 Block，并允许用户通过 `blockTurnSize` 自定义。Block 的 age 是它与同一线程中最新已就绪 Block 的距离，因此 open tail 和模型待处理 Block 不会触发衰减；默认 Block 衰减系数为 `0.30`。
+**同一段对话，保存为六种详细程度。**
 
-每个已封存的块包含六种详细程度：
+DeepSeek Harness 插件默认每 **6 轮**完整对话封存一个 Block，一轮指一次用户提问和助手的完整回复。封块大小可以配置；核心库默认值为 12 轮。尚未达到边界的内容继续保留在当前对话中。
 
-| 层级 | 内容 | 主要用途 |
+每个完成处理的 Block 包含以下视图：
+
+| 层级 | 保存的内容 | 主要用途 |
 | --- | --- | --- |
-| L0 | 标题和标签 | 为很久以前的记忆提供轻量索引 |
-| L1 | 简短摘要 | 快速判断一段历史是否相关 |
-| L2 | 关键事实 | 提供紧凑的事实列表 |
-| L3 | 规则化精简对话 | 删除范围明确的冗余，不做自由语义改写 |
-| L4 | 接近原文的可读对话 | 核对自然语言上下文和工具结果 |
-| L5 | 完整消息和工具记录 | 最终来源 |
+| L0 | 标题和标签 | 用最少内容标识这段历史 |
+| L1 | 简短摘要 | 快速了解讨论主题 |
+| L2 | 关键事实 | 查看决定、约束、计划和结果 |
+| L3 | 按规则精简的对话 | 保留讨论过程，去除明确冗余 |
+| L4 | 接近原文的可读对话 | 核对更完整的语言上下文 |
+| L5 | 原始消息与工具记录 | 查证来源及具体细节 |
+
+L0–L2 由模型概括生成；L3、L4 由程序按照确定性规则生成。L3 可以精简独立寒暄、纯确认、重复长粘贴内容和工具参数等，不进行自由语义改写。
+
+原始记录先保存，摘要和事件处理随后进行。只有处理完成、进入就绪状态的 Block，才会替换对应的原生历史并参与衰减。
+
+**后续对话越多，旧 Block 默认展示得越简略。**
+
+Block 的展示变化由指数衰减控制：
+
+$$
+w_{\text{block}}(age)=e^{-\lambda_{\text{block}}\,age}
+$$
+
+其中，$\lambda_{\text{block}}$ 默认取 **0.30**，程序根据权重区间选择当前展示层级。系数越小，详细内容保留得越久，相应占用的上下文也越多。
+
+公式中的 `age` 按当前展示锚点与同一会话最新就绪 Block 之间的距离计算。它衡量的是对话积累的进度，**不是现实中经过的天数**。尚未封存的对话，以及仍在等待模型处理的 Block，都不会推动这项衰减。
+
+例如，一个从 L5 开始、期间没有重新展开的 Block，在默认参数下会经历：
 
-Block 到达边界时，StrataGate 会在任何模型调用之前，先原子地保存永久 L5 与确定性生成的 L4、L3。随后 Block 保持模型待处理状态，不能替换原生对话历史，也不参与衰减；只有 L0–L2 校验和 Event 处理完成后才进入就绪状态。随着后续就绪 Block 增加，默认展示层级逐渐变浅；需要更多细节时，可以重新展开。
+| 后续新增的就绪 Block 数量 | 默认展示层 |
+| ---: | --- |
+| 0–1 | L5 |
+| 2 | L4 |
+| 3–4 | L3 |
+| 5–6 | L2 |
+| 7–8 | L1 |
+| 9 及以上 | L0 |
 
-L0–L4 都是同一份来源的派生视图，不会覆盖或重写 L5。事件卡同样只能引用原始块，不能反向修改来源。
+图中的层级变化用于展示趋势，实际变化由衰减参数和层级阈值共同决定，并非每新增一个 Block 就下降一级。
 
-这使 StrataGate 可以同时满足两个目标：
+**需要细节时，可以重新展开。**
 
-- 旧记忆保持轻量；
-- 任何关键结论仍然可以回到原始消息核对。
+假设某段旧对话目前只显示：
+
+> 讨论了项目技术方案与近期计划。
+
+用户追问“当初为什么选择 pnpm”，Agent 可以展开关键事实、精简对话或完整原始记录，找到当时的原因。
+
+展开既可以逐级进行，也可以直接指定更详细的层级。展开后，系统会以此次选定的层级和当前 Block 位置重新设置衰减起点；随着后续对话继续积累，它再逐渐变简。
+
+因此，旧对话日常可以保持轻量，需要时仍能恢复细节。**L0–L4 都是原始记录的派生视图，不会覆盖 L5。**
 
 <a id="event-cards"></a>
 
-### 2. 事件卡：同时保存内容、来源和时间
+### 2. 长期记忆：事件线保留历史，知识图谱整理当前状态
 
-值得长期查找的决定、偏好、计划、纠正和时间事件会被整理成事件卡。
+短期记忆保留一段讨论的上下文，长期记忆则把值得在后续会话中继续使用的信息提取出来。StrataGate 用 Event 记录决定、偏好、计划和变化，再根据这些事件整理知识图谱。
 
-每张事件卡不仅保存摘要，还会记录：
+![图 4：StrataGate 长期记忆更新——事件提取、历史关系与当前状态图谱](docs/assets/fc07e5b6e1cc07c115faa773a2718aa9.png)
 
-```ts
-{
-  sourceBlockId,
-  sourceMessageIds,
+**事件卡记录发生过什么，并保留来源。**
 
-  mentionedAt,
-  happenedStart,
-  happenedEnd,
+同一个 Block 可以产生多条 Event，也可以没有需要提取的长期信息。每条事件除了内容，还保存来源 Block、来源消息，以及可确定的时间信息。
 
-  status,
-  participants,
-  eventType,
+时间信息需要区分两个含义：
 
-  supersedesEventIds,
-  conflictsWithEventIds
-}
-```
+| 时间 | 表示什么 |
+| --- | --- |
+| 提及时间 | 这件事什么时候在对话中被说到 |
+| 发生时间 | 事情实际发生或计划发生的时间 |
 
-其中：
+例如，用户在 5 月 6 日说“下周完成原型”，5 月 6 日是提及时间，“下周”描述的是计划完成时间。这条记录应保留计划性质，不能直接作为“原型已经完成”的证据。
 
-- `mentionedAt` 表示这件事什么时候在对话中被提到；
-- `happenedStart` / `happenedEnd` 表示事情实际发生或预计发生的时间；
-- `status` 可以区分已经发生、计划中、已取消或仍在持续的事件；
-- `supersedesEventIds` 和 `conflictsWithEventIds` 用于保留纠正和冲突关系。
+当时间无法确定时，保留原始表达和不确定性，方便之后回到来源核对。
 
-将“提及时间”和“发生时间”分开，可以避免把消息日期直接当成事件日期，也让系统有条件正确解析“上周”“下个月”等相对时间。
+**新事件通过补充、取代或冲突关系更新记忆。**
 
-L0–L2 校验完成后，Event 抽取会独立运行，不再等待块 `N+1`。抽取器可以读取前一个 Block 和最近可用的后续就绪 Block 作为上下文，但新增事实和引用必须来自目标块 `N`。
+项目讨论可能先后出现：
+
+> “这个项目使用 npm。”
+>
+> “我们改用 pnpm。”
+>
+> “下周完成原型。”
+
+这三条信息的作用不同：
+
+- “改用 pnpm”更新了包管理器选择，旧 npm 事件保留为历史。
+- “下周完成原型”补充了一项计划，不影响包管理器选择。
+- 如果出现无法同时成立、又不能确定哪条有效的说法，则保留冲突关系，供后续核实。
+
+旧事件的内容和来源不会被新事件覆盖，其有效状态和关联关系可以随新证据更新。因此，系统既能找到当前有效的信息，也能回答“以前是什么样、后来发生了什么变化”。
 
 <a id="current-state-graph"></a>
 
-### 3. 当前状态图谱与可审计检索
+**知识图谱根据事件整理当前信息和关系。**
 
-事件卡保存“发生过什么”。在此基础上，StrataGate 可以把人物、项目、组织、工具和地点的当前状态整理成图谱节点和有方向的关系。DeepSeek Harness 使用这条图谱原生路径。
+图谱将人物、项目、组织、工具和地点表示为节点，将“使用”“参与”“依赖”等联系表示为有方向的关系。节点属性和关系都保留来源 Event。
 
-图谱整理任务会单独保存进度。即使任务失败，也只需重试这一步，不必重新提取已经写入的事件。系统只有在确认事实或关系引用了本批次事件后才会保存，因此每条整理后的结论都能回到来源。状态发生变化时，旧结论会被标记为历史记录，而不是修改原始事件。
+在上述例子中，图谱可以把项目当前使用的包管理器更新为 pnpm，同时保留 npm 的历史状态。之后：
 
-`searchEvents()` 会分别按文字、参与者、类型、名称和时间等信息排序，再合并这些结果；`searchGraphNodes()` 则会在名称、别名、标签、状态、事实和关系中进行加权文字搜索。搜索只返回紧凑的相关事实，不会一次塞入整份大记录；如果文字完全不匹配，也不会随意返回候选结果。这些路径使用可复现的文字和结构化信号，不依赖向量或语义检索。
+- 问“项目现在使用什么”，可以先查当前图谱；
+- 问“什么时候改的”，可以查变更事件；
+- 问“为什么改”，可以进一步展开事件并回查原始讨论。
+
+图谱中的状态需要与来源一致。“下周完成原型”直接支持的是一项计划；图中展示的“原型开发中”或“负责人”等信息，需要相应事件提供额外依据。
+
+图谱更新作为独立任务执行并保存进度。更新失败时，可以单独重试，已经写入的事件和原始来源仍然保留。
 
 <a id="evidence-gate"></a>
 
-### 4. 证据门：相关不等于充分
+### 3. 证据门：检查检索结果是否足以回答当前问题
 
-普通检索系统通常在返回若干相似结果后，直接把它们交给回答模型。StrataGate 在检索和回答之间增加了一层固定协议：
+找到相关记忆之后，还需要判断它能否支持当前答案。StrataGate 通过一个固定、简短的评估结构，要求 Agent 明确说明证据是否充分，以及接下来应当做什么。
 
-```text
-verdict · evidence_refs · fit · missing · next_strategy
-```
+| 评估项 | 需要说明的内容 |
+| --- | --- |
+| `verdict` | 证据充分、部分充分，还是与问题不符 |
+| `evidence_refs` | 哪些检索结果支持当前判断 |
+| `fit` | 证据与问题具体匹配在哪里 |
+| `missing` | 还缺少哪些信息 |
+| `next_strategy` | 直接回答，还是继续搜索或展开 |
 
-每次检索后都要明确回答五个问题：
+例如，用户问：
 
-- 当前证据是 `sufficient`、`partial` 还是 `wrong`；
-- 哪些结果真正支持当前判断；
-- 证据与问题具体匹配在哪里；
-- 还缺少什么；
-- 下一步应该回答、继续搜索、展开事件，还是回查原始消息。
+> 为什么当初改用了 pnpm？
 
-只有同时满足以下条件，系统才接受 `sufficient`：
+检索结果只有：
 
-1. 至少一条证据来自当前指定的检索批次；
-2. `next_strategy` 明确为 `answer`；
-3. 判断使用固定、长度有界的结构，而不是不断增长的私有检索便签。
+> 项目已从 npm 改为 pnpm。
 
-如果判断为 `partial` 或 `wrong`，系统可以选择：
+这条结果确认了变更，却没有说明原因。Agent 应将其判断为部分充分，继续展开事件或回查原始对话，而不能仅凭工具选择推测当时的理由。
 
-```text
-search_events
-expand_event
-search_graph
-expand_graph_node
-search_raw_memory
-expand_block
-```
+证据门由模型判断内容是否充分，程序负责检查引用和流程约束：被引用的证据必须来自指定检索批次；接受 `sufficient` 时，需要有效证据引用，并明确选择回答。
 
-证据门不负责替应用完成整个 Agent loop。StrataGate 提供状态、约束和校验，具体模型调用、工具循环和最大检索预算仍由接入方控制。
+这些检查使检索过程可以追踪和核验，但模型仍可能误判证据。没有找到足够信息时，应继续查找，或在回答中明确说明无法确认。
+
+主动检索的循环和预算由接入方控制。图 1 中的“最多 4 次”表示示例评测配置，不是所有接入场景的固定限制。
 
 <a id="use-only-reinforcement"></a>
 
-### 5. 检索和强化分开
+### 4. 只强化实际使用的记忆：采用越多，之后衰减越慢
 
-一次事件被搜索到，不代表它真的帮助了答案。
+长期记忆也会随对话推进而衰减。这里变化的是 Event 的权重，它参与后续召回和排序；与短期 Block 不同，Event 不会因此逐级切换 L0–L5 展示层。
 
-因此，搜索只更新可观测的检索记录，不会直接增加记忆权重。回答完成后，应用需要显式调用：
+![图 3：StrataGate 长期记忆权重——自然衰减、仅检索不强化与采用后强化](docs/assets/cecc9d191a4b9bf22a479623e2ebdc1d.png)
 
-```ts
-await memory.recordMemoryUse({ eventIds, elementIds });
-```
+**新事件具有初始权重，未被采用时逐渐衰减。**
 
-只有真正被答案采用的事件，或图谱证据背后的来源事件，才会更新长期权重。仍使用旧版元素卡的接入方式也继续受到支持。
+长期 Event 的基础权重函数为：
 
-这样可以避免一个常见反馈循环：
+$$
+w(t,n)=\max\left(floor,e^{-\lambda(n)t}\right)
+$$
 
-```text
-某条记忆偶然排得靠前
-        ↓
-被频繁搜索到
-        ↓
-权重继续增加
-        ↓
-以后更容易排在前面
-```
+$$
+\lambda(n)=\frac{0.15}{1+1.5\ln(n)}
+$$
+
+其中：
+
+- $t$ 是当前轮次与上次采用轮次的差，新事件从创建时开始计算；
+- $n$ 是内部采用计数，初始化为 1，每次记录采用后增加 1；
+- $floor$ 是根据记忆重要程度设置的最低权重。
+
+长期权重衰减同样按对话轮次计算，而不是按现实时间计算。较低的权重可能降低一条记忆在后续召回中的优先级，但不会因衰减而删除它的历史记录。
+
+**被搜索到，不会触发强化。**
+
+检索命中只说明一条记忆可能相关。系统可以记录它何时被检索，但不会因此增加采用计数，也不会重置衰减起点。
+
+自动带入上下文的记忆同样不会因为被展示而获得强化。这样可以避免某条记忆仅因偶然排在前面，就通过反复出现不断提高自身权重。
+
+**记录为实际采用后，才更新权重。**
+
+Agent 确定用于最终回答的证据后，会提交采用回执。通过检查的 Event 增加采用计数，并把衰减起点更新到当前轮次。对于未被额外限制权重的普通活跃事件，此时权重回到 1。
+
+随着采用计数增加，公式中的衰减系数变小，同样经过一段对话后，它能保留更高的权重。因此，反复帮助回答的记忆会逐渐衰减得更慢。
+
+采用依据来自 Agent 提交的证据选择。程序检查证据是否属于对应批次、是否经过充分性评估，并通过回执避免同一次操作被重复执行；没有使用的检索结果不获得这次强化。
+
+**不同重要程度的记忆，可以保留不同的最低权重。**
+
+| 记忆类别 | 默认最低权重 |
+| --- | ---: |
+| 普通信息 | 0 |
+| 用户偏好 | 0.3 |
+| 身份信息 | 0.9 |
+| 安全信息 | 1.0 |
+
+此外，置顶记忆的有效权重保持为 1；被取代的事件通常设置较低的权重上限，避免旧状态持续占据较高优先级。
+
+这些权重表达的是记忆管理策略，不能当作事实正确率。权重较高的信息仍需要结合当前问题、最新状态和原始来源进行判断。
 
 <a id="external-memory-import"></a>
 
-### 6. 外部 AI 记忆迁移
+## 外部 AI 记忆迁移
 
 可以把另一个 AI 的记忆总结直接迁移到 StrataGate。`importExternalMemory()` 将导入拆成固定的五步：
 
@@ -311,78 +406,98 @@ verdict = sufficient
 
 - 事件卡负责快速定位；
 - 来源时间戳和原始消息负责最终核对；
-- 证据门阻止系统拿着不完整信息直接回答。
-
-## 这些设计是怎么形成的
+- 证据门要求 Agent 识别缺失信息，并在证据不足时继续查证。
 
-当前设计并不是一次性确定的。多轮实验里最有价值的不是轮次编号，而是暴露出的失败模式。
+## 实验结果
 
-| 发现的问题 | 实验观察 | 最终设计选择 |
-| --- | --- | --- |
-| 时间信息被压在摘要里，难以准确恢复 | 在早期同口径实验中，引入每块多事件和显式发生时间后，Temporal 从 18.92% 提升到 45.95% | 将提及时间与发生时间分开，并保留原始时间表达和来源消息 |
-| Agent 的检索便签越来越大 | 有界五字段证据门取得 77.63%；扩展为更大的结构化检索便签后降至 63.82% | 保持判断结构小、长度有界，并让代码校验关键约束 |
-| 证据不足时反复搜索同一批事件卡 | 早期端到端版本有 19 道题至少搜索三次事件卡，只答对 2 道；当前策略在同一批题中答对 15 道，其中 12 道使用原文回查 | 搜索没有新增证据时切换信息通道，而不是继续重复同一种搜索 |
+仓库公开的 R8 对比评测使用 LoCoMo 中的 `conv-26` 对话样本，包含 **419 条消息、35 个会话和 152 道问题**，覆盖 category 1–4。
 
-当前端到端版本相较早期版本：
+两个系统分别生成答案，再对每道题的答案进行 **10 次独立 Judge 评审**。这里的十次指评审重复次数，不代表十次完整系统运行。
 
-| 指标 | 早期版本 | 当前版本 | 变化 |
+| 指标 | StrataGate | Mem0 base | 差值 |
 | --- | ---: | ---: | ---: |
-| 10 次评审平均准确率 | 70.33% | **80.46%** | **+10.13 个百分点** |
-| 多数票正确 | 107 / 152 | **121 / 152** | **+14 题** |
-| 检索轮数 | 215 | **146** | **-32.1%** |
-| 证据判断调用 | 237 | **146** | **-38.4%** |
-| 总 Token | 6.69M | **4.09M** | **-38.9%** |
+| 10 次评审平均准确率 | **80.46%** | 63.22% | **+17.24 个百分点** |
+| 多数票正确 | **121 / 152（79.61%）** | 96 / 152（63.16%） | **+25 题** |
+| 时间类问题（Temporal） | **74.86%** | 34.59% | **+40.27 个百分点** |
+| 单跳问题（Single-hop） | **89.29%** | 75.14% | **+14.14 个百分点** |
+| 多跳问题（Multi-hop） | **66.56%** | 61.56% | +5.00 个百分点 |
+| 开放域问题（Open-domain） | 83.08% | **84.62%** | -1.54 个百分点 |
 
-这组结果说明，旧版本中重复事件搜索是一条明确的失败路径；改为在卡片证据不足时回到来源后，准确率和检索效率同时改善。
+两边使用相同的问题、顺序、答案模型、Judge 模型、评审提示词、解析器和评审次数，并分别重新构建记忆。记忆抽取、检索实现、embedding 使用方式和回答上下文存在差异，因此这里比较的是两套完整系统配置。
 
-不过，两次端到端运行之间还修改了软过滤、中英文同义表达匹配、结果结构和重新抽取的记忆状态。因此这是一组有价值的诊断证据，不是原文回查的单变量消融实验。
+这组结果仅覆盖 `conv-26`，不代表完整 LoCoMo 成绩，也不能单独证明短期记忆衰减、知识图谱或证据门中某一项机制带来的收益。各组件的独立作用仍需通过消融实验检验。
 
-R1–R8 的完整实验过程、模型与 Judge 变化、逐题迁移和协议边界见 [`docs/EVALUATION.md`](docs/EVALUATION.md)。
+完整协议、逐题结果及评审波动见 [评测文档](docs/EVALUATION.md)，汇总数据见 [机器可读评测结果](benchmarks/locomo-conv26-r8-final.json)。
+
+## 这些设计是怎么形成的
+
+多轮实验中的失败案例，帮助 StrataGate 逐步明确了记忆处理与检索策略：
+
+- **时间信息需要单独保存。** 仅靠摘要不容易恢复事件日期，因此事件卡区分提及时间与发生时间，并保留原始时间表达和来源。
+- **证据判断需要简短、明确。** 将判断限制在五个字段内，让 Agent 明确说明证据、缺口和下一步，也便于程序检查引用。
+- **反复搜索没有新增信息时，需要换一种查找方式。** 当事件卡缺少关键细节时，展开来源或检索原始消息，比重复搜索同一批卡片更有价值。
+
+R1–R8 的完整实验过程、版本差异和逐题分析保留在 [评测文档](docs/EVALUATION.md)中。不同轮次之间存在多项调整，这些观察用于解释设计选择，不作为单个组件效果的独立证明。
 
 ## 当前局限与下一步
 
-当前版本仍有 31 道多数票错误题。按最终可观察到的失败阶段划分：
+上述 R8 评测中，仍有 **31 道题被多数评审判为错误**。按可观察到的失败阶段划分：
 
-| 失败阶段 | 题数 | 暴露的问题 |
+| 失败阶段 | 题数 | 反映的问题 |
 | --- | ---: | --- |
-| 没有检索，直接回答错误 | 15 | 时间题、多跳题和列表题有时过早相信模型自身记忆 |
-| 证据门判为 `sufficient`，最终答案仍错 | 14 | 相关但不属于目标事件的材料被误判为充分，或列表答案不完整 |
-| 到检索上限仍只有 `partial` 证据 | 2 | 确实存在没有找到足够证据的情况，但并非当前主要瓶颈 |
+| 未发起检索，直接回答错误 | 15 | Agent 有时未意识到需要查找历史证据 |
+| 证据被判为充分，最终答案仍然错误 | 14 | 证据可能属于相邻事件，或不足以支持完整答案 |
+| 达到检索预算时，证据仍不充分 | 2 | 在给定预算内没有找到足够的信息 |
 
-这表明当前的主要问题已经不是“检索轮数不够”，而是系统是否应该发起检索，以及检索到的证据是否真的足以支持完整答案。
+这些结果说明，在该评测范围内，仍需改进何时发起检索，以及如何判断证据是否真正回答了问题。证据门能够约束引用和评估流程，但不能保证模型的语义判断或最终答案一定正确。
 
-下一步将进行：
+后续验证重点包括：
 
-1. 固定 memory state，分别消融原文回查、软过滤和事实级检索；
-2. 向回答模型直接提供 gold evidence，区分检索失败和回答推理失败；
-3. 在更多会话上重复同一套配对协议；
-4. 最终扩展到完整 LoCoMo 数据集。
+1. 固定模型和记忆状态，对短期衰减及关键检索机制分别进行消融，比较准确率、上下文占用和调用成本。
+2. 直接提供已知正确的来源证据，区分“没有找到证据”和“拿到证据仍推理错误”。
+3. 在更多对话样本上重复相同协议，再扩展到完整 LoCoMo 数据集。
 
 ## 当前状态
 
-StrataGate 目前是用于验证长期 Agent 记忆设计的研究型原型。
+StrataGate 已提供可安装使用的 DeepSeek Harness 插件，并通过共享的 TypeScript 核心引擎实现记忆管理。
+
+当前功能覆盖：
+
+- 自动采集已完成的对话与工具记录；
+- L0–L5 分层短期记忆、展示衰减和按需展开；
+- 带来源与时间的 Event，以及根据事件更新的知识图谱；
+- 自动激活相关长期记忆，以及主动搜索和来源回查；
+- 检索批次管理、证据评估与采用回执；
+- 长期权重衰减、采用强化和外部 AI 记忆导入。
+
+仓库包含自动化测试、实验记录和可追溯的评测结果。公共 API、模型接入和评测覆盖仍在迭代，进行自定义集成时应固定版本，并结合自己的使用场景验证。
+
+常规入口 `StrataGate.open()` 使用 SQLite 持久化记忆；`StrataGate.inMemory()` 用于显式选择的临时运行和测试。存储适配层支持中断恢复和一致性校验，具体约束见 [架构文档](docs/ARCHITECTURE.md)。
 
-仓库已经实现并验证了：
+## 什么情况下适合使用 StrataGate
+
+StrataGate 适合需要长期保持对话连续性，同时控制历史上下文占用的 Agent 工作流。例如：
 
-- 分层对话块及其衰减规则；
-- 带来源、时间和冲突关系的事件卡；
-- 独立可重试、保留事件来源的知识图谱整理任务；
-- 面向事件和图谱节点的 BM25/RRF 检索；
-- 保留原始导入内容的外部 AI 记忆迁移；
-- 相互隔离的并发检索批次与证据判断；
-- 长度有界、可由代码校验的证据门；
-- 检索命中与实际采用分离的权重机制；
-- 自动化测试、实验记录和机器可读评测结果。
+- **持续推进一个项目。** 近期讨论保留细节，较早的讨论逐渐简化，需要追问原因时再展开。
+- **跨会话延续工作。** 在新的对话中找回项目决定、用户偏好、计划和未完成事项。
+- **跟踪信息变化。** 同时了解项目当前状态和历史变更，避免把旧决定当作当前结论。
+- **核对记忆来源。** 回答依赖日期、原话或工具结果时，可以从事件和图谱追溯到原始记录。
+- **迁移已有记忆。** 将其他 AI 导出的信息整理为事件，并保留原始导入内容。
 
-当前公共 API、模型接入方式和评测覆盖仍在迭代，不建议将其视为已经稳定的生产 SDK。
+记忆可按项目、会话或全局范围组织。知识图谱界面主要用于查看当前信息、关系和来源，尚不以多人协作编辑或跨产品云端同步为主要功能。
 
-默认实现使用内存状态。仓库也提供可选的 SQLite adapter，用于实验状态持久化、中断恢复和一致性验证；它不会改变核心检索语义，相关约束见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
+DeepSeek Harness 用户可以从 [快速开始](#quick-start-deepseek-harness)安装。配置、记忆工具和恢复机制见 [插件使用说明](docs/DSH.zh-CN.md)。
 
 ## 代码入口
 
-需要 Node.js 22 或更高版本。
+本节面向开发者。直接使用 DeepSeek Harness 插件的用户，可以按照 [快速开始](#quick-start-deepseek-harness)安装，无需自行构建仓库。
+
+开发环境需要：
+
+- Node.js **22.19.0 及以上的 22.x 版本**，或 **24.0.0 及以上版本**；
+- 对应的版本声明为 `^22.19.0 || >=24.0.0`。
 
-在本地检出仓库后，可以运行：
+检出仓库后，在仓库根目录运行：
 
 ```bash
 npm install
@@ -391,31 +506,44 @@ npm test
 npm run build
 ```
 
-代码与文档的主要入口：
+主要代码入口如下：
 
-- [`packages/core/examples/basic.ts`](packages/core/examples/basic.ts)：核心引擎最小示例；
-- [`packages/core/src/store.ts`](packages/core/src/store.ts)：核心状态、Block/Event/图谱生命周期、导入和检索；
-- [`packages/core/src/events.ts`](packages/core/src/events.ts)：统一事件类型；
-- [`packages/core/src/elements.ts`](packages/core/src/elements.ts)：校验来源的元素投影与时间视图；
-- [`packages/core/src/graph.ts`](packages/core/src/graph.ts)：校验来源的知识图谱整理和状态维护；
-- [`packages/core/src/external-memory.ts`](packages/core/src/external-memory.ts)：外部记忆格式、提示词、解析和提取；
-- [`packages/core/src/search.ts`](packages/core/src/search.ts)：确定性 BM25 排序和 RRF 融合；
-- [`packages/core/src/retrieval.ts`](packages/core/src/retrieval.ts)：证据门规范化与约束校验；
-- [`packages/core/src/blocks.ts`](packages/core/src/blocks.ts)：分层规则与确定性精简；
-- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)：完整系统边界与实现不变量；
-- [`docs/EVALUATION.md`](docs/EVALUATION.md)：完整实验过程与失败分析。
+| 入口 | 内容 |
+| --- | --- |
+| [核心引擎示例](packages/core/examples/basic.ts) | 最小接入示例 |
+| [核心状态与生命周期](packages/core/src/store.ts) | Block、Event、图谱、导入、检索和采用记录 |
+| [分层与衰减规则](packages/core/src/blocks.ts) | L0–L5 层级、展示衰减和确定性精简 |
+| [长期权重](packages/core/src/weights.ts) | Event 衰减及最低权重计算 |
+| [事件类型](packages/core/src/events.ts) | 统一事件分类 |
+| [知识图谱](packages/core/src/graph.ts) | 来源校验、图谱更新与状态维护 |
+| [检索排序](packages/core/src/search.ts) | BM25 排序与 RRF 融合 |
+| [证据评估](packages/core/src/retrieval.ts) | 评估结构及引用约束 |
+| [外部记忆导入](packages/core/src/external-memory.ts) | 导入格式、提示词和解析 |
+| [旧版元素卡支持](packages/core/src/elements.ts) | 元素投影和历史时间视图 |
+
+持久化模式下，调用 `recordMemoryUse()` 需要提供非空、稳定的 `receiptId`。同一次采用操作重试时应复用该 ID，以避免重复强化。例如：
+
+```ts
+await memory.recordMemoryUse(
+  { eventIds: usedEventIds },
+  { receiptId: usageReceiptId },
+);
+```
 
-`packages/core/examples/basic.ts` 用于展示核心接口，而不是完整复现 benchmark 中的 Agent 工具循环。评测所使用的模型调用、工具编排和 Judge 协议见评测文档。
+其中，`usedEventIds` 是应用确定用于答案的事件，`usageReceiptId` 标识这一次采用操作。DSH 插件通过记忆工具和批次协议处理这一过程，插件用户无需手动调用该接口。
+
+核心示例用于展示 API 接入；完整评测中的模型调用、工具循环和 Judge 协议见 [评测文档](docs/EVALUATION.md)。
 
 ## 文档与复现
 
 | 资源 | 内容 |
 | --- | --- |
-| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 数据流、分层规则、事件/元素协议、检索、证据门约束、权重和存储不变量 |
-| [`docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md`](docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md) | 外部记忆导出格式、导入流程和接入示例 |
-| [`docs/EVALUATION.md`](docs/EVALUATION.md) | R1–R8 实验、模型敏感性、Mem0 对比、失败分析和报告边界 |
-| [`benchmarks/locomo-conv26-r8-final.json`](benchmarks/locomo-conv26-r8-final.json) | 当前结果、逐阶段统计、运行信息和源产物哈希 |
-| [`packages/core/examples/basic.ts`](packages/core/examples/basic.ts) | 最小代码示例 |
+| [DeepSeek Harness 使用说明](docs/DSH.zh-CN.md) | 安装、配置、界面、记忆工具和恢复机制 |
+| [架构文档](docs/ARCHITECTURE.md) | 分层规则、事件与图谱、检索、证据门、权重和存储约束 |
+| [外部记忆导入](docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md) | 导出格式、导入流程和接入示例 |
+| [完整评测](docs/EVALUATION.md) | 实验协议、版本演变、失败分析和结果范围 |
+| [评测汇总数据](benchmarks/locomo-conv26-r8-final.json) | 已公开运行的结果、统计和产物信息 |
+| [核心引擎示例](packages/core/examples/basic.ts) | 最小 API 接入示例 |
 
 ## 项目结构
 
@@ -429,21 +557,6 @@ docs/                   DSH 使用、架构和完整评测文档
 benchmarks/             机器可读实验结果
 ```
 
-## 什么情况下适合使用 StrataGate
-
-如果你同时需要以下多项能力，可以优先考虑 StrataGate：
-
-- 自动记录已完成对话和工具结果，形成**跨会话长期记忆**；
-- 使用本地 SQLite 保存记忆，**不需要单独部署记忆服务**；
-- 支持项目、会话或全局隔离，而不是把所有记忆混在一起；
-- 使用分层 Event 和知识图谱，同时保存“发生过什么”和“当前是什么状态”；
-- 召回结果可以展开回原始对话与工具输出，**来源可追溯**；
-- 在把记忆用于回答前，通过**证据充分性检查**判断当前材料是否真的够用。
-
-如果你最需要的是自由编辑记忆内容、跨产品的云端多人协作，或者只想维护一个简单的手写便签文件，应先考虑其他插件。StrataGate 已提供以查看和追溯为主的知识图谱界面，但它更适合自动、本地、证据可追溯的 Agent 记忆工作流，而不是多人知识库编辑。
-
-DeepSeek Harness 用户可以从[快速开始](#quick-start-deepseek-harness)安装。DSH 适配层的行为、工具、配置和失败恢复方式见 [DeepSeek Harness 插件中文文档](docs/DSH.zh-CN.md)。
-
 ## 参与贡献
 
 欢迎各种形式的贡献：修复问题、完善文档、增加集成，或探索更好的记忆与检索方案都可以。