xuhdandClaude Opus 4.7
f9d7610679
以 Hermes 的可插拔记忆架构为骨架重写 deerflow 记忆模块,兼容原有 结构化数据,并新增 Hindsight 作为外部记忆后端。 P1 - 抽象层 + builtin 本地记忆: - MemoryProvider 抽象基类 + MemoryManager 编排层(builtin + ≤1 外部) - BuiltinFileProvider:USER.md/MEMORY.md 二元存储、字符配额、文件锁、 原子写、frozen snapshot - memory 工具(LangChain @tool):LLM 主动写入用户画像/工作笔记 - 记忆内容安全扫描(注入/外渗模式 + 不可见 unicode) - memory_config 改为嵌套结构 + 旧扁平字段兼容 + per-user 三层覆盖 - 迁移脚本 migrate_memory_to_v2.py:旧 memory.json -> USER.md/MEMORY.md - Gateway 新增 /api/memory/v2 与 v2/config 端点(用户可配置白名单字段) P2 - Hindsight 外部 provider: - HindsightProvider:双 bank 隔离(user bank 跨 agent 共享 + work bank agent 私有)、并发召回合并、auto-retain、on_memory_write 镜像 - hindsight_recall/reflect/retain 三个 LangChain 工具 - MemoryMiddleware.before_model 注入 Hindsight 动态召回 - context/tools/hybrid 三种 memory_mode - hindsight-client 作为可选依赖,未装时自动退回纯 builtin 注入走系统提示词(builtin frozen snapshot)+ before_model(Hindsight 动态召回)。后台抽取保留但默认关闭,P3 期重接入。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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` |
|