deerflow-code/offline-backend-20260512/backend/docs/HINDSIGHT_SETUP_ZH.md

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 官方文档为准。典型的本地部署:

# 下面的 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 包(可选依赖,默认不装):

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 段:

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