DeepSeek Harness（DSH）采用插件化架构。在智能体开发中，长期记忆往往导致上下文膨胀和 token 消耗。dsh-engram 从 symbolic-index 和 pi-esr 概念中汲取灵感，为 DSH 提供了一个极简的长期记忆系统，核心目标是节省 token。
核心功能¶
零 LLM 自动捕获¶
插件通过纯模式匹配捕获有意义的事件，不调用 LLM 进行热路径处理。
* 事件类型：支持 git milestones（带有 -m 提交信息的里程碑）、关键文件编辑、重复错误。
* 敏感信息脱敏：所有写入前会经过确定性脱敏处理，API keys、JWT、Bearer tokens、私钥等被替换为 <REDACTED:...> 标记。
* 排除项：静默提交（git push / git stash）被有意排除，不记录在案。
* 测试失败：通过纯模式（npm test、node --test、vitest/pytest/jest 的失败行）识别测试失败，作为 tags:["error","test"] 的条目捕获。
符号索引与渐进披露¶
- 索引结构：在提示词组装时注入紧凑的
[ENGRAM]块（默认预算 700 个字符，约 175 tokens，每行一条记忆）。 - 会话冻结：该块在会话开始时生成并冻结，保持请求前缀字节稳定，以支持 KV-cache 重用。
- 下钻工具：使用
engram_recall或engram_detail进行下钻，而非直接将原始命中结果倾倒到上下文中。 - 召回算法：进程内 BM25 召回（TF·IDF + 标签/短语加权 + 时间衰减因子）。包含实体邻居表（
esr_link格式）。 - 重复失败唤醒：当新失败与旧错误高度相似时，基于最近期和命中爬升（
promoteHits）唤醒旧的错误条目，避免失败记录堆叠。 - Fallback 机制：本地无命中时，回退到 DSH 自身的跨会话全文索引（
ctx.sessionQuery）；若仍为空且包含 CJK 字符，则扫描最新的会话日志（zstd 解压，LRU 缓存）。
会话开始自动召回¶
- 默认开启：
autoRecallOnStart默认开启。 - 机制：在会话第一条用户消息上运行一次确定性 BM25 召回。
- 注入形式：将前 ≤
autoRecallLimit个命中注入为[RECALL]块（默认 700 字符预算）。 - 行为：纯读操作（不增加命中次数），排除已被覆盖的旧条目。
记忆间语义管理¶
- 关系定义：
engram_store支持可选的supersedes（覆盖）和contradicts（矛盾）参数。 - 覆盖处理：被覆盖的条目（“陈旧真相”）被降级到召回列表尾部，并排除在
[ENGRAM]块之外，但依然可通过engram_detail检索。 - 矛盾处理：被矛盾的条目保留排名，但标记为
· contradicted by <id>。 - 自动覆盖：
autoSupersede配置（默认关闭）可自动将“改用 / no longer / switched…”类的更新标记为覆盖旧条目。
失败→修复闭环¶
- 命令标签：错误记忆携带
cmd:标签签名。 - 自动修复：当该命令后续执行成功时，插件自动沉积一条
procedure记忆（fixed: <cmd> — N earlier failing runs now succeed），并将旧错误条目标记为resolved，召回时优先展示修复方案。
ESR 轻量级证据闭环协议¶
- 命令集：
esr_task/esr_close/esr_link。 - 生命周期：任务经历
draft → active → stable生命周期。stable状态要求真实证据（artifact/evaluation/memory_ref）。 - 证据验证：
verifyArtifact（默认开启）检查非 URL artifact 是否存在于工作区（session cwd）。若不存在，任务保持 ACTIVE 状态并附带原因。force:true可跳过磁盘检查。 - 依赖管理：
esr_dep将依赖边写入任务的deps（阻塞逻辑）和共享链接表，使依赖关系成为图中的可见边。
会话结束待办自动下沉¶
- 默认开启：
autoSinkTodosOnEnd默认开启。 - 下沉机制：会话结束时，若计划仍有待办事项，它们被自动下沉为 ESR
draft任务（名称为待办文本，描述标记「源自会话计划」）。 - 状态：下沉为
draft而非active，避免产生证据义务。需通过显式esr_claim/esr_task才能激活。
技术细节¶
- 依赖环境：Node.js >= 22.19.0；DSH >= 0.1.2-alpha.2 < 0.2.0-0。
- 存储位置：数据存储于
ctx.storageDomain。 - 运行模式：以当前 DSH 进程权限运行。
典型用法¶
插件提供以下工具和接口用于操作记忆与任务：
// 记忆操作
engram_store(supersedes: string, contradicts: string)
engram_recall()
engram_detail()
// ESR 任务操作
esr_task(entity: string)
esr_close(taskId: string)
esr_link(taskId: string, targetId: string)
esr_dep(taskId: string, depId: string)
esr_status()
esr_claim(taskId: string)
// HTTP 接口
GET /api/dsh-engram/goals
GET /api/dsh-engram/triggerstats
适用场景与注意¶
- 适用场景：需要为 DeepSeek Harness 智能体引入长期记忆，但希望严格控制上下文 token 消耗，同时需要结构化任务管理和证据闭环能力的开发者。
- 注意：插件以当前 DSH 进程权限运行，请确保安装前检查源码与许可证（MIT）。
