企业官网建设流程全解析

Hindsight Deliveryman Demo：构建会"越送越聪明"的 AI 配送 Agent 完整实战指南

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

本文基于 Hindsight 官方文档中的 Deliveryman Demo 应用指南编写。该 Demo 是一个完整的可运行应用：一个 AI 配送 Agent 在多栋建筑组成的办公园区里完成送包裹任务，并借助 Hindsight 的长期记忆能力，逐步记住员工位置、楼栋布局与最优路径。读完本文，你将掌握从零启动 Hindsight API（含 LLM、提取模式、内置数据库等关键环境配置）、可选的 Control Plane 记忆检查界面、以及 Demo 前后端部署的完整流程，并理解 retain → 事实抽取 → mental models → 召回 这条记忆管线的实际工作机制。

Demo 定位：用记忆引擎驱动的长期学习型 Agent

Deliveryman Demo 的核心演示目标不是"送包裹"本身，而是展示 Hindsight 的long-term memory（长期记忆）能力在真实多轮交互中的表现：

• Agent 收到配送任务（例如 "Deliver Package #3954 to Victor Huang"）；
• 它在包含楼层、电梯、天桥（sky bridges）的多楼栋园区中导航；
• 途中遇到员工并学习他们的位置；
• 每次配送结束后，对话内容通过retain API发送给 Hindsight；
• Hindsight 从中抽取事实（员工位置、楼栋布局），并构建mental models（心智模型）；
• 下一次配送时，Agent 再向 Hindsight 发起查询，召回之前学到的内容。

Demo 的完整源码（FastAPI 后端 + React/Phaser 前端）位于独立的 hindsight-cookbook 仓库的deliveryman-demo目录下，本仓库仅承载 Hindsight 记忆引擎本体；本仓库的 cookbook 说明 即为该 Demo 的部署与运行文档。

前置条件

按原文档要求，运行该 Demo 需要：

• Python 3.11+
• Node.js 18+
• uv（Python 包管理器）

部署实战：六步启动完整链路

第 1 步：克隆仓库

需要两个仓库：Hindsight 本体（记忆引擎）与 hindsight-cookbook（包含本 Demo 的前后端代码）。Hindsight 仓库可克隆：

git clone https://gitcode.com/GitHub_Trending/hindsight2/hindsight

hindsight-cookbook 仓库提供deliveryman-demo子目录，内含backend/与frontend/。

第 2 步：配置并启动 Hindsight API

cd hindsight cp .env.example .env

编辑.env，写入 LLM 与存储配置：

HINDSIGHT_API_LLM_PROVIDER=groq HINDSIGHT_API_LLM_API_KEY=<your-groq-api-key> HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-120b HINDSIGHT_API_HOST=0.0.0.0 HINDSIGHT_API_PORT=8888 HINDSIGHT_API_ENABLE_OBSERVATIONS=true # Retain 提取设置（提升员工/位置信息的抽取效果） HINDSIGHT_API_RETAIN_EXTRACTION_MODE=custom HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS="Delivery agent. Remember employee locations, building layout, and optimal paths." # 内嵌数据库存储 PG0_DATA_DIR=/tmp/hindsight-data

各配置项的含义，结合本仓库源码可以进一步确认：

• HINDSIGHT_API_ENABLE_OBSERVATIONS：控制是否启用 observations（观察）能力。该变量在 config.py 中定义，且默认值即为True（config.py），Demo 中显式写true是为了让 Agent 的"途经观察"参与记忆沉淀。
• HINDSIGHT_API_RETAIN_EXTRACTION_MODE：retain 流水线的抽取模式。源码中允许取值为("concise", "verbose", "custom", "verbatim", "chunks")，默认concise（config.py）。Demo 选择custom，即使用自定义指令引导抽取。
• HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS：自定义抽取提示词，仅在custom模式下生效。源码在创建/更新 bank 时会强校验二者的一致性：若设置了retain_custom_instructions但retain_extraction_mode不是custom，API 会直接报错（http.py）。这解释了 Demo 排障表中"mental models 缺少员工信息 → 检查是否设置了custom模式"这一条：两者必须成对出现。
• PG0_DATA_DIR：将数据库数据目录指向本地路径，使用内嵌的 PostgreSQL（pg0）存储，免去额外安装 Postgres。
• HINDSIGHT_API_HOST/HINDSIGHT_API_PORT：监听地址与端口，Demo 约定0.0.0.0:8888，后端与前端均以此为HINDSIGHT_API_URL指向。

然后启动 API：

./scripts/dev/start-api.sh # 运行在 http://localhost:8888

查看 start-api.sh 的源码可知，该脚本的逻辑很直接：强制要求项目根目录存在.env（缺失即报错退出），用set -a导出其中全部变量，再执行uv run hindsight-api "$@"。这也意味着修改.env后必须重启该脚本才会生效。

第 3 步（可选）：启动 Control Plane

Control Plane 是一个 Web UI，用于检查 memory bank、facts 与 mental models 的内容——对于观察"Agent 到底学到了什么"非常有帮助：

cd hindsight ./scripts/dev/start-control-plane.sh # 运行在动态端口（查看终端输出）

从 start-control-plane.sh 源码看，它会先npm run build -w @vectorize-io/hindsight-client构建 TypeScript SDK，再启动 Next.js dev server；端口默认9999（可用HINDSIGHT_CP_PORT覆盖），数据面地址默认指向http://localhost:8888（可用HINDSIGHT_CP_DATAPLANE_API_URL覆盖），与第 2 步的 API 端口正好对应。

第 4 步：启动 Demo 后端

cd hindsight-cookbook/deliveryman-demo/backend # 创建虚拟环境并安装依赖 python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

创建backend/.env：

OPENAI_API_KEY=<your-openai-api-key> GROQ_API_KEY=<your-groq-api-key> HINDSIGHT_API_URL=http://localhost:8888 LLM_MODEL=openai/gpt-4o

启动后端：

./run.sh # 或手动： python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --ws wsproto --reload

注意：--ws wsproto参数是 WebSocket 支持的硬性要求。缺失时浏览器连接会失败并报 1006 错误——这是原文档明确标注的已知坑点，也是排障表的第一条。

第 5 步：启动 Demo 前端

cd hindsight-cookbook/deliveryman-demo/frontend npm install npm run dev # 运行在 http://localhost:5173

第 6 步：打开 Demo

浏览器访问 http://localhost:5173 即可开始配送任务，观察 Agent 随配送次数增加而"越来越熟"的过程。

架构总览

原文档给出的三层架构：

Browser (5173) → Frontend (React + Phaser) ↓ WebSocket Backend (8000) → FastAPI + Delivery Agent ↓ HTTP Hindsight API (8888) → Memory Engine + PostgreSQL

• 5173 端口（前端）：React + Phaser 负责园区场景渲染与交互；
• 8000 端口（后端）：FastAPI 承载 Delivery Agent 逻辑，通过 WebSocket 向前端推送实时状态；
• 8888 端口（Hindsight API）：记忆引擎本体，PostgreSQL 存储。

记忆数据流的闭环是：Agent 完成一次配送 → 会话内容经retain写入 Hindsight → Hindsight 抽取事实并更新 mental models → 下一次配送前 Agent 通过recall/查询召回已学知识。这一"写—提炼—读"的循环正是该 Demo 与一次性 RAG 应用的本质区别：知识在多次任务间持续积累。

排障速查表

继承原文档的 Troubleshooting 内容，并补充源码层面的成因说明：

另外从 start-api.sh 的实现看，.env在启动时一次性加载导出，改配置不重启不生效，这是配置类问题的常见根因。

小结与扩展方向

Deliveryman Demo 展示了 Hindsight 的典型使用范式：把 Agent 的完整会话通过 retain 沉淀为结构化事实与 mental models，再在后续任务中主动召回。若要进一步深化，可以：

1. 切换抽取模式对比效果：将HINDSIGHT_API_RETAIN_EXTRACTION_MODE从custom改为verbose或默认的concise（取值范围见 config.py），对比同一场景下 mental models 的丰富度；
2. 用 Control Plane 观察记忆演化：在两次配送之间打开 Control Plane（默认 9999 端口），直接查看 bank 中的 facts 与 mental models 变化；
3. 调整 bank 级配置：retain 相关参数（如retain_extraction_mode、retain_custom_instructions）也可通过 bank 配置以环境变量形式（HINDSIGHT_API_RETAIN_EXTRACTION_MODE）下发覆盖，相关字段说明见 http.py。

以上配置均以当前仓库的实际实现为准；Demo 前后端代码位于独立的 hindsight-cookbook 仓库，运行环境要求（Python 3.11+、Node.js 18+、uv）与.env示例以原文档为基准。

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