AI Agent 长期记忆系统实战：Hindsight + vLLM 全本地 GPU 部署

starrysky810
18 阅读6分钟

10KB 的系统提示词记忆区 → 知识图谱驱动的语义检索。从 hermes-agent 出发，一步步搭建自带 GPU 向量检索引擎的长期记忆系统。

一、为什么 AI Agent 需要自己的记忆系统？

LLM 本身是无状态的。每次对话结束，上下文就消失了。AI Agent 框架（hermes-agent、Claude Code、Codex 等）通过两种方式解决这个问题：

1. 系统提示词注入（hermes-agent 的 memory 工具） 每次新会话，把历史记忆拼进 system prompt。问题是：有 10,000 字符硬限制。跑几天就满了——旧记忆被挤出，新记忆没位置。

2. 外部向量数据库 把记忆存到外部的向量库里，按需检索注入。容量无限，检索精准。

本文讲的是第 2 种——如何给 hermes-agent 挂一个完整的本地记忆系统。

二、选型：Hindsight 对比其他方案

hermes-agent v0.15.0 内置了 8 个 memory provider 插件：Honcho、Mem0、Supermemory、Byterover、Hindsight、Holographic、OpenViking、RetainDB。

为什么选 Hindsight？

特性Hindsight其他 provider
部署模式Cloud / Local Embedded / Local External多数仅云
本地 GPU✅ 支持外部 embedding 服务❌
知识图谱✅ 实体解析 + 关系图部分支持
检索方式语义 + 关键词 + 实体图遍历 + 重排序多为纯向量
自动提取✅ auto_retain 自动结构化事实部分支持
中文嵌入✅ 可指定 bge-large-zh默认英文

最关键的：Hindsight 支持 local_external 模式——你可以自己部署 embedding 服务，Hindsight 只负责存储和检索。这意味着你可以用任何兼容 OpenAI API 的 embedding 服务，包括本地 GPU 跑 vLLM。

三、架构：三种部署模式

模式 A：local_embedded（最简，5 分钟）

hermes-agent 本机
┌──────────────────────────┐
│ Hindsight daemon (自动管理)│
│ ├ BGE-small (CPU, 130MB) │
│ ├ PostgreSQL (pg0 内嵌)  │
│ └ LLM 提取 → 任何 API    │
└──────────────────────────┘

一条命令：

hermes memory setup  # 选 hindsight → local_embedded

适合：快速体验。embedding 跑 CPU，个人使用完全够。

模式 B：local_embedded + 外部 GPU embedding

GPU 服务器 (可选)          hermes-agent 本机
┌──────────────┐          ┌──────────────────────────┐
│ vLLM / TEI   │←────────│ Hindsight daemon          │
│ bge-large    │  内网    │ embedding provider=openai │
│ :8000        │          │ → http://gpu-server:8000  │
└──────────────┘          └──────────────────────────┘

配置：

{
  "mode": "local_embedded",
  "llm_provider": "groq",
  "llm_api_key": "你的key"
}

# Hindsight 环境变量
HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=http://gpu-server:8000/v1
HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL=BAAI/bge-large-zh-v1.5

适合：已有 GPU 服务器，想加速 embedding。

模式 C：全 Docker 部署（本文重点）

GPU 节点 (Docker)                     hermes-agent 本机
┌────────────────────────────┐       ┌────────────────────┐
│ vLLM 容器          :8000   │       │ config.yaml:        │
│ + Hindsight 容器    :8888   │←─────│ memory.provider:    │
│   ├ LLM → 任何 provider   │ HTTP  │   hindsight         │
│   ├ Embedding → vLLM(GPU) │       │ mode: local_external│
│   └ PG (pg0)              │       └────────────────────┘
└────────────────────────────┘

优势：每个组件独立容器，可分别部署到不同机器，升级和排障互不影响。

四、实战：Jetson Orin 上部署 vLLM + Hindsight

4.1 硬件要求

组件最低推荐
vLLM + bge-large4GB 显存8GB+
Hindsight512MB RAM1GB
PostgreSQL512MB RAM1GB
总计~5GB 显存 + 2GB RAM—

我用的是 NVIDIA Jetson AGX Orin（30GB 统一内存，CUDA 12.6）。普通 Linux 服务器 + NVIDIA GPU 也完全适用。

4.2 关键镜像

vLLM 没有官方 ARM64 镜像。Jetson 用户需要用社区编译版：

ghcr.io/yuyirobotlab/vllm-orin:0.19.0

x86_64 用户直接用官方：

docker pull vllm/vllm-openai:latest

Hindsight 官方支持多架构：

ghcr.io/vectorize-io/hindsight-api:latest  # 支持 amd64 + arm64

国内用户拉镜像慢，可用 GHCR 代理：

docker pull ghcr.1ms.run/vectorize-io/hindsight-api:latest

4.3 启动 vLLM embedding 服务

docker run -d --name vllm \
  --network host \
  --gpus all \
  -e HF_ENDPOINT=https://hf-mirror.com \
  vllm/vllm-openai:latest \
  --model BAAI/bge-large-zh-v1.5 \
  --runner pooling \
  --host 0.0.0.0 --port 8000 \
  --gpu-memory-utilization 0.3 \
  --enforce-eager

几个关键参数说明：

  • --runner pooling：vLLM 0.19+ 的 embedding 模式（旧版用 --task embedding 已弃用）
  • --gpu-memory-utilization 0.3：embedding 模型只有 1.3GB，不需要占满显存
  • --enforce-eager：跳过 JIT 编译加速首次启动（Jetson 上编译要 10+ 分钟）
  • HF_ENDPOINT：国内必设，否则模型下载失败

验证：

curl http://localhost:8000/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"BAAI/bge-large-zh-v1.5","input":"你好世界"}'
# 返回 1024 维 embedding

4.4 启动 Hindsight

docker run -d --name hindsight \
  --network host \
  --restart unless-stopped \
  -e HINDSIGHT_API_LLM_PROVIDER=opencode-go \
  -e HINDSIGHT_API_LLM_API_KEY=*** \
  -e HINDSIGHT_API_LLM_MODEL=deepseek-v4-flash \
  -e HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai \
  -e HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=http://localhost:8000/v1 \
  -e HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL=BAAI/bge-large-zh-v1.5 \
  -v /data/hindsight:/root/.hindsight/data \
  ghcr.io/vectorize-io/hindsight-api:latest

LLM provider 可换成任何平台：

# OpenAI
HINDSIGHT_API_LLM_PROVIDER=openai
# Groq (免费额度)
HINDSIGHT_API_LLM_PROVIDER=groq
# OpenRouter（路由多模型）
HINDSIGHT_API_LLM_PROVIDER=openrouter
# Ollama 本地模型
HINDSIGHT_API_LLM_PROVIDER=ollama

验证：

curl http://localhost:8888/health
# {"status":"healthy","database":"connected"}

4.5 Jetson 特殊注意事项

# 桥接网络不可用，必须 host 模式
--network host

# GPU 通过 CDI 访问（非 --gpus all）
--device nvidia.com/gpu=all

# containerd 数据盘可能不在 /var/lib
ls -la /var/lib/containerd  # 如果是软链接，说明已迁移

# 禁用 apt 自动更新（Jetson 内存紧张）
sudo systemctl mask apt-daily.timer
sudo systemctl mask apt-daily-upgrade.timer

五、hermes-agent 接入

本机三步：

1. 安装依赖

pip install hindsight-client==0.6.1

2. 配置 config.yaml

memory:
  provider: hindsight

3. 配置 Hindsight 连接

// ~/.hermes/hindsight/config.json
{
  "mode": "local_external",
  "api_url": "http://你的Hindsight服务器IP:8888",
  "memory_mode": "hybrid",
  "auto_retain": true,
  "auto_recall": true,
  "recall_budget": "mid"
}

4. /reset 生效

之后每轮对话：

  • 对话前 → Hindsight 自动检索相关记忆，注入上下文
  • 对话后 → 自动提取结构化事实，存入知识图谱
  • 工具：hindsight_retain（手动存）、hindsight_recall（手动查）、hindsight_reflect（综合推理）

六、记忆导入策略

hermes-agent 的 session 文件可能有几千个。全量导入没必要——session_search 已经做了 FTS5 全文索引。

建议分层：

层内容方式
L1 核心系统配置、环境变量、路径手动 hindsight_retain
L2 偏好用户画像、工作风格、安全规则手动
L3 流程已验证的工作流、常见 Pitfall手动 / 写脚本
L4 历史近期 session 摘要可选，脚本批量
-全量 session 原文不需要——session_search 已覆盖

七、成本控制

Hindsight 每次自动提取事实都会调一次 LLM（auto_retain）。频繁对话 → 费用高涨。

控制方法：

# 调大提取间隔
HINDSIGHT_API_RETAIN_EVERY_N_TURNS=12

# 或关掉自动提取，只用手动
# auto_retain: false

配合 hermes-agent config 的 flush_min_turns 兜底短 session。

八、常见问题

Q: vLLM 启动报 no kernel image is available？ A: 镜像和 GPU 的 CUDA 架构不匹配。Jetson Orin 需要 SM 8.7 编译的镜像。用 yuyirobotlab/vllm-orin 或自己编译。

Q: Hindsight 连不上 vLLM？ A: Docker 网络模式问题。如果都用 --network host，确认 vLLM 已完全启动后再启 Hindsight（vLLM 下载模型需要几分钟）。

Q: embedding 模型能换成英文的吗？ A: 改成 BAAI/bge-large-en-v1.5 即可。中文用 bge-large-zh-v1.5。

Q: 已有记忆怎么迁移？ A: 把旧记忆用 hindsight_retain 逐条写入。MEMORY.md 可以一次喂一整段。

Q: 数据存在哪？ A: Hindsight 默认用内嵌 PostgreSQL（pg0），数据在 ~/.hindsight/data/（或你挂载的 volume 目录）。

九、总结

维度传统 memory 工具Hindsight
容量10KB / 系统提示词限制无限制
检索全文注入（浪费 token）语义检索 + 实体图（按需注入）
存储纯文本 key-value结构化事实 + 实体关系
LLM 成本零（但每次都要读全文）按需提取（可控频率）
embedding无本地 CPU / GPU / 远程
部署零~2GB RAM + 可选 GPU

全程可以用自己的 GPU 跑 embedding，LLM 提取用已有的 API key——零额外固定成本。对个人开发者来说，这是一套「用到退休」的 Agent 记忆方案。

avatar
文章
阅读
粉丝