paulalesius/dsh-hindsight-advanced

dsh-plugin-hindsight-advanced

一个用于 DeepSeek Harness (dsh) 的插件，集成了 Hindsight 记忆系统：你的 agent 将记忆存储在你自己的 Hindsight 服务器中，并将相关的记忆带回对话中。

安装

使用 dsh 命令：

dsh plugin --profile web add /path/to/hindsight-advanced

从源码运行 dsh 时：

pnpm dsh plugin --profile web add /path/to/hindsight-advanced

然后重启服务器。

配置

配置是你自己的 DSH 配置中的一行 hindsight——绝不是对插件文件的编辑。你将它放在以下两个位置之一（只选一个，绝不要两个都放）：

每个会话。 在你 profile 的 patch 层中
（~/.dsh/profiles/web/cordis.patch.yml，追加到你现有的文件中）：

- id: hindsight
disabled: false
config:
bank: my-bank
baseUrl: http://127.0.0.1:9177
apiKeyRef: HINDSIGHT_API_KEY

仅一个预设。 在该预设自己的文件中
（~/.dsh/.agent-presets//agent.cordis.yml，追加）：

- id: hindsight
name: dsh-plugin-hindsight-advanced
config:
bank: my-bank
baseUrl: http://127.0.0.1:9177
apiKeyRef: HINDSIGHT_API_KEY

指向同一个 bank 的预设不需要单独的 bank——preset 作用域已经将每个预设的记忆彼此隔开。

关于这一行，有两件事需要了解：

- config 块会整体替换插件的默认值——列出你想要的每一个键；只有 bank 是严格必需的，其余键会回退到下表所示的默认值（但 baseUrl 和 apiKeyRef 值得重复写出，因为它们的默认值指向端口 8888 且不带密钥）；
- 要再次关闭该插件，请在该行上设置 disabled: true（或删除预设行）并重启。

配置键

| 键 | 默认值 | 作用 |
| --- | --- | --- |
| bank | — | 必需。 要使用的 Hindsight bank 的名称（服务器会在首次使用时创建它）。 |
| baseUrl | http://127.0.0.1:8888 | 你的 Hindsight 服务器的地址。 |
| apiKeyRef | — | 为插件提供密钥的方式——是密钥的名称，而不是密钥本身。该值会在每次调用时查找（环境变量 → ~/.dsh/.credentials.yaml → .env 文件），因此轮换密钥无需重启，密钥也绝不会留在配置文件中。见下文。 |
| apiKey | — | 直接写在配置中的明文密钥，而不是引用。优先使用 apiKeyRef。 |
| autoContext | true | 设为 false 可关闭每轮自动召回（hindsight 工具仍然保留）。 |
| prefetch | true | true（默认）：召回在上一轮结束时就开始，因此从第二轮起它针对的是上一条消息。false：每一轮都查询你刚刚发送的消息并等待服务器响应——记忆始终与你刚说的内容相关，代价是每次首次模型调用都要承受服务器的延迟。 |
| recallContextTurns | 5 | 有多少条你最近的对话轮次会随召回查询一起传递，这样记忆库就能根据对话内容来匹配记忆，而不仅仅是最后一条消息。查询是锚点消息，位于 Prior context: 块下方，该块包含最近的先前轮次（每条用户/助手消息一行），上限为 1000 个字符，超出时最先丢弃最旧的行。1（参考集成所采用的值）是普通的单消息查询。 |
| recallPreserve | true | true（默认值）：模型上下文是仅追加的——每个已提交的召回快照都会保留在对话中，因此后续轮次可以看到之前召回的记忆。false：模型上下文只携带最新的完整快照——每个新快照会就地替换前一个完整卡片（在该轮次召回触发的位置保留一行墓碑标记，其完整 token 从计费中扣除），并作为新卡片落在自己的轮次中，而持久会话日志会保留每个完整快照以供重放和审计。命名与 llama-server 的 --no-reasoning-preserve 一致：关闭时，一轮的快照就像它的推理一样，仅在该轮次内存在。 |
| retainScope | preset | 当 agent 未指定时，存储的记忆落在哪里：global（记忆库中的所有内容）、preset（此 agent 预设）或 session（仅此会话）。 |
| maxRecallTokens | 4096 | 每次召回带回多少记忆。 |
| autoContextTimeoutMs | 2500 | 一轮在继续之前可以等待记忆服务器多长时间。由于查找是提前运行的（见下文），大多数轮次永远不会付出这个代价；缓慢或停止的服务器永远不会阻塞 agent。 |
| retainAsync | false | false（默认值）：存储会等待记忆库处理完该记忆，因此下一轮已经能看到它。true：存储快速确认，记忆库在后台处理。 |
| bankConfig | — | 给服务器自身记忆提取的可选指令——例如 retain_mission: "Focus on decisions and durable project facts." 告诉 Hindsight 服务器从 agent 存储的内容中提取什么。 |

自动召回如何工作

在每一轮开始时，agent 会收到一条小提示：与你最新消息匹配的记忆，以及你存储的任何常驻规则。查找会在上一轮结束时就立即在后台开始——在你阅读或输入时——因此当 agent 开始下一轮时，记忆通常已经在那里，该轮完全不会等待记忆服务器。对话的第一轮没有可提前读取的内容，因此它会正常等待服务器（最多 autoContextTimeoutMs）。设置 prefetch: false 可以改为查询你刚发送的消息——代价是每一轮都要等待。
查询不仅仅是那一条消息：在默认的 recallContextTurns: 5 下，对话的最后几轮会随查询一起传递，位于 Prior context: 块下方（每条消息一行，上限为
1000 个字符），因此关于你一两轮前所讨论主题的记忆也能匹配——将其设为 1 可进行普通的单消息查询。
当某一轮的召回没有匹配到任何新内容时，你会得到一行
“本轮没有新记忆”，而不是重复的块：它逐行列出仍然生效的
记忆，每行一条，这样你就能确切看到应用了哪些内容，而无需重复整个块。
默认情况下，这些笔记是仅追加的（recallPreserve: true）：每一轮的
快照都会保留在模型上下文中，因此智能体会持续看到它之前召回的内容。将 recallPreserve: false 设为保持上下文
精简——每个新笔记会就地替换掉先前的完整卡片：在该轮召回触发的位置会保留一行
标记（这样你总能一眼看到召回发生在对话中的
哪里，而无需滚动），而完整笔记会作为一张新卡片落在它自己的轮次——只有最新的完整
召回会留在模型的可见表面上（卡片的完整历史仍保留
在会话日志中以便回放）。这个命名与 llama-server 的
--no-reasoning-preserve 一致：关闭它时，某一轮的快照，就像它的
推理一样，仅在该轮存续。代价是，被替换的卡片会
重新开始模型的缓存前缀。

为插件提供其密钥

apiKeyRef: HINDSIGHT_API_KEY 只是一个名称——插件在每次调用时都会按该名称查找
对应的值，顺序如下：环境变量，然后是
~/.dsh/.credentials.yaml，然后是 .env 文件。通常的做法是在
~/.dsh/.credentials.yaml 中添加一行，与您现有的条目并列添加
（例如 LLM 密钥——不要替换它们）：

version: 1
refs:
HINDSIGHT_API_KEY: