stratagate-dsh 0.2.91 → 0.2.93

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 ### 近期对话保留细节，远期记忆逐渐简化。
 
-StrataGate 让 AI Agent 的短期记忆随对话推进逐渐变得简略，需要时可重新展开、找回原始细节；重要信息则沉淀为事件与知识图谱，持续记录历史变化与当前状态，供后续会话使用。
+StrataGate 是 DeepSeek Harness 的跨会话记忆插件。近期对话保留细节，较早对话逐渐简化，需要时可以找回原文；重要决定、偏好和计划会整理为长期记忆，供后续会话使用。
 
 [![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)
@@ -20,12 +20,10 @@ StrataGate 让 AI Agent 的短期记忆随对话推进逐渐变得简略，需
 
 [English](README.md) · [DeepSeek Harness 插件说明](docs/DSH.zh-CN.md) · [架构说明](docs/ARCHITECTURE.md) · [完整评测](docs/EVALUATION.md)
 
-<strong>当前公开结果：</strong>在 LoCoMo `conv-26` 上，StrataGate 经过 10 次独立评审的平均准确率为 <strong>80.46%</strong>，Mem0 base 为 <strong>63.22%</strong>。[查看测试范围与方法](#实验结果)。
+<strong>公开评测：</strong>在 LoCoMo 单个对话样本 `conv-26` 的 152 道题上，每个答案经过 10 次独立评审，平均判定正确率为 <strong>80.46%</strong>，Mem0 base 为 <strong>63.22%</strong>。[查看评测范围](#experimental-results)。
 
 </div>
 
-> **简单来说：** StrataGate 让近期对话保留细节，让较早的对话随对话推进逐渐简化；重要信息则整理为事件与知识图谱，供后续会话使用。原始记录始终保留，需要时可以重新展开、核对细节。
-
 ## 为什么选择 StrataGate？
 
 1. **短期记忆：随对话推进逐渐模糊，需要时重新展开。**
@@ -56,13 +54,6 @@ StrataGate 让 AI Agent 的短期记忆随对话推进逐渐变得简略，需
 
 开始使用：→ [快速开始](#quick-start-deepseek-harness)
 
-## 选择适合你的入口
-
-| 使用方式 | 适合谁 | 从哪里开始 |
-| --- | --- | --- |
-| **DeepSeek Harness 插件** | 希望自动获得本地记忆和可视化记忆界面的 DSH 用户 | [安装 `stratagate-dsh`](#quick-start-deepseek-harness) |
-| **TypeScript 核心库** | 正在开发自定义 Agent 或记忆接入的开发者 | [代码入口](#代码入口) |
-
 <a id="quick-start-deepseek-harness"></a>
 
 ## 快速开始：DeepSeek Harness
@@ -73,6 +64,8 @@ StrataGate 让 AI Agent 的短期记忆随对话推进逐渐变得简略，需
 dsh plugin --profile web add stratagate-dsh
 ```
 
+支持整个 DSH `0.2.0` 版本族：全部 Alpha、Beta、RC 和正式版（`>=0.2.0-0 <0.2.1-0`），同时保留此前支持的宿主版本。同属 `0.2.0` 的新版本无需因版本声明而等待插件更新。
+
 重启该 profile，之后照常使用 DSH 即可。StrataGate 会自动记录主 Agent 已完成的对话，在后台生成可搜索的记忆，并在 **DSH 设置 → StrataGate-AgentMemory** 中提供记忆界面。
 
 数据库默认保存在：
@@ -83,20 +76,7 @@ DSH_HOME/stratagate/memory.db
 
 移除插件不会删除数据库。截图、配置项、记忆工具和自动记录规则见 [DeepSeek Harness 插件中文说明](docs/DSH.zh-CN.md)。
 
-## 这些设计要解决什么问题
-
-随着对话不断积累，AI Agent 需要在有限的上下文中，同时处理眼前的任务、之前的讨论和长期有效的信息。
-
-近期讨论通常需要完整细节，较早的对话则可以先保留简短概括，等到需要时再展开。与此同时，用户偏好、项目决定和任务计划还会发生变化，需要区分历史记录与当前状态。StrataGate 围绕这些需求，分别管理短期记忆的展示、长期记忆的更新，以及检索后的判断和使用反馈。
-
-| 常见问题 | StrataGate 的处理方式 |
-| --- | --- |
-| 对话越来越长，历史细节持续占用上下文 | 将同一段对话保存为 L0–L5 分层视图；随着后续对话积累，较早的内容默认展示得更简略，需要时再展开 |
-| 重要信息分散在不同对话中，旧决定与新状态容易混淆 | 提取带来源和时间的 Event，用事件线保留历史，再通过知识图谱整理当前状态 |
-| 搜到了相关内容，却缺少回答问题所需的关键细节 | 通过证据门评估当前材料；不足时继续搜索、展开记忆或回查原文 |
-| 记忆仅因频繁被搜到，就不断获得更高权重 | 将检索与采用分开：长期权重随对话推进衰减，只有记录为实际采用的记忆才触发强化 |
-
-短期记忆衰减，让旧对话逐渐减少在当前上下文中呈现的细节；长期记忆及其权重机制，帮助 Agent 在后续会话中找回仍然有用的信息。两者都保留来源，使简化后的内容能够继续追溯和核对。
+上面的命令使用 `web` profile；如果使用其他 profile，请替换 `web`。开发者可直接查看[开发与文档](#code-entry-points)。
 
 <a id="how-stratagate-works"></a>
 
@@ -104,53 +84,21 @@ DSH_HOME/stratagate/memory.db
 
 ![图 1：StrataGate 整体处理流程——记忆形成、自动激活、主动检索与证据判断](docs/assets/aaed14b0b43a76334008117f6ca104af.png)
 
-StrataGate 的工作过程分为记忆形成、回答时找回，以及采用后的反馈。
-
-### 1. 对话积累，形成分层短期记忆
-
-每轮完成的对话及工具记录会先保存。DeepSeek Harness 插件默认每 **6 轮**封存一个 Block，用户可以调整这一大小；尚未达到边界的内容继续保留在当前对话中。
-
-每个 Block 保存 L0–L5 六种详细程度的视图，从标题索引、简短摘要到完整原始记录。后台处理完成后，Block 才开始参与衰减：随着同一会话中的后续就绪 Block 增加，较早的 Block 默认展示层逐渐变浅。
-
-这个过程减少的是当前上下文中呈现的历史细节，完整的 L5 原始记录仍然保留。→ [分层记忆](#layered-memory)
-
-### 2. 重要信息沉淀为 Event，并更新知识图谱
-
-对话中值得长期保留的决定、偏好、计划和变化，会被提取为 Event。每条事件记录内容、时间和来源，供之后的会话查找。
-
-知识图谱再根据这些事件，整理人物、项目、工具等实体的当前信息和关系。新事件可以补充或取代旧状态，历史事件及其来源继续保留。→ [事件卡](#event-cards) · [当前状态图谱](#current-state-graph)
-
-### 3. 回答前自动带入相关记忆，需要时主动检索
-
-每次主模型调用前，插件会根据当前问题和最近的对话，自动带入少量相关的长期 Event 与图谱信息，为回答提供背景。
-
-当前 DSH 实现最多带入 **4 条 Event 和 4 个图谱节点**，并受约 **900 tokens** 的总预算限制。当前会话的历史则通过分层 Block 和尚未封存的对话提供。
-
-如果已有上下文足够，Agent 可以直接回答；如果还缺少信息，就通过记忆工具搜索事件、图谱或原始消息，并按需展开更详细的内容。
-
-### 4. 主动检索后，检查证据是否足以回答
-
-找到相关记忆后，Agent 需要判断它是否真正回答了当前问题：哪些证据可以使用，还缺少什么，以及是否需要继续查找。
-
-例如，“项目使用 pnpm”可以回答当前采用什么工具，但不足以回答“当初为什么选择 pnpm”。遇到这种情况，Agent 应展开相关事件或回查原始讨论。
+1. **保存对话。** 若干轮连续对话组成一个记忆块（Block），保存为从索引到原文的六种视图。
+2. **提取长期信息。** 决定、偏好、计划或变化被整理为长期事件（Event），保留时间与来源；知识图谱据此整理当前状态。
+3. **回答时找回。** 插件自动带入少量相关记忆；信息不足时，Agent 搜索事件、图谱或原始消息，并判断证据是否够用。
+4. **记录实际使用。** 最终答案选作证据的 Event 会记录为一次“采用”，用于更新长期权重。
 
-证据门要求模型明确给出这份判断，并由代码检查证据引用和流程约束。证据仍然不足时，Agent 需要继续查找，或明确说明无法确认。→ [证据门](#evidence-gate)
-
-### 5. 记录实际采用的证据，更新长期权重
-
-搜索命中或自动带入上下文，不会触发记忆强化。
-
-当 Agent 确定哪些证据用于最终回答时，会提交采用回执。被记录为实际采用的 Event 更新采用计数和衰减起点；采用次数越多，之后衰减越慢。没有采用的搜索结果不会获得这次强化。→ [只强化实际使用的记忆](#use-only-reinforcement)
-
-例如，用户先决定“项目使用 npm”，后来改为“项目使用 pnpm”。StrataGate 会保留这两次决定，并在知识图谱中更新当前选择。之后询问“现在用什么”，可以从当前状态中找到答案；询问“什么时候改的、为什么改”，则可以沿 Event 回到当时的对话，核对时间和原因。
-
-[查看一次从事件卡回查原始消息的检索示例](#一次真实的检索)。
+自动召回目前最多带入 4 条 Event 和 4 个图谱节点，总预算约 900 tokens。当前会话另由分层 Block 和尚未封存的对话提供。
 
 ## 核心设计
 
-StrataGate 分别管理对话的展示层级、长期信息的更新、检索证据的判断，以及记忆被采用后的反馈。
+| 机制 | 变化的内容 | 保留的内容 |
+| --- | --- | --- |
+| 短期记忆简化 | 旧 Block 默认使用哪个 L0–L5 视图 | L5 原始对话与工具记录 |
+| 长期权重衰减 | Event 在后续召回中的优先级 | Event 历史及其来源 |
 
-其中，**短期记忆衰减决定旧对话展示得多详细，长期记忆权重影响信息在后续召回中的优先级**。这两种变化都不会因衰减而删除原始来源。
+两者都随对话进度变化：短期按就绪 Block 距离计算，长期按对话轮次计算。放置几天本身不会触发这两种衰减。
 
 <a id="layered-memory"></a>
 
@@ -175,6 +123,11 @@ DeepSeek Harness 插件默认每 **6 轮**完整对话封存一个 Block，一
 | L4 | 去除内部记录的近原文对话 | 过滤 system 消息；用户和助手正文只裁剪首尾空白并添加角色标签；可识别的工具记录保留名称和结果摘要 |
 | L5 | 原始消息与工具记录 | 查证来源及具体细节 |
 
+L0–L2 由模型概括；L3/L4 按固定规则删减寒暄、重复内容和工具记录，具体规则见下方。短期衰减按后续就绪 Block 的数量推进，不按现实中经过的天数计算。
+
+<details>
+<summary>具体精简规则、衰减公式与层级阈值</summary>
+
 L0–L2 由模型概括生成；L3、L4 不调用模型改写，而是由程序按以下固定规则生成：
 
 - **L4：** 删除 system 消息；用户和助手正文只裁剪首尾空白并添加 `User`、`Assistant` 等角色标签。对于能够识别的结构化工具记录，只保留工具名称和最长 160 字符的结果摘要，省略原始 `arguments`、`params`、`input` 和 `request`；无法识别为工具 JSON 的 tool 正文保持原样。
@@ -206,6 +159,8 @@ Block 的展示变化由指数衰减控制：
 
 图中的层级变化用于展示趋势，实际变化由衰减参数和层级阈值共同决定，并非每新增一个 Block 就下降一级。
 
+</details>
+
 **需要细节时，可以重新展开。**
 
 假设某段旧对话目前只显示：
@@ -224,7 +179,7 @@ Block 的展示变化由指数衰减控制：
 
 短期记忆保留一段讨论的上下文，长期记忆则把值得在后续会话中继续使用的信息提取出来。StrataGate 用 Event 记录决定、偏好、计划和变化，再根据这些事件整理知识图谱。
 
-![图 4：StrataGate 长期记忆更新——事件提取、历史关系与当前状态图谱](docs/assets/fc07e5b6e1cc07c115faa773a2718aa9.png)
+![图 3：StrataGate 长期记忆更新——事件提取、历史关系与当前状态图谱](docs/assets/fc07e5b6e1cc07c115faa773a2718aa9.png)
 
 **事件卡记录发生过什么，并保留来源。**
 
@@ -309,23 +264,9 @@ Block 的展示变化由指数衰减控制：
 
 长期记忆也会随对话推进而衰减。这里变化的是 Event 的权重，它参与后续召回和排序；与短期 Block 不同，Event 不会因此逐级切换 L0–L5 展示层。
 
-![图 3：StrataGate 长期记忆权重——自然衰减、仅检索不强化与采用后强化](docs/assets/cecc9d191a4b9bf22a479623e2ebdc1d.png)
-
-**新事件具有初始权重，未被采用时逐渐衰减。**
-
-长期 Event 的基础权重函数为：
-
-<p align="center"><strong>w(t,n) = max(floor, e<sup>−λ(n)t</sup>)</strong></p>
-
-<p align="center"><strong>λ(n) = 0.15 / (1 + 1.5 ln(n))</strong></p>
-
-其中：
-
-- `t` 是当前轮次与上次采用轮次的差，新事件从创建时开始计算；
-- `n` 是内部采用计数，初始化为 1，每次记录采用后增加 1；
-- `floor` 是根据记忆重要程度设置的最低权重。
+![图 4：StrataGate 长期记忆权重——自然衰减、仅检索不强化与采用后强化](docs/assets/cecc9d191a4b9bf22a479623e2ebdc1d.png)
 
-长期权重衰减同样按对话轮次计算，而不是按现实时间计算。较低的权重可能降低一条记忆在后续召回中的优先级，但不会因衰减而删除它的历史记录。
+未被用于答案的 Event 权重随对话轮次逐渐降低，可能影响后续召回的排序，但历史记录仍然保留。
 
 **被搜索到，不会触发强化。**
 
@@ -354,60 +295,52 @@ Agent 确定用于最终回答的证据后，会提交采用回执。通过检
 
 这些权重表达的是记忆管理策略，不能当作事实正确率。权重较高的信息仍需要结合当前问题、最新状态和原始来源进行判断。
 
-<a id="external-memory-import"></a>
+<details>
+<summary>长期权重公式与计数含义</summary>
 
-## 外部 AI 记忆迁移
+**新事件具有初始权重，未被采用时逐渐衰减。**
 
-可以把另一个 AI 的记忆总结直接迁移到 StrataGate。`importExternalMemory()` 将导入拆成固定的五步：
+长期 Event 的基础权重函数为：
 
-```text
-外部 AI 总结
-    ↓ extractor：提取候选 Event
-    ↓ searchEvents：每个候选只检索现有 Event 的 Top-K
-    ↓ decider：ADD / MERGE / SUPERSEDE / CONFLICT / IGNORE
-    ↓ 写入新 Event，保留旧 Event 与来源链
-    ↓ 仅为新写入的规范 Event 创建图谱投影任务
-```
+<p align="center"><strong>w(t,n) = max(floor, e<sup>−λ(n)t</sup>)</strong></p>
+
+<p align="center"><strong>λ(n) = 0.15 / (1 + 1.5 ln(n))</strong></p>
+
+其中：
 
-库导出 `EXTERNAL_MEMORY_EXPORT_PROMPT_ZH_CN`、`EXTERNAL_MEMORY_DECIDER_PROMPT_ZH_CN` 和 `externalMemoryJsonExtractor`，可让外部 AI 输出可校验的 `stratagate.external-memory.v2` JSON，再由本地模型从五种处理方式中选择。v2 将记忆性质与内容分类分开；时间字段严格区分“被提及时间”和“实际发生时间”。日期不确定时，系统会省略日期并保留原始说法，不会根据当前日期或聊天顺序猜测。
+- `t` 是当前轮次与上次采用轮次的差，新事件从创建时开始计算；
+- `n` 是内部采用计数，初始化为 1，每次记录采用后增加 1；
+- `floor` 是根据记忆重要程度设置的最低权重。
 
-完整接入示例和提示词说明见 [`docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md`](docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md)。DeepSeek Harness 管理界面会先预览导入，JSON 不合格时使用模型兜底恢复，确定性忽略完全重复项，并让当前模型结合 Top-K 本地匹配选择新增、合并、取代、冲突或忽略。导入分析及逐条进度会持久化，关闭后重新打开页面可继续查看；高置信度判断自动采用，低置信度项可人工选择具体动作；提交后可按批次撤销。
+长期权重衰减同样按对话轮次计算，而不是按现实时间计算。较低的权重可能降低一条记忆在后续召回中的优先级，但不会因衰减而删除它的历史记录。
 
-新事件可以取代旧事件，但旧事件及其来源仍然保留。遗忘可以让事件退出搜索，同时不破坏来源链路。
+</details>
 
-## 一次真实的检索
+<a id="external-memory-import"></a>
 
-LoCoMo 中有一道题询问 Caroline 在什么时候进行了学校演讲。
+## 外部 AI 记忆迁移
 
-事件卡已经找到了“学校演讲”，但卡片本身没有包含足够的日期信息：
+可以导入其他 AI 导出的记忆总结。StrataGate 将重要信息整理为 Event，与已有记忆比较，并保留原始导入内容供追溯。
 
-```text
-search_events
-        ↓
-命中“学校演讲”事件卡
-        ↓
-事件相关，但没有具体日期
-verdict = partial
-missing = 发生日期
-        ↓
-search_raw_memory
-        ↓
-找到 2023-06-09 的原始消息
-其中写着 “last week”
-        ↓
-结合消息时间解析相对日期
-verdict = sufficient
-        ↓
-回答
-```
+DSH 管理界面提供导入预览：重复内容可以忽略，变化可以新增、合并或取代旧状态，不确定的关系可以标为冲突。低置信度项可人工选择处理方式，提交后可按批次撤销。旧事件及其来源仍会保留。
+
+导出格式、提示词与接入示例见[外部记忆导入说明](docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md)。
+
+## 一次真实的检索
 
-这个过程里：
+LoCoMo 中有一道题询问 Caroline 在什么时候进行了学校演讲。检索过程是：
 
-- 事件卡负责快速定位；
-- 来源时间戳和原始消息负责最终核对；
-- 证据门要求 Agent 识别缺失信息，并在证据不足时继续查证。
+1. 搜索事件，找到“学校演讲”事件卡，但没有具体日期。
+2. Agent 判断证据部分充分，指出缺少发生日期，继续检索原始消息。
+3. 找到 2023-06-09 的消息，其中写着“last week”。
+4. 结合消息时间理解“上周”，得到足够的时间依据后回答。
 
-## 实验结果
+事件卡帮助定位，原始消息和时间戳帮助核对；证据门要求 Agent 识别缺口，继续查证。
+
+<a id="实验结果"></a>
+<a id="experimental-results"></a>
+
+## 评测结果与边界
 
 仓库公开的 R8 对比评测使用 LoCoMo 中的 `conv-26` 对话样本，包含 **419 条消息、35 个会话和 152 道问题**，覆盖 category 1–4。
 
@@ -428,18 +361,6 @@ verdict = sufficient
 
 完整协议、逐题结果及评审波动见 [评测文档](docs/EVALUATION.md)，汇总数据见 [机器可读评测结果](benchmarks/locomo-conv26-r8-final.json)。
 
-## 这些设计是怎么形成的
-
-多轮实验中的失败案例，帮助 StrataGate 逐步明确了记忆处理与检索策略：
-
-- **时间信息需要单独保存。** 仅靠摘要不容易恢复事件日期，因此事件卡区分提及时间与发生时间，并保留原始时间表达和来源。
-- **证据判断需要简短、明确。** 将判断限制在五个字段内，让 Agent 明确说明证据、缺口和下一步，也便于程序检查引用。
-- **反复搜索没有新增信息时，需要换一种查找方式。** 当事件卡缺少关键细节时，展开来源或检索原始消息，比重复搜索同一批卡片更有价值。
-
-R1–R8 的完整实验过程、版本差异和逐题分析保留在 [评测文档](docs/EVALUATION.md)中。不同轮次之间存在多项调整，这些观察用于解释设计选择，不作为单个组件效果的独立证明。
-
-## 当前局限与下一步
-
 上述 R8 评测中，仍有 **31 道题被多数评审判为错误**。按可观察到的失败阶段划分：
 
 | 失败阶段 | 题数 | 反映的问题 |
@@ -450,44 +371,20 @@ R1–R8 的完整实验过程、版本差异和逐题分析保留在 [评测文
 
 这些结果说明，在该评测范围内，仍需改进何时发起检索，以及如何判断证据是否真正回答了问题。证据门能够约束引用和评估流程，但不能保证模型的语义判断或最终答案一定正确。
 
-后续验证重点包括：
-
-1. 固定模型和记忆状态，对短期衰减及关键检索机制分别进行消融，比较准确率、上下文占用和调用成本。
-2. 直接提供已知正确的来源证据，区分“没有找到证据”和“拿到证据仍推理错误”。
-3. 在更多对话样本上重复相同协议，再扩展到完整 LoCoMo 数据集。
-
-## 当前状态
-
-StrataGate 已提供可安装使用的 DeepSeek Harness 插件，并通过共享的 TypeScript 核心引擎实现记忆管理。
-
-当前功能覆盖：
-
-- 自动采集已完成的对话与工具记录；
-- L0–L5 分层短期记忆、展示衰减和按需展开；
-- 带来源与时间的 Event，以及根据事件更新的知识图谱；
-- 自动激活相关长期记忆，以及主动搜索和来源回查；
-- 检索批次管理、证据评估与采用回执；
-- 长期权重衰减、采用强化和外部 AI 记忆导入。
+R1–R8 的设计演变、逐题分析与后续验证方向见[完整评测](docs/EVALUATION.md)。
 
-仓库包含自动化测试、实验记录和可追溯的评测结果。公共 API、模型接入和评测覆盖仍在迭代，进行自定义集成时应固定版本，并结合自己的使用场景验证。
+## 使用范围与成本
 
-常规入口 `StrataGate.open()` 使用 SQLite 持久化记忆；`StrataGate.inMemory()` 用于显式选择的临时运行和测试。存储适配层支持中断恢复和一致性校验，具体约束见 [架构文档](docs/ARCHITECTURE.md)。
+记忆可以按项目、会话或全局范围组织。知识图谱界面用于查看信息、关系与来源；多人协作编辑和跨产品云端同步不是主要功能。
 
-## 什么情况下适合使用 StrataGate
+分层视图减少的是回答时带入的历史上下文。后台生成摘要、提取 Event 和整理图谱仍会调用模型，因此不能把上下文减少直接等同于总 Token 或费用下降；工具记录较多时，后台成本尤其需要结合实际使用量评估。
 
-StrataGate 适合需要长期保持对话连续性，同时控制历史上下文占用的 Agent 工作流。例如：
+公共 API、模型接入和评测覆盖仍在迭代，自定义集成应固定版本并验证自己的场景。证据门要求模型说明依据，但不能保证判断和答案永远正确。
 
-- **持续推进一个项目。** 近期讨论保留细节，较早的讨论逐渐简化，需要追问原因时再展开。
-- **跨会话延续工作。** 在新的对话中找回项目决定、用户偏好、计划和未完成事项。
-- **跟踪信息变化。** 同时了解项目当前状态和历史变更，避免把旧决定当作当前结论。
-- **核对记忆来源。** 回答依赖日期、原话或工具结果时，可以从事件和图谱追溯到原始记录。
-- **迁移已有记忆。** 将其他 AI 导出的信息整理为事件，并保留原始导入内容。
+<a id="代码入口"></a>
+<a id="code-entry-points"></a>
 
-记忆可按项目、会话或全局范围组织。知识图谱界面主要用于查看当前信息、关系和来源，尚不以多人协作编辑或跨产品云端同步为主要功能。
-
-DeepSeek Harness 用户可以从 [快速开始](#quick-start-deepseek-harness)安装。配置、记忆工具和恢复机制见 [插件使用说明](docs/DSH.zh-CN.md)。
-
-## 代码入口
+## 开发与文档
 
 本节面向开发者。直接使用 DeepSeek Harness 插件的用户，可以按照 [快速开始](#quick-start-deepseek-harness)安装，无需自行构建仓库。
 
@@ -505,36 +402,6 @@ npm test
 npm run build
 ```
 
-主要代码入口如下：
-
-| 入口 | 内容 |
-| --- | --- |
-| [核心引擎示例](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 },
-);
-```
-
-其中，`usedEventIds` 是应用确定用于答案的事件，`usageReceiptId` 标识这一次采用操作。DSH 插件通过记忆工具和批次协议处理这一过程，插件用户无需手动调用该接口。
-
-核心示例用于展示 API 接入；完整评测中的模型调用、工具循环和 Judge 协议见 [评测文档](docs/EVALUATION.md)。
-
-## 文档与复现
-
 | 资源 | 内容 |
 | --- | --- |
 | [DeepSeek Harness 使用说明](docs/DSH.zh-CN.md) | 安装、配置、界面、记忆工具和恢复机制 |
@@ -544,17 +411,9 @@ await memory.recordMemoryUse(
 | [评测汇总数据](benchmarks/locomo-conv26-r8-final.json) | 已公开运行的结果、统计和产物信息 |
 | [核心引擎示例](packages/core/examples/basic.ts) | 最小 API 接入示例 |
 
-## 项目结构
+核心实现位于 `packages/core/`，DSH 适配层位于 `src/`。分层规则见 [blocks.ts](packages/core/src/blocks.ts)，长期权重见 [weights.ts](packages/core/src/weights.ts)。
 
-```text
-src/                    DeepSeek Harness Host 与 Web client 适配层
-tests/                  DeepSeek Harness 集成测试
-cordis.patch.yml        根目录 DSH bundle 清单
-packages/core/          共享记忆引擎、核心测试和示例
-integrations/workbuddy/ WorkBuddy Host Adapter 与 MCP 接入
-docs/                   DSH 使用、架构和完整评测文档
-benchmarks/             机器可读实验结果
-```
+核心库的 `StrataGate.open()` 使用 SQLite，`StrataGate.inMemory()` 用于临时运行和测试。持久化模式下，`recordMemoryUse()` 必须提供稳定的 `receiptId`；同一次采用操作重试时复用该 ID，避免重复强化。参见[架构说明](docs/ARCHITECTURE.md)。
 
 ## 参与贡献