dsh-hindsight-memory

Readme

# dsh-hindsight-memory

把 [Hindsight](https://github.com/vectorize-io/hindsight) 变成 DeepSeek Harness 的
**管线级长期记忆**：不暴露任何 agent 工具，模型调用前后自动完成记忆的注入与留存
（即 Hermes Agent 的 `pre_llm_call` / `post_llm_call` 钩子模式）。

## 工作原理

| 钩子 | DSH 事件 | 行为 |
|---|---|---|
| Auto-Recall | `agent/pre-step`（waterfall） | **每轮一次**（对齐 Hermes 的 prologue 语义）：仅在 turn 的第一个 LLM 调用（step 1）前，取最新用户消息（≤800 字符）作 query 调 Hindsight `recall`，把相关记忆作为一条**插件来源的 user 消息**追加进步骤批次。后续 step 不再召回——turn 级 WeakMap 认领（防重放），工具循环内复用 step 1 已持久化的那一块。**琐碎输入跳过**（对齐 Hermes `is_trivial_prompt`）：“好的/嗯/ok/谢谢/继续”等寒暄确认及 `/` 斜杠命令不发起召回。 |
| Auto-Retain | `session/event`（observer） | 轮次结束（`turn/end`）后，从会话日志组装该轮 User/Assistant 文本，异步 `retain` 入库（fire-and-forget，绝不阻塞循环）。 |

- 标题生成、会话摘要等内务 LLM 调用不经过 agent loop，**天然不受记忆注入污染**。
- resume 会话通过 `session.firstLiveSeq` 跳过历史事件，**不会重复留存**旧轮次。
- Hindsight 任何故障都被隔离：recall 失败 → 本步无注入；retain 失败 → 仅记日志，聊天永不中断。
- 子 agent / fork 会话默认同样参与（`includeSubagents` 可关）。

## 设置界面

插件带浏览器半：重启后设置侧边栏会出现独立分节 **设置 → Hindsight 记忆插件**
（顶级条目，注册于 `settings.section` slot），可就地编辑并保存（写入
`settings.yaml` 的 `hindsight-memory:` 用户层，**实时生效、无需重启**）：

| 控件 | 字段 | 说明 |
|---|---|---|
| 启用开关 | `enabled` | 关闭后立即停止注入与留存 |
| API URL | `apiUrl` | Hindsight API 地址 |
| API KEY | `apiKey` | Bearer Token，留空不认证 |
| BANK ID | `bankId` | 记忆库名，多端指向同一 bank 即可共享记忆 |
| Recall Budget | `recallBudget` | low / mid / high 三档 |

每字段支持「重置」（回退到组合层配置值）；保存失败时保留草稿可修正重试。
配置分层遵循 DSH settings 语义：schema 默认值 ← bundle patch（base）← 用户层。

## 配置（全部可省略）

```yaml
- insert:
    - id: hindsight-memory
      name: dsh-hindsight-memory
      config:
        apiUrl: http://127.0.0.1:28888       # Hindsight API
        apiKey: ""                            # 可选 Bearer token
        bankId: dsh                           # 记忆 bank
        autoRecall: true
        autoRetain: true
        recallBudget: low                     # low / mid / high
        recallTypes: [observation]            # 只注入蒸馏后的观察层
        maxQueryChars: 800
        recallTimeoutMs: 8000                 # 服务端冷启动首个 recall 可能偏慢
        maxMemories: 8
        maxBlockChars: 4000
        retainContext: conversation between the DSH agent and the user
        retainTags: [source:dsh]
        includeSubagents: true
        retainEveryNTurns: 1
        verbose: false
```

bundle 自带的 `cordis.patch.yml` 已写入 `apiUrl` / `bankId` 默认值；在 profile 的
`cordis.patch.yml` 里再插一条同 id 的 insert 即可覆盖任意键。

## 安装

```sh
dsh plugin --profile web add dsh-hindsight-memory   # 或本地路径
```

安装器会把包写进 profile 依赖与 `dsh.profile.bundles`，bundle patch 随之生效。
重启 dsh web 后，宿主日志应出现：

```
hindsight-memory: active (api=… bank=… recall=true retain=true)
```

## 卸载 / 回滚

```sh
dsh plugin --profile web remove dsh-hindsight-memory
```

## 验证

1. 新会话告诉 agent 一个事实（如「我的服务器叫 atlas」），正常聊完一轮。
2. 打开 Hindsight UI（部署机的 29999 端口）→ bank `dsh`，应看到刚留存的
   `User: … / Assistant: …` 记忆。
3. 再开一个全新会话直接问「我的服务器叫什么」——回答应直接带上答案，
   全程没有调用任何工具。