Ryu6Zero/dsh-hindsight

dsh-hindsight

官方级 DeepSeek Harness 记忆插件，后端对接 Hindsight。

给 DSH Agent 真正的跨会话记忆：召回过去的决策、记住新事实、查看记忆健康状况——通过一个自包含的 Cordis 插件完成。没有 dsh-mnemon、没有编排层、没有捆绑存储引擎。就是一层对接 Hindsight REST API 的轻薄 HTTP client。

为什么

DSH Agent 默认无状态——每次会话都从零开始。已有的记忆方案（如 dsh-mnemon）是重型的“三层编排全家桶”。如果你本就部署了 Hindsight（高质量向量记忆引擎，带实体解析 + 知识图谱 + 多策略检索），这个插件把 DSH 直接接上去，一个可安装的包就够。

已实测端到端跑通：一个真实 DSH Agent 调用 hindsight_recall，在 headless profile 里从 Hindsight bank 召回真实记忆。

特性

- /hindsight 斜杠命令 — status / recall  / related  [depth] / list [查询] / remember  / forget
- 6 个模型工具 — hindsight_status hindsight_recall hindsight_related hindsight_list hindsight_remember hindsight_forget（Agent 下一步可直接调用）
- 知识图谱遍历 — hindsight_related：从一条记忆出发，BFS 遍历 Hindsight 实体关系图谱的邻居（1-5 跳），追踪关联决策/实体
- 主动记忆引导 — autoRemember 开启时，hindsight_remember 引导模型主动识别并保存可持久复用的事实（偏好/决策/约束），“不确定先问”防脏数据
- 记忆引导注入 system prompt — systemPromptSection 开启时，模型从第一轮就知道自己有长期记忆、何时该召回/保存（官方 section provider 形态）
- 异步操作可观测 — hindsight_operations / /hindsight operations：查看记忆提取队列状态，“刚存的记住了吗”不再靠猜
- 批量去重写入 — hindsight_condense：一次提交 2-10 条事实，自动跳过与近期记忆重复的内容（文本归一化保守查重）
- 召回缓存 — 相同查询 60s 内秒回（recallCacheTtlMs 可调，0 关闭），写操作即时失效
- 多库只读探索 — 只读工具支持 bank 参数 / 命令支持 @库名 前缀，可跨项目库检索；写入始终走默认库防误写
- 热配置 — endpoint / token / bankId / 超时 / autoRemember，改完即时生效，无需重启
- 部署诊断 — hindsight_status 连不上时返回具体诊断 + Docker 一键启动引导
- 独立 client — HindsightClient 是零依赖 HTTP 层（health recall list listBanks stats graph related operations remember forget），插件之外也能复用

安装

要求 Node ≥ 20，DeepSeek Harness ≥ 0.1.1-rc.2。

装到 Web profile（完整 UI）和 Headless profile（命令行任务）——两者挂载同一套工具：

npm registry（发布后）
dsh plugin --profile web add dsh-hindsight
dsh plugin --profile headless add dsh-hindsight

或本地开发目录
dsh plugin --profile web add "link:/绝对/路径/dsh-hindsight"
dsh plugin --profile headless add "link:/绝对/路径/dsh-hindsight"

然后启动/重启 profile：

dsh --profile web

配置

默认指向 http://localhost:8888、bank hermes。在 DSH 设置界面的 hindsight 命名空间里覆盖（别改 bundle patch）：

| 字段 | 默认 | 含义 |
|---|---|---|
| endpoint | http://localhost:8888 | Hindsight 服务地址 |
| token | '' | 远程服务的 Bearer token；本地开放服务留空 |
| bankId | hermes | 记忆 bank id |
| defaultRecallLimit | 10 | 每次召回上限 |
| requestTimeoutMs | 15000 | 数据面请求超时 |
| healthTimeoutMs | 5000 | 健康探测超时 |
| autoRemember | true | 会话中引导模型主动保存可持久事实（写前会先问） |
| systemPromptSection | true | 向 system prompt 注入记忆引导段（模型开局即知有记忆） |
| recallCacheTtlMs | 60000 | 召回缓存 TTL 毫秒（0 = 关闭缓存） |

环境变量/用户设置优先于 bundle 默认值。token 不写进提交的配置。

还没有 Hindsight？零基础起步

本插件把 DSH 桥接到一个已有的 Hindsight 服务。你还没有？ 用官方 Docker 镜像 ~1 分钟拉起（需要一个 OPENAI_API_KEY）：

docker run -it --pull always --name hindsight --restart unless-stopped \
-p 8888:8888 -p 9999:9999 -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
-v hindsight-data:/home/hindsight/.pg0 ghcr.io/vectorize-io/hindsight:latest

- API 监听 http://localhost:8888（本插件默认读取的地址）。
- 从控制面板 http://localhost:9999 创建名为 hermes 的 memory bank，或在设置里把 bankId 改成你自己的。
- hindsight_status 在服务不可达 / bank 缺失时会返回具体诊断和上面的启动命令，首次运行失败也会直接告诉你该怎么做。

官方文档：https://hindsight.vectorize.io/developer/installation

用法

/hindsight status               # bank 统计、记忆/连接/文档数
/hindsight recall 记忆架构决策   # 语义召回，显示文本 + ID
/hindsight related  [depth] # 遍历知识图谱邻居（1-5 跳）
/hindsight list                 # 最近记忆
/hindsight operations [数量]     # 最近异步操作状态（提取队列）
/hindsight remember 记住X        # 入队异步结构化提取
/hindsight forget           # 软删除（作废）一条记忆

在对话里直接让 Agent 做这些也行——它通过模型工具「查一下记忆」「记住这个」即可自己完成。

构建与测试

pnpm install
pnpm build        # tsdown:lib/index.js + index.d.ts + sourcemap
node scripts/test-client.mjs   # 对运行中的 Hindsight 做真实集成测试

scripts/test-client.mjs 命中真实 Hindsight 端点（health/stats/listBanks/recall/list/graph/related/remember/forget/diagnose），15 项契约全绿。remember→recall 可见性有个要说明的坑：Hindsight 通过自己的 LLM/consolidation 队列异步提取，刚 remember 的事实可能要超过测试窗口才出现在召回里——这是 Hindsight 自身的环境性依赖，不是插件问题。

范围

这是轻量独立插件，特意不是 dsh-mnemon 的替代：

- ✅ 范围內：Hindsight REST client + 斜杠命令 + 模型工具 + 热配置。
- ❌ 范围外：WebUI 工作台、多 provider 编排、捆绑存储、client/浏览器 bundle、提取/蒸馏子 Agent。

License

MIT。见 LICENSE。