127 lines
4.1 KiB
Markdown
127 lines
4.1 KiB
Markdown
# 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` |
|