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

Hindsight 从 0 到跑通智能体记忆管理完整实战手册【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个智能体记忆系统它不只存对话历史而是让 Agent 把经历沉淀成可检索、可反思的长期记忆。本文走最短路径一条 Docker 命令起服务再用十几行 Python 跑通 retain存入→ recall检索→ reflect反思的完整闭环。你需要 Docker或 Python 3.11、一个 LLM API KeyOpenAI 即可。⚡ 先跑起来Docker 一键部署智能体记忆服务下面这条命令拉取官方镜像并启动内置 pg0 数据库挂成命名卷重启不丢数据8888 是 API 端口9999 是管理界面。export OPENAI_API_KEYsk-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用纯 Pythonpip 装好直接起服务数据同样落在本机pip install hindsight-api export HINDSIGHT_API_LLM_API_KEYsk-your-key hindsight-api启动后本机 8888 端口行为与 Docker 版完全一致后面所有客户端代码都能直接连它。团队内网共享一台机器 外部数据库给 3~10 个人共用用官方 compose 最合适它带一个装了 pgvector 的 PostgreSQL数据全部进库。这是典型的 docker compose 外部数据库配置。export HINDSIGHT_DB_PASSWORDchoose-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.replicaCounthelm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \ --set api.llm.provideropenai \ --set api.llm.apiKeysk-your-key \ --set postgresql.enabledtrue不想把 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/v1LM Studio。HINDSIGHT_API_DATABASE_URL — 换外部 PostgreSQL本地 Docker 别动它用内置 pg0生产改成托管库的postgresql://user:passhost: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_urlhttp://localhost:8888) # 指向你的服务 # 存入一条事实后台会做提取、向量化、建记忆条目 client.retain(bank_idmy-bank, contentAlice works at Google as a software engineer) # 检索向量 文本混合召回相关记忆 results client.recall(bank_idmy-bank, queryWhat does Alice do?) # 反思基于全部相关记忆生成一段有依据的回答 reply client.reflect(bank_idmy-bank, queryTell me about Alice)results返回非空列表、reply给出连贯回答闭环就跑通了。不想维护独立服务的话pip install hindsight-all后用HindsightEmbedded首次调用自动拉起本地守护进程数据按 profile 存在~/.pg0下。 踩坑速查compose 报 Please set the HINDSIGHT_DB_PASSWORD→ 变量没导出 →export HINDSIGHT_DB_PASSWORDxxx 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 框架大概率已经在里面了。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考