长期记忆抽取 hy-sde/dsh-memory-extraction

[!NOTE]
📦 本插件位于 dsh-plugins monorepo —— 问题与 pull request 请提到那里。
npm：@hy-sde-org/dsh-memory-extraction

dsh-memory-extraction —— 为 DeepSeek Harness 自动提取长期记忆

独立包 @hy-sde-org/dsh-memory-extraction：在压缩检查点自动提取长期记忆，服务于 DeepSeek Harness。每经过一个 compaction/summary 边界，一条有界、fail-open 的流水线就会投影出该检查点区间的用户撰写文本，借助辅助模型调用提出并规范化持久事实（证据锚定、提议/准入/规范化、按会话游标、跨会话证据下限），再把准入的事实提交到 retain/learn 写入的同一个项目记忆库 —— 对显式记忆面严格增量（retain / recall / reflect / memory_edit / learn 仍是面向模型的路径）。

| 标识 | 值 |
| 包 | @hy-sde-org/dsh-memory-extraction |
| 插件 id | memory-extraction（手动添加的那一行 —— 包本身不带 bundle 行） |
| 平面 | host —— 注入 memory + llm，不发布任何东西 |
| 提交接缝 | ctx.memory（提取出的事实以 source: 'memory_extract' 落地） |

基于 Apache Maka（Apache License 2.0，© the Apache Software Foundation） —— 记忆提取引擎（证据投影、提议/准入/规范化、控制存储、压缩触发器）移植自 Maka（No. 2），上游为 packages/runtime/src/memory-extraction.ts。DSH 集成部分衍生自 DeepSeek Harness 代码库（MIT，© 2026 DeepSeek）；每个衍生文件都在头部标注了出处。见 THIRD-PARTY-NOTICES.md。

为什么需要它

没有这个包，持久记忆只有在模型记得调用 retain/learn 时才会增长。这个引擎改为盯住每一个压缩检查点：用户在整个会话中陈述的事实会被投影、验证并自动提交，于是记忆无需手动自律也能挺过压缩。承载核心作用的规则移植自 Maka，并由引擎强制执行：

- 证据只取用户撰写的文本 —— 助手文本仅供解读；工具调用/结果和推理过程不透明。证据有界（JSON 12 000 字符 / 每条记录 4 000 字符），溢出时 fail-closed。
- 准入经过验证 —— 提议 → 准入（对有界证据做逐字引用检查 + 拒绝密钥）→ 规范化 → 再次准入，每个区间最多 3 次辅助模型调用，超时 60 s；
- 故障被隔离（运行时边界 fail-open —— 压缩永远不会被阻塞）。
- 游标只移动到已提交的边界 —— 写入顺序是 items → cursor → receipt，所以崩溃绝不会导致重复处理；operation id 是确定性的（memory_ + {sessionId, trigger, boundarySeq} 的 sha256），receipt 让重放变成 no-op。
- 子代理被排除 —— 子智能体的压缩永远不会提取（excludeSubagents: true 默认）。
- 跨会话证据门槛 —— 一个事实只有在 minGapEvidence 个不同会话（默认 2）提出同一个持久事实后才会提交；未经证实的事实留在 gap ledger 里作为 open pending facts，并在 gapLedgerMaxAgeMs（默认 90 d）后过期。

前置条件

- Node.js 22.19 或更新版本，且 PATH 上有 npm 和 pnpm；
- 一个 DeepSeek Harness 发行版，带有 0.2.0-rc.2 peer 范围 —— @deepseek-ai/cordis ~4.0.4 以及 @deepseek-ai/dsh-compaction、 @deepseek-ai/dsh-llm、@deepseek-ai/dsh-session、@deepseek-ai/dsh-storage ^0.2.0-rc.2 —— 包括标准 dsh 命令行；
- 已挂载 @hy-sde-org/dsh-memory 插件 ——提取结果提交到它的 ctx.memory bank；
- 一个暴露 kv facet 的存储后端 —— 两个随附后端（sqlite 和 storage-json）都支持。别的什么都不需要：不需要 API key（辅助调用复用会话路由到的模型，除非你配置 provider/model）。

继续之前先安装 Harness 命令行和 pnpm：

npm install --global @deepseek-ai/dsh pnpm
dsh --version

快速开始

这个包不带 dsh.bundle.patch，所以挂载分两步：安装包，然后手动往配置档的 host composition 里加一行。

路线 A —— 已发布的 npm 包

dsh plugin --profile web add @hy-sde-org/dsh-memory-extraction

因为包没有声明 bundle，命令行会把它装成普通配置档依赖，并警告 declares no dsh.bundle — installed as a plain dependency, not a profile layer。不会自动应用任何行 —— 把它加到 host composition（配置档的 cordis.patch.yml 补丁层，在任何会话之前加载）：

- insert:
- id: memory-extraction
name: '@hy-sde-org/dsh-memory-extraction'
config:
backend: sqlite # storage backend hosting the control unit (default sqlite)
enabled: true # master switch (default true)
excludeSubagents: true # child-agent compactions never extract (default true)
provider: <cheap provider id> # optional; unset uses the session's routed model config
model: <cheap model id> # optional; unset uses the session's routed model config
importance: 0.5 # bank importance for auto-extracted facts (default 0.5)
dedupe: true # probe the bank before committing duplicates (default true)
timeoutMs: 60000 # auxiliary call timeout (default 60000)
minGapEvidence: 2 # 事实提交前需要的不同会话数（默认 2；0 关闭下限） gapLedgerMaxAgeMs: 7776000000 # 超过这个时间的目击不再计数（默认 90 天，单位毫秒）

路线 B —— 从源码安装（验证这份 checkout，或改插件）

git clone git@github.com:hy-sde/dsh-plugins.git
cd dsh-plugins
pnpm install
PACKAGE_TARBALL="$(cd dsh-memory-extraction/packages/memory-extraction && pnpm pack --pack-destination /tmp | tail -n 1)"
dsh plugin --profile web add "$PACKAGE_TARBALL"

pnpm pack 会跑常规的 prepack 构建，产出一个包含 dist/ 的 tarball。安装后就是一个普通的配置档依赖，和路线 A 完全一样 —— 同样按上面的方式加上 host-composition 那一行。

验证组合后的配置

dsh web --dump-config

组合出的树里必须能看到 memory-extraction 这一行，加载的是 @hy-sde-org/dsh-memory-extraction。

运行

dsh web

下一个包含用户撰写文本的 compaction 检查点之后，引擎会提出、验证并把持久事实提交进项目记忆库，带上 source: 'memory_extract' —— 让智能体 recall 或 reflect，自动抽取的条目就在那里。插件异步启动；如果配置的存储后端缺失，它会记日志并保持静默，而不是让组合失败。

卸载

删掉你加到 host composition 里的那一行，然后：

dsh plugin --profile web remove @hy-sde-org/dsh-memory-extraction

这个包做什么

引擎是 host-plane 的 Cordis 插件（inject: ['memory', 'llm']，不发布任何东西）：一个进程打开一次 memory_extraction 控制单元（表 cursors / receipts / failures / gaps，建在 KvUnit 上），并通过一个不带作用域的 ctx.on('session/event') 监听器观察每个会话的事件。每到 compaction/summary 边界，它就运行按会话串行的流水线 —— 项目证据、提出、准入、规范化、再准入、提交 —— 并且从不阻塞 compaction 监听器。提交的事实走 ctx.memory 提交面，带一次去重探测，落进 retain/learn 写入的同一个库；延迟的事实留在 gap ledger 里保持目击状态，并展示给后续的提出流程（模型引用 gapId，而不是另造一个转述）。引擎本身是纯的，不依赖 cordis 也能测试：

import { MemoryExtractionEngine } from '@hy-sde-org/dsh-memory-extraction'

const engine = new MemoryExtractionEngine(ports) // readGate/readEvents/cursor+receipt+failure/commitItems/generate
const result = await engine.execute(snapshot) // never throws; idempotent by operation id

配置

所有选项都是可选的；这一行的 config: 会补上默认值。

| 选项 | 默认值 | 用途 |
| backend | sqlite | 承载控制单元的存储后端；必须暴露 kv facet |
| enabled | true | 总开关 |
| excludeSubagents | true | 子代理的压缩永不提取 |
| provider、model | 未设置 | 辅助模型路由；未设置时沿用会话路由的请求头。大规模部署建议用便宜的辅助模型 |
| importance | 0.5 | 自动提取事实的 bank 重要度 |
| dedupe | true | 提交重复项前先探测 bank |
| timeoutMs | 60000 | 每次辅助调用超时；设置范围后最多发起 3 次辅助调用 |
| minGapEvidence | 2 | 事实提交前需出现的不同会话数；0 关闭该下限 |
| gapLedgerMaxAgeMs | 7776000000 | 早于此时长的出现记录不再计数（90 天）；0 关闭该账本 |

兼容性

| 组件 | 支持的契约 |
| Node.js | 22.19 或更新（engines.node >=22.19.0） |
| DeepSeek Harness | 0.2.0-rc.2 对等范围（@deepseek-ai/cordis ~4.0.4；dsh-compaction、dsh-llm、dsh-session、dsh-storage ^0.2.0-rc.2） |
| Memory bank | @hy-sde-org/dsh-memory（ctx.memory 接缝） |
| 存储后端 | 必须暴露 kv facet —— 自带的 sqlite 和 storage-json 都支持 |

上游接缝契约变更需要发布新包版本并做契约评审。

开发

pnpm install
pnpm check # strict typecheck of packages/memory-extraction
pnpm test # vitest run
pnpm build # tsc -> dist
pnpm pack:all # pack the publishable package

引擎是纯状态机（src/engine.ts），运行在注入的端口之上，所以状态机、证据投影和解析器都能脱离 cordis 测试；src/runtime.ts 是唯一的主机接线。实现导览见 packages/memory-extraction/README.md（English | ）。

许可与署名

本包采用 MIT 许可 —— 见 LICENSE。源自 DeepSeek Harness 代码库的代码为 MIT（© 2026 DeepSeek）；memory-extraction 引擎移植自 Apache Maka (No. 2)，遵循 Apache License 2.0（© the Apache Software Foundation）—— Apache License 2.0 文本适用于移植的 Maka 模块，仓库其余部分为 MIT。上游声明文本转载于 THIRD-PARTY-NOTICES.md。

本插件是独立的可安装包；harness 仍归其自身项目所有。