dsh-engram

dsh plugin --profile web add dsh-engram

dsh-engram

[中文](README.zh.md) · [English](README.md) · [已交付 UI 控件清单](FEATURES.zh.md)


为 DeepSeek Harness 设计的极简长期记忆插件，融合了

symbolic-index 与 pi-esr 的思想——

目标只有一个：省 token。

• 零 LLM 摄入 — 纯模式匹配从工具结果自动捕获有意义的事件（带书面 -m 提交信息的 git 里程碑、

关键文件编辑、反复出现的错误），另有显式 engram_store。热路径上没有任何模型调用，纯粹的操作

——git push / git stash / 无提交信息的 commit——刻意从不记录（见下方「自动捕获策略」）。

每条写入先过一道确定性密钥脱敏器——API key、JWT、Bearer token、私钥、AWS/Stripe/Slack/GitHub

token 与 key=value 形密钥一律替换为 <REDACTED:…> 标记，且在去重哈希 / 字符上限 / 落盘之前完成，

敏感内容永远进不了磁盘。测试失败用纯模式识别（npm test / node --test / vitest/pytest/jest

• 失败行）自动捕获为 tags:["error","test"]、信号上调。DSH goal 域打通：completed/blocked 的

goal（goal/change 会话事件）自动沉淀为 handoff/error 记忆（tag:goal），目标结局不随会话消散

（读取面见 GET /api/dsh-engram/goals）。

• 用户纠正/偏好学习（autoCapturePreferences，默认开，零 LLM） — 「AI 犯错被纠正后，教训要留存」

（correx、PAHF、Mem0 偏好提取）：

一个 session/event 监听器盯 user/message，用确定性纠正/偏好句式把用户话语沉淀为独立的

preference 记忆 kind——中文（不要用X、改用X、以后统一用X…）与英文（don't use X、

switch to X、prefer X、never use X…）模式，三种方向（avoid / switch-to / prefer），

并带疑问句 / 一次性操作指令 / 记忆工具元话语过滤器抑制误报。preference 记忆在 [ENGRAM]

块里压过其它所有 kind（[R] 前缀），让用户的长期规则成为每会话模型看到的第一行；

每会话上限 + 近期窗口去重与自动捕获同纪律。零 LLM、零向量、确定性纯函数——提取片段有界，

每条写入依旧先过密钥脱敏器。

• 符号索引 + 渐进披露 — 一个紧凑的 [ENGRAM] 块（默认预算 700 字符 ≈ 175 token；每条记忆一行）在

组装提示词时注入，并按会话冻结，让请求前缀字节稳定以复用 KV 缓存。模型需要细节时用

engram_recall / engram_detail 下钻，而不是把命中的原文灌进上下文。召回对内存池做

进程内 BM25 排序（TF·IDF + 标签/短语加权 + 时间衰减因子，确定性、零依赖）；

命中实体锚定的记忆时附带实体邻域关系简表（复用 esr_link：node --rel--> node · conf%）；

与历史失败高度同源的新错误会唤醒旧 error 记忆（刷新 recency + 命中，向 promoteHits

爬升直至重回索引，失败不重复堆积）；本地零命中时自动兜底到 DSH 自带的跨会话全文索引

（ctx.sessionQuery，按 cwd 过滤）——不另建 SQLite，完全复用宿主。当 FTS 兜底也返回空、

且查询含 CJK 中文（FTS5 中文分词整段只算一个 token）时，召回会对最近若干会话日志做

有界的子串扫描（zstd 解压 + LRU 缓存，限文件数与字节），追加命中会话的确定性

# past sessions 行。

• 会话启动自动召回（autoRecallOnStart，默认开） — 纯拉取式设计有个被实证戳穿的盲区：

召回工具只交模型自觉，而真实会话里模型几乎从不主动调 engram_recall（实测 19 个会话数千次

工具调用只出现 ~5 次召回）。因此宿主在新会话首次组装时，用会话首条用户消息对工作区做

一次确定性 BM25 召回，把命中前 ≤3 条直接注入 [RECALL] 块（默认 700 字符预算，"少而准"，

agentmemory 候选①）——相关记忆不依赖模型想起来就已在上下文里。纯规则、零 LLM、

纯读不 bump 命中；superseded 过期真相不占注入槽（仍可 engram_detail 重取）；

与 [ENGRAM] 一起按会话冻结保持前缀稳定。

• 读路径激活（D） — 命中条目的单行预览被截断（>140 字符）时带 … 标记，且块尾

引导行点名该具体 id：#<id> truncated — engram_detail <id> (full) · engram_recall <query>。

模型由此知道完整记录就在一次确定性 engram_detail 之后，而不是以为预览就是全文

（实证盲区：66 个会话 0 次 engram_detail——下钻路径此前对模型不可见）。

• 记忆间语义（supersede/contradict） — engram_store 可选收 supersedes / contradicts

记忆 id（同工作区校验）。被 supersede 的「过期真相」在召回里降级到尾部、并从 [ENGRAM]

块中剔除（新陈述占行）；被 contradicts 的记忆保留排序但标注 · contradicted by <id>。

旧行永不删除——可重取，只是排得诚实。可选 autoSupersede 配置（默认关）对"实体锚定 +

替换式更新（改用/不再/no longer/switched…）"自动打 supersedes；显式 supersedes 永远优先。

• 失败→解法闭环（零 LLM） — error 记忆带 cmd: 签名标签；同命令随后跑通时自动沉淀

procedure 记忆（fixed: <cmd> — N earlier failing runs now succeed），并把旧 error

行打上 resolved（不影响其排序），召回因此浮出解法而不是过期失败。

• ESR-lite 证据闭环 — esr_task / esr_close / esr_link 给任务一个 draft → active → stable

生命周期，其中 stable 必须要有真实证据（artifact / evaluation / memory_ref），把"缺什么"

摊在明面上，而不是让 agent 没有证据就宣布完成。可开 verifyArtifact（默认开）：非 URL 的

artifact 按工作区（= 会话 cwd）解析并在磁盘上实存校验，路径不存在则任务保持 ACTIVE、给出原因；

force:true（或关掉该开关）可跳过磁盘校验——三种证据门照样必填。工具与网页表单共享同一个

证据门（store.evidenceGate），口径绝不会漂移。

任务不再是孤立节点：esr_task(entity=…) 一键挂点——自动建 ent_<slug> 节点并挂

task --relates_to--> entity 边（幂等），挂着领域锚点的任务立刻带关系；

esr_dep 双写——依赖边同时进 tasks[].deps（blocker 逻辑）与 links 表，图谱里每条

任务依赖都是一等可见的边。

• ESR 触发机制（pi-esr 对齐，混合：静态协议 + 冻结快照 + 单调渐进 actionables + 拉取） —

前缀缓存稳定是核心。模型「何时用 ESR」靠静态方法论（engram:esr-method，每轮逐字节相同）；

[ESR] 块 = 确定性冻结快照（会话开始定下、确定性排序、时间戳排除、明示 WILL NOT

auto-refresh）+ 本会话单调渐进的 actionables：promote:/root-cause:/close:/stale:/escalate:

在它们成熟的那一刻被一次追加进块并冻结（永不回撤）——前缀只在「真正出现新决策点信息」时变化、

绝不逐轮漂移，同时保留决策点提醒（漏斗最窄处 / 复发失败 / 收工 / stale / 平衡）。实时状态仍可

拉取：esr_status（全量视图 + since_revision 增量短响应 + 派生 actionables）。

recorder 由 tools/result 订阅喂入（actionables 的数据源）；P4 转化度量照常（#suggest-* 标记 +

10 分钟归因 + GET /api/dsh-engram/triggerstats）。纯规则、零 LLM。

• 会话结束 todo 自动沉淀（draft 兜底，autoSinkTodosOnEnd 默认开） — 会话内 todo 仍是

轻量、随会话而逝的"工作记忆"；但当会话在其拆解边界（session/disposed）关闭时仍挂着 pending

todo，这些待办会自动转为该工作区的 ESR draft 任务（名称=todo 原文、描述「源自会话计划」、

按已存在任务名去重、受 maxTasksPerWorkspace 上限约束），计划从此不静默蒸发。落到 draft

而非 active：不占 [ESR] 的 active 行、不产生证据义务，仍需刻意的 esr_claim / esr_task

推进才变 active——「进行中默认不写」的取舍不变，只把「收尾丢数据」的缺口补上。可关（profile

patch 或设置卡）。

• 记忆 GC（pi-esr 约束） — 定时、机械、只归档的回收：TTL 过期记忆归档、超容量工作区淘汰低价值条目、

stable 任务超保留窗离开 [ESR] 表面、悬空链接边清理。工作集（active 任务引用 / 任务记忆 / 已入索引命中）

永不触碰；不硬删任何东西——归档条目保留 id、始终可重取。

• Context GC（自动 GC = 替代 DSH 自动 compact，opt-in） — 不是记忆面板 GC：开启后接管 DSH 自带的上下文压缩

（compaction 服务），把「有损 LLM 全量摘要」换成机械驱逐 + 重取指针——扫描被驱逐轮次里的

engram/ESR 锚（#记忆id、tsk_、ent_、file_path），只留一行「细节在 engram_detail /

engram_recall / [ESR] 里」；只有无锚轮次才走 scoped LLM 叙事兜底（gcNarrative，默认开、可关成纯机械）。

六条 GC 约束（working-set-protected / pointer-salience / no-provenance-no-evict…）全部落地；任何错误回退

默认压缩，永不破坏 compact。

• Web 查看器 — 一个带统计的记忆浏览器和配置卡片，完全构建在 DSH 原生设置槽位上（不碰任何第三方 UI 包）。

MIT   ·   node >= 22.19   ·   host 半边 + 浏览器半边合在一包

为什么还要一个记忆插件？

对既有 DSH 插件生态的调研显示，记忆领域里"召回桥 / 审批门 / LLM 蒸馏 / 向量+图"这几个方向已经挤满了。

dsh-engram 补的是对 token 纪律真正重要的三个空白：

1. 写入路径没有模型 — 捕获是确定性的模式匹配。

2. 提示词里不灌全文 — 只注入有界的符号索引 + 会话启动时自动召回的最相关 ≤3 条（预算内），

更深的检索按需进行（"检索到≠灌全文"）。

3. 诚实的任务闭环 — 没有证据就不能宣布 STABLE。

DSH 已经提供跨会话 FTS（`ctx.ses

…(truncated)