# Hindsight 记忆后端接入指南

> Memory V2 的外部 provider。详见 `docs/MEMORY_V2_DESIGN_ZH.md`。

Hindsight 是带知识图谱、实体消解、多策略检索的长期记忆服务。DeerFlow 以 HTTP
客户端方式接入一个**你自己部署**的 Hindsight Docker 实例(`local_external` 模式)。

DeerFlow 不负责 Hindsight 的部署与运维 —— 它只是一个 HTTP 客户端。Hindsight 不可达
或未配置时,记忆系统自动退回纯 builtin 本地记忆,不影响任何功能。

---

## 1. 部署 Hindsight Docker

Hindsight 的官方镜像与部署方式请以 Hindsight 官方文档为准。典型的本地部署:

```bash
# 下面的 8765 只是占位示例。端口随你的 Hindsight 实例实际暴露的来,
# 例如映射成 9999、8888 等都行 —— deerflow 只认 config.yaml 里的 api_url。
docker run -d \
  --name hindsight \
  -p <宿主端口>:<容器端口> \
  -v hindsight-data:/data \
  <hindsight-镜像>

# 确认服务可达 (端口换成你实际暴露的)
curl http://localhost:<宿主端口>/health
```

数据卷 `hindsight-data` 用于持久化记忆库,容器重建时不丢数据。

> **端口说明**:deerflow 是纯 HTTP 客户端,只需要把 `api_url` 指向 Hindsight 的
> **HTTP API 端口**即可。如果你的实例同时暴露了多个端口 (例如 API 与 Web UI 各一个),
> `api_url` 填 HTTP API 那个;Web UI 端口 deerflow 不需要。

---

## 2. 安装客户端依赖

DeerFlow 侧需要 `hindsight-client` Python 包(可选依赖,默认不装):

```bash
cd offline-backend-20260512/backend
uv pip install 'hindsight-client>=0.4.22'
# 或安装 harness 的 hindsight extra:
uv pip install -e 'packages/harness[hindsight]'
```

未安装时 `HindsightProvider.is_available()` 返回 `False`,provider 不会被注册。

---

## 3. 配置 config.yaml

在项目根 `config.yaml` 的 `memory` 段:

```yaml
memory:
  enabled: true
  provider: hindsight              # 启用 Hindsight 外部 provider
  hindsight:
    mode: local_external
    api_url: http://localhost:8765  # 换成你实例实际暴露的 HTTP API 端口
    api_key: $HINDSIGHT_API_KEY    # 如果你的实例需要鉴权
    bank_id_template: "deerflow-user-{user_id}"
    work_bank_id_template: "deerflow-work-{user_id}-{agent_id}"
    memory_mode: context           # context / tools / hybrid
    recall_budget: mid             # low / mid / high
    auto_recall: true
    auto_retain: true
    retain_async: true
```

`api_key` 以 `$` 开头时按环境变量解析。把密钥放进 `.env`:

```
HINDSIGHT_API_KEY=your-key
```

---

## 4. 双 bank 隔离

Memory V2 用两个 bank 隔离记忆(B 方案):

| Bank | 模板 | 内容 |
|---|---|---|
| 全局 user bank | `deerflow-user-{user_id}` | 用户身份、偏好,跨 agent 共享 |
| agent 工作 bank | `deerflow-work-{user_id}-{agent_id}` | agent 私有工作笔记 |

- LLM 调 `memory(target="user")` → 镜像到 user bank
- LLM 调 `memory(target="memory")` → 镜像到 work bank
- 自动 retain 的对话 → work bank
- 召回时并发查两个 bank 并合并

模板占位符:`{user_id}` / `{agent_id}` / `{thread_id}`。

---

## 5. memory_mode 三种模式

| 模式 | 自动召回 | 自动写入 | 暴露工具给 LLM |
|---|---|---|---|
| `context` | ✅ | ✅ | ❌ LLM 看不到 Hindsight |
| `tools` | ❌ | ❌ | ✅ `hindsight_recall` / `reflect` / `retain` |
| `hybrid` | ✅ | ✅ | ✅ 自动 + 工具齐发 |

`tools` / `hybrid` 模式下,`get_available_tools` 会额外暴露 3 个 Hindsight 工具。

---

## 6. 迁移旧记忆到 Hindsight

P1 的迁移脚本 `scripts/migrate_memory_to_v2.py` 只迁移本地 USER.md / MEMORY.md。
把这些记忆灌进 Hindsight bank 的步骤将在后续提供。

---

## 7. 排查

| 现象 | 检查 |
|---|---|
| 记忆没召回 | `curl api_url/health`;`memory.provider` 是否为 `hindsight`;`injection.include_hindsight` |
| 启动日志报 "Hindsight provider 已配置但不可用" | `hindsight-client` 是否安装;`api_url` 是否配置 |
| LLM 看不到 Hindsight 工具 | `memory_mode` 是否为 `tools` 或 `hybrid` |
| 写入慢 | 确认 `retain_async: true` |