dsh-agent-memory v0.7.2:面向 DeepSeek Harness 的跨会话长期记忆插件

[Culeot]

摘要

DeepSeek Harness(DSH)当前缺乏跨会话长期记忆:现有能力(storage domain、session-query-sqlite、agent-instructions)均为文件型或会话级存储,会话间沉淀的动态知识——用户偏好、既定决策、历史教训——无法跨会话保留。本文实现 dsh-agent-memory v0.7.2:基于 DSH 原生 cordis 机制的跨会话记忆插件,提供 schema 校验持久化、确定性检索、容量淘汰/近重复合并/TTL/删除守卫治理,以及按需注入与自我纠错闭环。已发布 npm(dsh-agent-memory@0.7.2),源码 GitHub(Culeot/dsh-agent-memory,MIT)。

1. 背景

DSH 现有记忆能力:

• dsh-agent-instructions:静态文件规则(AGENTS.md),人工维护;
• dsh-goal:会话内目标,不跨会话;
• dsh-session-query-sqlite:历史会话查询,非知识沉淀;
• 社区方案([Idea] dsh-memory：跨会话长期记忆插件（补上 memory 能力缺口） #192、长期记忆 #484、dsh-plugins: bounded cross-session memory (MEMORY.md/USER.md) and skill lifecycle curation, ported from hermes-agent #525):MEMORY.md 自维护文件,无 schema、无治理、检索依赖模型逐次翻文件。

动态知识在上述架构中无处安放,每次新会话从零开始。

2. 设计

2.1 架构

• 记忆库:domain 全量记录,6 个模型工具按需读写,是唯一事实源;
• 按需注入:每轮模型执行前,以当前消息 recall 相关记忆注入(取代早期版本每轮广播热记忆的机制,v0.2.0 起);
• 底层逻辑:复用 preset persona 与 AGENTS.md 的协议规则,不重复实现。

注:早期版本的"热记忆广播"(每轮注入固定 top-N)已在 v0.2.0 废弃。热度排序(hotRecords)保留为 memory_recall 空查询时的浏览排序方式,不再参与每轮注入。

2.2 接入点(全部复用既有机制)

能力	接口
持久化	ctx.storageDomain.open(defineDomain),backend=json,zod 边界校验
工具注册	ctx.tools.register(defineTool),6 工具
协议注入	ctx.systemPrompt.section()(memory-protocol, order 110)
按需注入	agent/pre-step 钩子,每轮按当前消息 recall
纠错闭环	agent/error 指纹监听

2.3 数据模型

Domain memory v1,单表 records。字段:id、content(≤2000 字符)、kind(fact/preference/decision/lesson/todo/note)、tags、scope(user/project)、project、importance(1–3)、createdAt/updatedAt/accessedAt/accessCount/expiresAt。坏数据 open 即拒绝。

3. 检索与注入

3.1 检索

零依赖。中文按 bigram 索引、单字兜底;英文按词;支持整串匹配与 query-word 子串命中(v0.7.0——短查询对长记忆不再漏检)。评分 = 相关性 × 新鲜度(90 天半衰)× 重要性 × 访问频率。

3.2 防无关联想(v0.5.0)

• MATCH_BASE_MIN=1.0:纯单字重合分数归零,不命中;
• hasMeaningfulQuery:纯虚词/填充查询(如"ok了吗")跳过注入,省 token。

3.3 按需注入(v0.2.0/v0.3.0/v0.6.0)

每轮模型执行前,以当前消息 recall,注入 top-3 条相关记忆摘要(默认)。检索结果与上一轮一致时跳过注入(重复抑制)。注入为只读操作,不触发访问计数写盘(v0.6.0)。

4. 记忆治理

• 容量淘汰:maxRecords=400,importance=3 豁免;
• 近重复合并:Jaccard ≥ 0.7(中文校准),保留旧 TTL;
• TTL 过期:expiresAt 到达即淘汰,上限 3650 天;
• 删除守卫:importance=3 需 confirm=true。

4.1 辩证治理(v0.7.x)

• 教训辩证写入(v0.7.1):协议与 lessonize 提示要求区分:①错在哪、怎么规避 ②失败的条件是什么、换条件是否可行(适用边界) ③是否有效可保留的部分;禁止把条件性失败记成绝对结论。
• 记忆库辩证管理(v0.7.2):矛盾记忆不必然错误——先分条件与时机再判断;新决策覆盖旧记录时标记 superseded("已由 X 更新/覆盖"),不留静默矛盾;forget 前确认条件真正消失。

5. 自我纠错闭环(v0.4.0)

监听 agent/error,按错误指纹(code/message)计数;同指纹第 2 次触发提示,模型以 memory_remember 固化为 importance=3 教训。教训入库后经 pre-step 注入自动召回。用户纠正由协议当场固化。

6. 外部修改防护(v0.2.1)

存储文件启动时一次性加载,单写者模型。每次写入前校验文件指纹,外部修改则拒绝写入(MEMORY_EXTERNAL_MODIFIED,绝不静默覆盖);批量导入走 memory_import(写链);外部修改后 memory_reload 合并,免重启。

7. 工具集

工具	语义
memory_remember	写入记忆(含 TTL)
memory_recall	检索,相关性×重要性×新鲜度×使用频率排序;空查询按热度浏览
memory_index	浏览,kind/tag/scope 过滤、分页
memory_forget	按 id/tags 删除,importance=3 需 confirm
memory_reload	外部修改后重开合并
memory_import	JSONL/JSON 批量导入(走写链)

8. 评估

• 单元测试:45 例全绿;
• 真机冒烟:headless 往返验证通过;
• 检索质量:top-1 命中 100%(9/9 查询);query-word 子串命中 headless 验证 15 hits;
• 性能:400 条写入 45ms,recall 3.1ms;
• 兼容性:peer 依赖锁 0.1.0-rc.6 全家桶,不依赖未公开 API。

9. 版本演进

v0.1.0(4 工具,热记忆广播)→ v0.2.0(广播改按需注入)→ v0.2.1(外部修改防护)→ v0.3.0(重复抑制)→ v0.4.0(自我纠错闭环)→ v0.5.0(防无关联想)→ v0.6.0(只读注入,删热记忆广播残余)→ v0.7.0(query-word 命中)→ v0.7.1(教训辩证写入)→ v0.7.2(记忆库辩证治理)。

10. 发布与安装

• npm:dsh-agent-memory@0.7.2 — https://www.npmjs.com/package/dsh-agent-memory
• 源码:https://github.com/Culeot/dsh-agent-memory(MIT),标签 dsh-plugin

cd ~/.dsh/profiles/<profile>
pnpm add dsh-agent-memory

preset 挂载(agent.cordis.yml):

- id: memory
  name: 'dsh-agent-memory'

重启后新会话出现 6 个 memory_* 工具。前置条件:profile 已挂存储三件套(dsh-storage、dsh-storage-json、dsh-storage-domain,web profile 自带)。

11. 建议

若官方评估内置长期记忆,建议纳入 packages/memory/*,与 dsh-tool-goal 同级。作者愿按官方规范调整架构与许可。

[Electricitysheep]

跨会话长期记忆这块确实是 DSH 的空白（文件型/会话级存储留不住动态知识），你这个基于原生 cordis 的实现补得很及时。和 #1373 的 dsh-memory、#1052 里提到的 dsh-sgme 一起，memory 家族算是凑齐了不同路线了。

已收录进手册生态章节（memory 家族），后续如果整理出"记忆插件选型对比"也欢迎来手册共建：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/07-ecosystem.md