Hindsight 记忆 paulalesius/dsh-hindsight-advanced

dsh-plugin-hindsight-advanced

🔴 兼容性：本插件逐字对应 DeepSeek Harness 提交 0d1f50007f9bca3f52b06e1c3074fa14d5fb0720。它不兼容之后的 DeepSeek Harness 版本——那些版本 bug 太多，没法用。

一个 DeepSeek Harness（dsh）插件，集成 Hindsight 记忆系统：你的智能体把记忆存进你自己的 Hindsight 服务器，再把相关的记忆带回对话。

安装

用 dsh 命令：

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

从源码运行 dsh 时：

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

然后重启服务器。

配置

配置就是你自己的 DSH 配置里的一行 hindsight——绝不要去改插件自己的文件。你可以把它放在两个位置之一，或者两个都放，前提是两行指向不同的 bank（配置档全局的 bank 加某个预设专属的 bank；见下文「挂载插件两次」）：

每个会话。 放在配置档的补丁层（~/.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/<preset>/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 端口，而且不带 key）；
- 想再关掉插件，就把这一行设成 disabled: true（或者删掉预设那一行），然后重启。

挂载插件两次

两行可以同时作用于一个会话：配置档全局那一行，加上某个智能体预设那一行，指向不同的 bank。这时会话的 PRESET 挂载接管自动召回：每个自动入口（回合开始时的快照、步骤中途的召回、压缩后的召回、教训闸门）只提交一份快照——预设 bank 的卡片——并把配置档全局 bank 的常驻指令作为独立小节合并进去（用那个 bank 作标题），这样配置档全局 bank 的规则仍然能到达模型，而不用每回合多一个块。对那个会话来说，配置档全局那一行在所有自动入口上都保持沉默：没有第二份快照，没有预取，没有步骤中途或压缩后的召回，没有闸门查询（它的 hindsight 工具仍然已注册，但会被该会话智能体对应的预设行遮蔽）。预设行未覆盖的会话，照常由配置档级行提供服务。合并按 bank 做故障隔离：某个配置档级 bank 的指令列表拉取失败，就直接不参与合并，预设 bank 的卡片仍会带着自己的规则落地。对同一个 bank 挂载两次是多余的：第二次挂载的刷新会淘汰第一次挂载的卡片，最终表层只收敛到一个 bank 的卡片。

配置键

| 键 | 默认值 | 作用 |
| 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 | 召回查询里附带多少条你最近的轮次，这样 bank 能拿记忆去匹配对话在谈什么，而不只是最后一条消息。查询以锚点消息为主体，前面加一个 Prior context: 块，列出最近的先前轮次（每条 user/assistant 消息一行），上限 1000 字符，超出时先丢弃最旧的行。1（参考集成默认发布的值）就是单纯的单消息查询。 |
| recallPreserve | true | true（默认）：模型上下文只追加 —— 每个已提交的召回快照都留在对话里，后续轮次能看到先前召回的记忆。false：模型上下文只保留最新的完整快照 —— 每个新快照会就地淘汰上一个完整卡片（该轮召回触发的位置留一行墓碑标记，其完整 token 从计费中扣除），并在自己所属的轮次作为新卡片落地，而持久会话日志会保留每个完整快照，供回放和审计。命名对应 llama-server 的 --no-reasoning-preserve：关掉之后，一轮的快照就像它的推理一样，只在该轮存活。 |
| recallAfterText | false | true：从第一步之后开始，某一步的 claim 不带人类消息时，就以上一步已提交的 text（智能体写下的文字）为锚点召回记忆库。受 autoContextTimeoutMs 限制，每步最多召回一次；claim 里带人类消息时改走干预路径。 |
| recallAfterReasoning | false | 与 recallAfterText 类似，但锚点是上一步已提交的 reasoning。两个键同时开启时，两个锚点合并成一次召回（先 reasoning，再 text），绝不会查两次。 |
| actionLessons | false | true：从第一步之后开始，某一步的 claim 不带人类消息时，插件会把上一步已提交的 tool calls 与记忆库中的失败教训（即 experience 记忆）做匹配，并在下一次模型调用前提交一行折叠提示（无标签，只显示摘要），列出匹配到的教训。上一步没有 tool calls 就没有锚点（不查记忆库）；每条教训每轮最多显示一次；子代理会话保持静默。 |
| actionLessonCandidates | 10 | actionLessons 提示行渲染多少条教训。召回本身不受这个键限制，提示行只保留最先匹配到的几条。 |
| lessonGate | false | true：执行 lessonGateTools 中列出的工具之前，待执行的调用本身会以记忆库中的失败教训（即 experience 记忆）为锚点做一次有界召回；若命中且匹配分数达到或超过 lessonGateMinScore，就在工具主体运行前拒绝这次调用：模型会看到渲染出的教训作为该工具的错误结果，从而在行动之前先从召回中学到东西。子代理会话保持静默；只有列出的工具才付出这次查询；超时或记忆库故障则放行调用（没有记忆库，就没有门禁）。默认关闭。 |
| lessonGateMinScore | 0.3 | 门禁拒绝受控调用所需的最低匹配分数（低于阈值的命中，或没有任何分数的命中，都放行调用）。 |
| lessonGateTools | bash, run_code | 门禁覆盖的工具名——只有这些调用才付出执行前的查询（默认是具备副作用能力的执行器）。 |
| recallAfterCompaction | false | true：上下文压缩成功之后，插件会以对话中最后一条人类消息为锚点召回记忆库（与预取相同的 Prior context: 组合），并把快照直接落到界面上——该行标签为 recall:compact - <ms>ms。压缩发生在任何步骤之外（轮次边界、上下文压力下的步骤中途，或请求重试时），所以没有步骤可以挂载召回；这次查询是分离的，受 recallCompactTimeoutMs 限制，而失败的压缩不会召回任何内容。默认关闭。 |
| retainScope | preset | 智能体没有说明时，存储的记忆落在哪里：global（全部进记忆库）、preset（当前智能体预设）或 session（仅当前会话）。 |
| maxRecallTokens | 4096 | 每次召回带回多少记忆。 |
| autoContextTimeoutMs | 2500 | 一轮最多等记忆服务器多久，超时就继续往下走。因为查询会提前跑（见下文），大多数轮次根本不用等；服务器再慢或停掉，也不会阻塞智能体。 |
| recallCompactTimeoutMs | 8000 | DETACHED 压缩后查询（recallAfterCompaction）的超时上限。它的查询是完整的多轮组合（锚点 + Prior context: 块，最多 1000 字符），记忆库处理它比处理阻塞循环路径里的单条消息查询更慢——放在共用的 autoContextTimeoutMs 下会必然超时，快照会被悄悄丢弃。这个事件是 fire-and-forget，所以更大的默认值永远不会传到智能体循环。 |
| retainAsync | false | false（默认）：存储会等到记忆库处理完这条记忆，下一轮就能看到它。true：存储快速确认，记忆库在后台处理。 |
| bankConfig | — | 可选，给服务器自己的记忆提取用的指令——比如 retain_mission: "Focus on decisions and durable project facts." 告诉 Hindsight 服务器该从智能体存储的内容里提取什么。 |

自动召回是怎么工作的

每轮开始时，智能体会拿到一小段提示：与你最新消息匹配的记忆，加上你存过的常驻规则。查询在上一轮结束时就立刻在后台启动——你还在读或打字的时候——所以等智能体开始下一轮时，记忆通常已经就位，这一轮完全不用等记忆服务器。对话的第一轮没有可提前读的东西，所以会正常等服务器（最多 autoContextTimeoutMs）。把 prefetch 设为 false，就会改为查询你刚发出的消息——代价是每一轮都要等。
如果智能体正在干活时你又发了消息，召回会跟着它走：智能体在下一步接住这条干预时，会当场召回记忆库（受 autoContextTimeoutMs 限制），锚点就是这条干预本身，所以轮次中途的纠正会带着关于「它纠正了什么」的记忆一起到达。只携带插件注入上下文的步骤不会召回任何东西。
默认情况下，上一句就是全部：没有人类消息的步骤不召回任何东西。把 recallAfterText 设为 true 和/或把 recallAfterReasoning 设为 true 可以改变这一点——在第一步之后，某个步骤的 claim 不带人类消息时，插件会以该步骤上一步自己的输出为锚点召回记忆库：它写下的文本和/或它提交的推理（两个都开时，合成一个锚点，推理在前，文本在后）。查询和干预的查询一样受 autoContextTimeoutMs 限制，并搭上推进该步骤的同一个决策，所以关于智能体刚做了什么事的记忆，会在……之前进入上下文下一次模型调用。claim 里的人类消息仍然优先（就是上面的干预路径），而且每步最多只有一次召回。
每条 note 的行里显示的是它这次查找花了多久（比如 recall - 12ms），位置就在插件名那里——展开这一行就能看到生产者。步骤中途的智能体输出 note，按它锚定的对象来标注：recall:text - 12ms（文本）、recall:think - 12ms（推理），或者 recall:think+text - 12ms（两者合并锚定）。
另有一趟独立的处理，actionLessons，对智能体的动作做同样的步骤中途操作，而不是对它的文字：在第一步之后某一步，如果它的 claim 不带人类消息，插件就拿上一步已提交的工具调用（每次调用一行）去匹配失败教训库——也就是它的 experience 记忆——匹配上就提交一行折叠的提示行（没有标签——只有摘要），列出匹配到的教训，位置在下一次模型调用之前。上一步没有工具调用就什么都不锚定（不查库），每条教训每轮最多出现一次，子代理会话保持静默。默认关闭；actionLessonCandidates 限制这一行最多渲染多少条教训。
第四个界面，recallAfterCompaction（默认关闭），在上下文压缩成功之后立刻召回：压缩发生在任何步骤之外（轮次边界的手动压缩、步骤中途的自动压力压缩，或者请求溢出后的重试），所以没有步骤前的决策可以挂载快照——查找独立运行在会话最后一条人类消息上（和预取一样的 Prior context: 组合），快照直接落到界面上，标注为 recall:compact - <ms>ms。这次查找走自己的超时限制（recallCompactTimeoutMs，默认 8000），因为组合出来的查询比那些阻塞循环路径的单消息查找服务得更慢——放在共用的 autoContextTimeoutMs 下它一定会超时；这个事件是即发即忘的，所以这个限制永远不会传到智能体循环。压缩失败（服务端报错）就不召回任何东西，子代理会话保持静默，召回结果没变化就不提交任何东西——或者提交「没有新记忆」的标记行，和其他地方一样。
还有一个独立的可选界面，lessonGate（默认关闭），把教训操作放在执行时而不是步骤时：在调用 lessonGateTools 里列出的工具（默认 bash 和 run_code）之前，待执行的调用本身会在失败教训库——也就是它的 experience 记忆——上锚定一次有界召回，如果匹配的分数达到或超过 lessonGateMinScore（默认 0.3），就在工具主体运行前拒绝这次调用：渲染出的教训作为工具的错误结果传过去，这样模型在动作执行之前就能从召回里学到东西。它和 actionLessons 可以配合使用（门禁阻止第一次执行；提示行在结果之后强化），但不共享状态——门禁不提交任何东西，也从不做去重，因为拒绝是模型唯一的反馈通道。子代理会话保持静默，只有被点名的工具才会付出查询代价，而超时、调用中止或 bank 故障都会放行这次调用。
查询不只看那一条消息：默认 recallContextTurns: 5 时，对话最近几轮会随查询一起带上，放在 Prior context: 块下面（每条消息一行，上限 1000 字符），所以关于你一两轮前讨论话题的记忆也能匹配上——想只查单条消息，就把它设为 1。
某一轮的召回没有匹配到新内容时，你会看到一行「no new memories this turn」，而不是重复整块内容：它列出仍然生效的记忆，每条一行，这样你能清楚看到应用了哪些记忆，又不必重复整块。
默认情况下笔记是只追加的（recallPreserve: true）：每一轮的快照都留在模型上下文里，智能体始终能看到自己早先召回的内容。设为 recallPreserve: false 可以让上下文更精简——每来一条新笔记，就地把上一张完整卡片退役：那一轮召回触发的位置留下一行标记（这样你总能看清召回发生在对话的哪里，不用滚动），而完整笔记作为新卡片落在它自己那一轮——只有最近一次完整召回留在模型可见的表面上（卡片的完整历史仍保留在会话日志里，可供回放）。退役按 bank 进行——当会话双重挂载到不同 bank 时，只有它的 OWNER 挂载会在那里提交（见 Mounting the plugin twice），所以只有 owner bank 的卡片能被退役。这个命名对应 llama-server 的 --no-reasoning-preserve：关掉它，一轮的快照就像它的推理一样，只活那一轮。代价是，退役的卡片会让模型缓存的 prefix 重新开始——中途步骤的笔记也按同样规则退役，而内容未变的召回则什么都不提交（不退役，也没有 prefix 开销），所以完全相同的重复步骤依然免费。

给插件配好它的 key

apiKeyRef: HINDSIGHT_API_KEY 只是一个名字——插件每次调用都会按这个名字去查值，顺序是：环境变量，然后 ~/.dsh/.credentials.yaml，然后 .env 文件。通常的做法是在 ~/.dsh/.credentials.yaml 里写一行，加在你现有条目旁边（比如 LLM key——不要替换掉它们）：

version: 1
refs:
HINDSIGHT_API_KEY: <the Hindsight server's token>