Hindsight 从 0 到跑通：智能体记忆管理完整实战手册

【免费下载链接】hindsight Hindsight: Agent Memory That Learns 项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

Hindsight 是一个智能体记忆系统，它不只存对话历史，而是让 Agent 把经历沉淀成可检索、可反思的长期记忆。本文走最短路径：一条 Docker 命令起服务，再用十几行 Python 跑通 retain（存入）→ recall（检索）→ reflect（反思）的完整闭环。你需要 Docker（或 Python 3.11+）、一个 LLM API Key（OpenAI 即可）。

⚡ 先跑起来：Docker 一键部署智能体记忆服务

下面这条命令拉取官方镜像并启动，内置 pg0 数据库挂成命名卷，重启不丢数据；8888 是 API 端口，9999 是管理界面。

export OPENAI_API_KEY=sk-your-key   # 换成你自己的 key

docker run -it --pull always --name hindsight --restart unless-stopped \
  -p 8888:8888 -p 9999:9999         # 端口冲突时改成 18888:8888 这种形式
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -v hindsight-data:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest

此时浏览器打开 http://localhost:9999 应看到管理界面（初始银行列表为空属正常）；API 侧执行 curl http://localhost:8888/health，返回 200 即成功。

🧭 按场景选路

本地试 5 分钟：不想装 Docker，用纯 Python

pip 装好直接起服务，数据同样落在本机：

pip install hindsight-api
export HINDSIGHT_API_LLM_API_KEY=sk-your-key
hindsight-api

启动后本机 8888 端口行为与 Docker 版完全一致，后面所有客户端代码都能直接连它。

团队内网共享：一台机器 + 外部数据库

给 3~10 个人共用，用官方 compose 最合适：它带一个装了 pgvector 的 PostgreSQL，数据全部进库。这是典型的 docker compose 外部数据库配置。

export HINDSIGHT_DB_PASSWORD=choose-a-strong-password  # compose 强制校验此项
cd docker/docker-compose
docker compose up -d

成功标志：docker compose ps 里 db 和 hindsight 两个容器都是 running，浏览器打开 http://localhost:9999 能看到各 bank 的记忆统计。

生产 / 多副本：Helm 一次搞定

K8s 上用仓库自带的 chart，副本数走 helm values 的 api.replicaCount：

helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \
  --set api.llm.provider=openai \
  --set api.llm.apiKey=sk-your-key \
  --set postgresql.enabled=true

不想把 key 写在 --set 里，改用 --set api.secrets.HINDSIGHT_API_LLM_API_KEY="$OPENAI_API_KEY"，或用 existingSecret 指向一个已存在的 Secret。

🔑 关键配置逐项讲

HINDSIGHT_API_LLM_API_KEY — 模型密钥，必填

没有它第一次 retain 就会失败。Docker 用 -e 注入，Helm 放 Secret 里。

HINDSIGHT_API_LLM_PROVIDER — 用哪家模型

默认 openai。可换 anthropic、gemini、groq、deepseek，也能跑本地 ollama、lmstudio，任何 OpenAI 兼容端点均可。

HINDSIGHT_API_LLM_MODEL — 模型名

不填则用各 provider 的默认模型。切 provider 时记得同步改它，否则常见"model not found"报错。

HINDSIGHT_API_LLM_BASE_URL — 自定义模型端点

本地部署或走网关时填，例如 http://localhost:1234/v1（LM Studio）。

HINDSIGHT_API_DATABASE_URL — 换外部 PostgreSQL

本地 Docker 别动它（用内置 pg0）；生产改成托管库的 postgresql://user:pass@host:5432/db 即可，compose 示例参考 docker/docker-compose/external-pg/。

api.replicaCount — Helm 的 API 副本数

默认 1。生产环境提到 2~3 前，先确认所有副本共享同一个 PostgreSQL，否则每个副本各用各的本机 pg0，记忆互不相通。

🔌 接入你的代码：用 Python 跑通记忆管理闭环

装客户端后，十个对象、三步调用：

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")  # 指向你的服务

# 存入一条事实（后台会做提取、向量化、建记忆条目）
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")

# 检索：向量 + 文本混合召回相关记忆
results = client.recall(bank_id="my-bank", query="What does Alice do?")

# 反思：基于全部相关记忆生成一段有依据的回答
reply = client.reflect(bank_id="my-bank", query="Tell me about Alice")

results 返回非空列表、reply 给出连贯回答，闭环就跑通了。不想维护独立服务的话，pip install hindsight-all 后用 HindsightEmbedded：首次调用自动拉起本地守护进程，数据按 profile 存在 ~/.pg0 下。

🧯 踩坑速查

• compose 报 "Please set the HINDSIGHT_DB_PASSWORD" → 变量没导出 → export HINDSIGHT_DB_PASSWORD=xxx && docker compose up -d
• 容器起来了，第一次 recall 却 401 → key 没注入容器 → 补 -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY 后重建
• 重启后记忆全没了 → pg0 卷没挂 → 确认 -v hindsight-data:/home/hindsight/.pg0 存在
• 8888 端口被占用 → 别的进程占了端口 → 改映射为 -p 18888:8888，客户端 base_url 同步改
• 换了 provider 后调用直接报错 → 只改了 key 没改 provider → HINDSIGHT_API_LLM_PROVIDER 与 HINDSIGHT_API_LLM_MODEL 成对设置
• 本地 ollama 报模型不存在 → 默认模型名和你本地模型对不上 → 显式指定 HINDSIGHT_API_LLM_MODEL

📚 下一步读什么

• 安装完整参考：裸机、Windows、离线环境
• 环境变量配置全表
• Mental Models：长期记忆如何被巩固

跑通之后去翻翻 hindsight-integrations/ 目录，你手上的 Agent 框架大概率已经在里面了。

【免费下载链接】hindsight Hindsight: Agent Memory That Learns 项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight