Hindsight 本地开发环境搭建指南从 uv 工作区到 API 客户端再生成的完整实践【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个为 AI Agent 提供持久记忆能力的开源系统Agent Memory That Learns其核心 API 服务基于 PostgreSQL 与 pgvector实现了时间、语义、实体图谱等多策略检索。本篇开发指南面向希望在本地搭建 Hindsight 开发环境、参与贡献或二次开发的工程师完整覆盖从环境准备、依赖安装、数据库启动、LLM 配置到测试运行与客户端代码再生成的每一个环节。读完本文你将能在一台干净的机器上把整个 Hindsight 跑起来并掌握其构建与代码生成流水线的工作原理。前置条件在开始之前需要准备以下环境对应仓库中的官方开发文档 version-0.6 开发指南Python 3.11Hindsight 的 API 服务hindsight-api/hindsight-api-slim为现代异步 Python 代码要求 3.11 及以上版本。uvAstral 出品的极速 Python 包管理器。仓库根目录的 pyproject.toml 声明了一个 uv workspace成员包括hindsight-all、hindsight-api、hindsight-api-slim、hindsight-all-slim、hindsight-dev、hindsight-mcp-server、hindsight-clients/python、hindsight-embed等多个包使用 uv 可以一次性同步整个工作区依赖。Docker 与 Docker Compose用于以容器方式启动 PostgreSQL以及后续的客户端代码生成步骤见下文。一个 LLM API KeyHindsight 的 retain记忆写入、reflect推理回答、consolidation记忆整合等操作都依赖 LLM。开发阶段可选择 OpenAI、Groq 或本地 Ollama。本地开发环境搭建1. 克隆仓库git clone https://github.com/vectorize-io/hindsight.git cd hindsight2. 安装依赖仓库使用 uv 管理依赖一条命令即可同步全部工作区成员uv sync根目录的 pyproject.toml 中index-strategy unsafe-best-match允许 uv 在所有配置的索引中搜索包这保证了在引入 PyTorch 等需要独立索引的依赖时仍能正确解析。同步完成后uv run即可在统一环境中执行任意命令如uv run pytest。3. 启动 PostgreSQLHindsight 的持久化依赖 PostgreSQL 与向量扩展。开发时可以用 Docker 只启动数据库cd docker docker-compose up -d postgres需要说明的是当前仓库的 Docker 编排集中在 docker/docker-compose 目录下按场景拆分为多个独立 compose 文件。最贴近文档描述的数据库优先方案是 external-pg该目录下唯一的 YAML 文件它使用带 pgvector 扩展的pgvector/pgvector镜像通过环境变量HINDSIGHT_DB_USER默认hindsight_user、HINDSIGHT_DB_PASSWORD必填、HINDSIGHT_DB_NAME默认hindsight_db、HINDSIGHT_DB_VERSION默认 18控制连接信息并将 API 服务与数据库编排在同一个hindsight-net网络中。此外alloydb、vchord、timescale 等目录提供了不同存储后端的参考编排。4. 配置环境变量从仓库根目录的 .env.example约 630 行、覆盖全部可配置项复制出开发配置cp .env.example .env编辑.env填入数据库连接与 LLM 提供商信息。文档给出的最小可用示例为# Database (connects to Docker postgres) HINDSIGHT_API_DATABASE_URLpostgresql://hindsight:hindsight_devlocalhost:5432/hindsight # LLM Provider (choose one) HINDSIGHT_API_LLM_PROVIDERgroq HINDSIGHT_API_LLM_API_KEYgsk_xxxxxxxxxxxx HINDSIGHT_API_LLM_MODELllama-3.1-70b-versatile.env.example中注释明确列出了受支持的 Provideropenai、openai-responses、groq、ollama、gemini、anthropic、lmstudio、vertexai、minimax、deepseek、zai、atlas、meta、volcano、openai-codex、claude-code、github-copilot。开发时可根据手头资源选择云 API需 Key如groqllama-3.1-70b-versatile、openaigpt-4o-mini这也是.env.example中主配置的默认值、anthropicclaude-sonnet-4-20250514、deepseek、zaiGLM 系列、minimax1M 上下文等。本地/订阅制无需 API KeyollamaHINDSIGHT_API_LLM_BASE_URLhttp://localhost:11434/v1、lmstudio默认http://localhost:1234/v1推荐 Qwen 2.5 32B、openai-codexChatGPT Plus/Pro OAuth、github-copilot需先用 Copilot CLI 登录。除 LLM 之外.env.example还沉淀了大量与开发调优直接相关的配置组理解它们有助于你按需裁剪开发环境API 服务HINDSIGHT_API_HOST默认0.0.0.0、HINDSIGHT_API_PORT默认8888、HINDSIGHT_API_LOG_LEVEL默认info。Embeddings默认本地模型HINDSIGHT_API_EMBEDDINGS_PROVIDERlocal默认模型BAAI/bge-small-en-v1.5也可切换onnx纯 CPU、tei、openai、cohere、google、litellm等。文档指出首次运行会下载 embedding 与 rerank 模型缓存于 HuggingFace 缓存目录。Reranker默认本地HINDSIGHT_API_RERANKER_PROVIDERlocal默认模型cross-encoder/ms-marco-MiniLM-L-6-v2。检索管线开关HINDSIGHT_API_ENABLE_TEXT_SEARCH、HINDSIGHT_API_ENABLE_TEMPORAL_RETRIEVAL、HINDSIGHT_API_ENABLE_GRAPH_RETRIEVAL、HINDSIGHT_API_ENABLE_RERANKING默认全部开启全部关闭时 recall 退化为单次向量查询。向量/文本检索扩展HINDSIGHT_API_VECTOR_EXTENSIONpgvector默认可换vchord、pgvectorscaleHINDSIGHT_API_TEXT_SEARCH_EXTENSIONnative默认可换vchord、pg_textsearch、pgroonga、pg_search。需要注意在main()入口见 main.py会先调用load_dotenv_for_entrypoint()加载.env再读取配置因此开发时修改.env后需重启服务生效。5. 启动 API 服务文档中的启动命令为./scripts/start-server.sh --env local服务器启动后监听 http://localhost:8888。在当前仓库中scripts目录下实际提供的是按场景拆分的开发脚本见 scripts/dev核心入口是 start-api.sh启动 API 数据面服务与 start-worker.sh启动后台 worker另有start-control-plane.sh管理端 UI与start-docs.sh文档站点等可理解为文档中start-server.sh的演进拆分。若不想借助脚本也可直接使用已安装的 CLI 命令。hindsight-api 的 README 说明了最简启动方式export HINDSIGHT_API_LLM_PROVIDERopenai export HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx hindsight-api其命令行入口定义在 pyproject.toml 的[project.scripts]hindsight-api hindsight_api.main:mainmain()内部基于argparse解析参数并通过 config.py 中DEFAULT_PORT 8888与ENV_PORT HINDSIGHT_API_PORT确定监听端口。常用 CLI 参数包括hindsight-api --help hindsight-api --port 9000 # 自定义端口默认 8888 hindsight-api --host 127.0.0.1 # 仅绑定本机 hindsight-api --workers 4 # 多 worker 进程 hindsight-api --log-level debug # 详细日志服务启动后会提供 REST API记忆操作以及位于/mcp的 MCP 端点供 Agent 工具调用集成。运行测试Hindsight 的测试主体位于 hindsight-api-slim/tests包含数百个测试文件test_recall_*.py、test_retain_*.py、test_consolidation_*.py、test_llm_*.py、test_mental_model_*.py等覆盖检索、写入、整合、LLM 适配、迁移与多租户等方方面面。运行方式# 运行全部测试 uv run pytest # 运行指定测试文件例如检索相关测试 uv run pytest tests/test_recall_config.py # 详细输出 uv run pytest -vhindsight-api-slim 的 pyproject.toml 中定义了 pytest 依赖pytest、pytest-asyncio、pytest-timeout、pytest-xdist、testcontainers等并配置了若干 marker如oracle需要ORACLE_TEST_DSN环境变量的 Oracle 23ai 集成测试、hs_llm_mat跨多 Provider 的 LLM 最小验收测试。参与贡献时PR 前必须保证uv run pytest全绿。代码生成OpenAPI 驱动的四语言客户端Hindsight 的客户端 SDK 不是手写的而是从 OpenAPI 规范自动生成这是贡献者修改 API 后必走的流水线。重新生成 API 客户端修改 OpenAPI spec 后运行./scripts/generate-clients.sh文档指出该脚本会生成 Python 与 TypeScript 客户端。从当前仓库的 generate-clients.sh 实现看它实际覆盖四种语言且对每种语言使用不同的生成器并做了大量生成后修补以保证产物可直接使用Rust构建期通过build.rs progenitor 自动生成脚本通过cargo build --release --locked触发再生成。Python用固定版本openapitools/openapi-generator-cli:v7.10.0Docker 运行--platform linux/amd64保证跨平台输出一致读取 spec 生成到临时目录再同步回 hindsight-clients/python。脚本会保护手工维护的封装层hindsight_client/hindsight_client.py与README.md并打上 PEP 561py.typed标记还会自动修补rest.py将 aiohttpTCPConnector的初始化推迟到首次请求异步上下文规避生成代码在__init__阶段要求运行中事件循环的 no running event loop 错误。TypeScript通过 hindsight-clients/typescript 目录下的npm run generatehey-api/openapi-ts版本固定在 package.json 中并对client.gen.ts打 Deno 兼容补丁从RequestInit中析构掉与 DenoHttpClient冲突的client字段。Go同样用 openapi-generator 生成随后修补 union 类型的MarshalJSON指针接收者为值接收者否则嵌入结构体按值序列化时自定义 marshaller 会被跳过、导致 422并修复api_files.go缺失os导入等问题go.mod/go.sum作为受维护文件被保留以保证再生确定性。输出目录均为仓库真实存在的路径Python 客户端hindsight-clients/pythonTypeScript 客户端hindsight-clients/typescriptGo 客户端hindsight-clients/goRust 客户端hindsight-clients/rust导出 OpenAPI Schema./scripts/export-openapi.sh在当前仓库中对应的实际脚本是 generate-openapi.sh它先进入hindsight-dev执行uv run generate-openapi生成规范再进入hindsight-docs执行npm run build重建文档站点。也就是说导出 OpenAPI 与文档构建是一条流水线完成的。项目结构文档给出了如下结构总览与当前仓库对照基本一致hindsight/ ├── hindsight-api/ # 主 API 服务器 │ ├── hindsight_api/ │ │ ├── api/ # HTTP 端点 │ │ ├── engine/ # 记忆引擎、检索、推理 │ │ └── web/ # 服务器入口 │ └── tests/ ├── hindsight-clients/ # 生成的 SDK 客户端 │ ├── python/ │ └── typescript/ ├── hindsight-control-plane/ # 管理端 UINext.js ├── docker/ # Docker Compose 编排 └── scripts/ # 开发脚本对照当前仓库几点值得补充的差异与细节API 实现核心代码实际位于 hindsight-api-slim/hindsight_apihindsight-api为发布到 PyPI 的聚合包名见 hindsight-api/README.md。其中 api 目录存放 HTTP/MCP 端点http.py、mcp.py、observability.py等engine 目录存放记忆引擎与各 Provider 适配llm_provider.py、retrieval、providers等config.py集中解析全部HINDSIGHT_API_*环境变量。测试主测试套件在 hindsight-api-slim/tests另有 hindsight-dev/tests、hindsight-system-tests/tests 等分层测试。控制面hindsight-control-plane 是基于 Next.js 的 Admin UI通过HINDSIGHT_CP_DATAPLANE_API_URL默认http://localhost:8888代理到数据面。Dockerdocker 下按场景拆分了多种编排external-pg、local-llm、tei、pg_search 等另有 standalone 的 Dockerfile 与启动脚本。贡献流程按照官方开发文档参与贡献的标准流程为从main创建功能分支完成代码修改运行测试uv run pytest提交 Pull Request仓库根目录还提供了 CONTRIBUTING.md 与 AGENTS.md、CLAUDE.md面向 AI 编码助手的项目说明以及 scripts/setup-hooks.sh安装 git hooks等辅助设施动手前值得一读。故障排查数据库连接问题先确认 PostgreSQL 容器是否在运行docker-compose ps再验证连接串是否可达psql postgresql://hindsight:hindsight_devlocalhost:5432/hindsight若使用仓库自带的 external-pg 编排注意其默认用户/库名是hindsight_user/hindsight_db需在.env的HINDSIGHT_API_DATABASE_URL中与之保持一致或显式设置HINDSIGHT_DB_USER、HINDSIGHT_DB_NAME。ML 模型下载首次运行时Hindsight 会下载 embedding 与 reranking 模型本地 Provider 默认分别是BAAI/bge-small-en-v1.5与cross-encoder/ms-marco-MiniLM-L-6-v2耗时可能数分钟。模型缓存在 HuggingFace 缓存目录~/.cache/huggingface/。若网络受限无法访问 HuggingFace.env.example也提供了HF_ENDPOINThttps://hf-mirror.com这类镜像环境变量以适配特定网络环境。端口冲突若 8888 端口被占用通过环境变量换端口该变量由 config.py 的ENV_PORT读取HINDSIGHT_API_PORT8889 ./scripts/start-server.sh --env local等价地使用 CLI 参数hindsight-api --port 8889或直接设置HINDSIGHT_API_PORT8889 hindsight-api均可。小结Hindsight 的本地开发链路是一条uv 同步依赖 → Docker 起库 → 环境变量驱动配置 → 一键起服务 → pytest 回归 → 脚本再生成客户端的完整流水线。理解 .env.example 中的配置分组与 generate-clients.sh 的生成-修补逻辑能让你在改动 API 或调优检索行为时快速定位到正确的配置入口与再生成步骤。对于任何希望让 Agent 拥有可学习、可检索、可推理持久记忆的开发者来说这套环境既是贡献的起点也是深入理解 Hindsight 内部机制的最佳入口。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考