企业官网建设流程全解析

Hindsight API 使用指南：为 AI Agent 构建会学习的时间—语义—实体记忆系统

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

Hindsight API 是一套面向 AI Agent 的持久化记忆系统，基于 PostgreSQL + pgvector 构建，同时融合**时间（Temporal）、语义（Semantic）、实体（Entity）**三种记忆能力。本文以 hindsight-api-slim/README.md 为核心脉络，完整覆盖安装、启动、Python SDK 编程、CLI 与配置、Docker 部署、MCP 集成等实战内容，并结合仓库源码深入讲解 TEMPR 多策略检索、实体图谱、时间推理、性格特质与三类记忆的底层实现，帮助你在本地最快跑通一整套"存储—召回—反思"记忆闭环。

从 README 出发：Hindsight API 是什么

Hindsight 给 AI Agent 提供"像人一样工作"的长期记忆：它不仅存储事实，还追踪实体与实体间的关系，支持时间推理（例如"去年春天发生了什么？"），并能基于可配置的**性格特质（disposition traits）**形成观点。其核心定位在 hindsight-api-slim/README.md 中被概括为：

Memory System for AI Agents— Temporal + Semantic + Entity Memory Architecture using PostgreSQL with pgvector.

围绕这一主题，仓库内对应实现位于 hindsight-api-slim/hindsight_api，其中 engine/memory_engine.py 是记忆引擎的核心实现，config.py 是全部环境变量的集中定义，api/http.py 承载 REST API 端点，engine/reflect、engine/search、engine/retain 则分别对应反思、检索与事实抽取三大子模块。

安装：一条 pip 命令起步

pip install hindsight-api

需要说明的是，README 中的hindsight-api发行名在仓库中对应的是 hindsight-api-slim/pyproject.toml（包名hindsight-api-slim，版本 0.9.2，要求 Python >= 3.11）。该pyproject.toml也揭示了依赖选型的关键信息，可作为排障参考：

• 数据库驱动：asyncpg>=0.30.0提供异步 PostgreSQL 访问，sqlalchemy>=2.0.44,<2.1（特意钉在 2.0 线，因为 2.1 起默认 DBAPI 切换为 psycopg3，裸装环境会因缺少psycopg模块导致迁移失败），pgvector>=0.4.1提供向量类型支持；
• LLM 层：openai>=1.66.0（Responses API）、anthropic>=0.40.0、google-genai>=1.72.0、litellm>=1.93.0（macOS 上钉在 1.91.x 纯 Python wheel 线）；
• Web/服务层：fastapi[standard]>=0.120.3、uvicorn>=0.38.0、fastmcp>=3.2.0（MCP 协议支持）；
• 附加依赖组（extras）：embedded-db（pg0-embedded>=0.15.0，内嵌 PostgreSQL）、local-ml（本地嵌入/重排模型，sentence-transformers 等）、local-llm（内置 llama.cpp 推理，完全离线运行）、local-onnx（进程内 ONNX Runtime 嵌入）。

在仓库环境中，也可通过uv直接运行，例如uvx hindsight-api（见 pyproject.toml 中对 macOS 纯 wheel 的说明）。若只想要内嵌数据库能力，可安装hindsight-api-slim[embedded-db]。

Quick Start：60 秒跑起记忆服务器

启动服务端

# 设置 LLM 提供商 export HINDSIGHT_API_LLM_PROVIDER=openai export HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxxxx # 启动服务（默认使用内嵌 PostgreSQL） hindsight-api

服务启动后默认监听 http://localhost:8888，提供两类能力：

• REST API：用于记忆操作；
• MCP 服务器：挂载在/mcp，供工具调用式集成。

"默认使用内嵌 PostgreSQL"并非营销话术：HINDSIGHT_API_DATABASE_URL的默认值是pg0（见 config.py 的DEFAULT_DATABASE_URL = "pg0"），由 pg0.py 中的EmbeddedPostgres类负责拉起一个进程内的 PostgreSQL 实例，默认用户名/密码/库名均为hindsight，端口自动分配，并带 5 次重试（指数退避）的启动逻辑；若你显式传入连接串，引擎会跳过 pg0 直接连外部库（见memory_engine.initialize()中start_pg0()的判断逻辑，memory_engine.py）。

使用 Python API

from hindsight_api import MemoryEngine # 创建并初始化记忆引擎 memory = MemoryEngine() await memory.initialize() # 为你的 Agent 创建一个记忆库（memory bank） bank = await memory.create_memory_bank( name="my-assistant", background="A helpful coding assistant" ) # 存储一条记忆 await memory.retain( memory_bank_id=bank.id, content="The user prefers Python for data science projects" ) # 召回记忆 results = await memory.recall( memory_bank_id=bank.id, query="What programming language does the user prefer?" ) # 带推理的反思 response = await memory.reflect( memory_bank_id=bank.id, query="Should I recommend Python or R for this ML project?" )

上面四个核心操作在源码中的对应关系如下（便于深入阅读）：

• MemoryEngine.initialize()：并行完成 pg0 启动、嵌入模型加载、连接池与后台任务初始化，见 memory_engine.py；
• create_memory_bank：走ensure_bank路径，幂等创建银行行与存储（见 memory_engine.py），同名/同 ID 的 bank 重复创建不会产生副作用；
• retain：MemoryEngine.retain()是同步便捷包装（内部asyncio.run调retain_async，见 memory_engine.py），生产环境建议直接用retain_async以获得更高吞吐；
• recall：同样提供同步包装，底层是"4 路并行检索"（见 memory_engine.py）；
• reflect：reflect_async实现了一个只读的 agentic 循环——反思智能体迭代调用lookup（查心理模型）、recall（语义+时间检索）、search observations（检索既有观察）与expand（获取 chunk/文档上下文）等工具，最终综合答案且不写入任何内容（见 memory_engine.py）。

CLI 选项：精细控制服务进程

hindsight-api --help # 常用选项 hindsight-api --port 9000 # 自定义端口（默认 8888） hindsight-api --host 127.0.0.1 # 仅绑定 localhost hindsight-api --workers 4 # 多 worker 进程 hindsight-api --log-level debug # 详细日志

CLI 实现位于 main.py，除 README 列出的四项外还支持（详见_parse_cli_args）：

• --reload：开发期代码变更自动重载（仅开发使用）；
• --access-log/--no-access-log：开启/关闭访问日志（默认关闭，DEFAULT_ACCESS_LOG = False）；
• --proxy-headers/--forwarded-allow-ips：信任反向代理的X-Forwarded-*头；
• --ssl-keyfile/--ssl-certfile：直接启用 HTTPS；
• --daemon：以后台守护进程方式运行（默认绑定127.0.0.1，端口由DEFAULT_DAEMON_PORT决定；显式--host/HINDSIGHT_API_HOST会覆盖该安全默认值）。

从源码看，hindsight-api的--workers N会交给 uvicorn 以 spawn 方式拉起多进程；为了保证每个 worker 快速就绪，main.py 刻意将MemoryEngine、create_app等重依赖改为模块级懒加载（PEP 562__getattr__），使 worker 启动从数秒级降到数百毫秒级。

pyproject.toml还声明了另外三个入口命令，同样值得关注：

• hindsight-worker：独立 worker 进程，用于分布式任务处理（hindsight_api.worker.main:main）；
• hindsight-local-mcp：本地 stdio MCP 服务器（hindsight_api.mcp_local:main）；
• hindsight-admin：管理 CLI（hindsight_api.admin.cli:main），支持备份恢复、银行转账等运维操作。

配置：环境变量即配置面

所有配置都通过HINDSIGHT_API_前缀的环境变量注入，集中定义在 config.py，并由load_dotenv_for_entrypoint()在入口处加载.env文件（.env优先于进程环境，见 config.py）。README 给出的核心变量如下：

上述默认值在源码中均有对应常量：DEFAULT_DATABASE_URL = "pg0"、DEFAULT_LLM_PROVIDER = "openai"、DEFAULT_LLM_MODEL = "gpt-4o-mini"（当提供商不在默认模型表中时的回退值）、DEFAULT_HOST = "0.0.0.0"、DEFAULT_PORT = 8888、DEFAULT_WORKERS = 1、DEFAULT_LOG_LEVEL = "info"（见 config.py 与 config.py）。

值得一提的是 config.py 在仓库中是"唯一的环境读取者"（对应测试test_config_is_the_only_env_reader.py），并且配置分**静态字段（static）与层级字段（hierarchical）**两类：静态字段（如数据库 URL、端口、worker 设置）只能服务级全局设定；层级字段（如 LLM 参数、保留策略、检索参数）可在租户/银行（bank）级通过ConfigResolver覆盖。若代码误用全局配置读取银行级字段，会抛出ConfigFieldAccessError（见 config.py）。

连接外部 PostgreSQL 的示例

export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@localhost:5432/hindsight export HINDSIGHT_API_LLM_PROVIDER=groq export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx hindsight-api

切换到外部库后，服务会在启动时自动执行数据库迁移（Alembic 迁移脚本位于 hindsight_api/alembic），无需手动建表。

值得知道的进阶配置（来自源码）

config.py 定义了远超 README 表格的配置面，按功能可归纳为几组，实操中经常用到：

• LLM 行为：HINDSIGHT_API_LLM_BASE_URL（自定义网关地址）、HINDSIGHT_API_LLM_MAX_CONCURRENT（并发上限）、HINDSIGHT_API_LLM_MAX_RETRIES/HINDSIGHT_API_LLM_INITIAL_BACKOFF/HINDSIGHT_API_LLM_MAX_BACKOFF（重试与退避）、HINDSIGHT_API_LLM_TIMEOUT/HINDSIGHT_API_LLM_CONNECT_TIMEOUT（超时）、HINDSIGHT_API_LLM_REASONING_EFFORT、HINDSIGHT_API_LLM_TEMPERATURE（全局采样温度，可省略为none/default/off以适配拒绝显式温度的模型）以及按操作拆分的HINDSIGHT_API_RETAIN_LLM_*、HINDSIGHT_API_REFLECT_LLM_*、HINDSIGHT_API_CONSOLIDATION_LLM_*系列，可让 retain/reflect/consolidation 各用不同模型；
• 嵌入与重排：HINDSIGHT_API_EMBEDDINGS_PROVIDER、HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL、HINDSIGHT_API_EMBEDDINGS_TEI_URL、HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL、HINDSIGHT_API_RERANKER_PROVIDER、HINDSIGHT_API_RERANKER_MAX_CANDIDATES等，覆盖远程 API、TEI 与本地模型三类嵌入/重排来源；
• 检索管线开关：HINDSIGHT_API_ENABLE_TEXT_SEARCH、HINDSIGHT_API_ENABLE_TEMPORAL_RETRIEVAL、HINDSIGHT_API_ENABLE_GRAPH_RETRIEVAL、HINDSIGHT_API_ENABLE_RERANKING—— 这四个开关可按银行独立关闭某条检索臂，让没有时间/关系结构的纯检索型银行"轻装运行"；
• 向量与全文索引：HINDSIGHT_API_VECTOR_EXTENSION（如 pgvector/vchord）、HINDSIGHT_API_TEXT_SEARCH_EXTENSION（如 pg_search/pg_trgm 等）、HINDSIGHT_API_SEMANTIC_MIN_SIMILARITY等相似度阈值；
• 观测/整合：HINDSIGHT_API_ENABLE_OBSERVATIONS、HINDSIGHT_API_ENABLE_AUTO_CONSOLIDATION、HINDSIGHT_API_CONSOLIDATION_BATCH_SIZE等，控制事实→观察的自动整合节奏；
• 运维：HINDSIGHT_API_LOG_LEVEL、HINDSIGHT_API_WORKERS、HINDSIGHT_API_OTEL_TRACES_ENABLED（OpenTelemetry 追踪）、HINDSIGHT_API_MCP_ENABLED、HINDSIGHT_API_ENABLE_BANK_CONFIG_API、HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUP、HINDSIGHT_API_SKIP_LLM_VERIFICATION等。

Docker 部署：一行命令自托管

docker run -it --name hindsight --restart unless-stopped -p 8888:8888 \ -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \ -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \ ghcr.io/vectorize-io/hindsight:latest

该命令把内嵌 PostgreSQL 的数据目录~/.hindsight-docker以卷方式挂载到容器内/home/hindsight/.pg0，实现数据持久化；--restart unless-stopped保证服务异常退出后自动拉起。

若使用外部 PostgreSQL，仓库提供了开箱即用的 Compose 编排 docker/docker-compose/external-pg/docker-compose.yaml：

cd docker/docker-compose/external-pg export HINDSIGHT_DB_PASSWORD=your-strong-password export HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxxxx docker compose up -d

该编排包含两个服务：

• db：pgvector/pgvector:pg18镜像，预装 pgvector 扩展，数据落卷pg_data；
• hindsight：ghcr.io/vectorize-io/hindsight:latest应用容器，通过HINDSIGHT_API_DATABASE_URL指向db服务（postgresql://user:pass@db:5432/dbname），并暴露8888（API）与9999（控制平面）两个端口。

Compose 文件支持的环境变量还包括：HINDSIGHT_DB_USER（默认hindsight_user）、HINDSIGHT_DB_NAME（默认hindsight_db）、HINDSIGHT_DB_VERSION（默认 18）、HINDSIGHT_VERSION（应用版本，默认 latest）。

另外，docker/standalone/Dockerfile 提供了镜像构建参数：INCLUDE_API/INCLUDE_CP（是否包含 API/控制平面）、INCLUDE_LOCAL_MODELS（是否包含本地 ML 模型，使用外部提供商时可关闭以缩小镜像）、PRELOAD_ML_MODELS（构建期预下载模型）。

MCP 集成：让 Claude Code 等客户端直接调用记忆

Hindsight API 的/mcp端点对外提供 MCP（Model Context Protocol）服务；针对不启动完整 API 服务、仅本地进程内集成的场景，README 提供了独立入口：

hindsight-local-mcp

这会运行一个stdio 传输的 MCP 服务器，可直接对接任意 MCP 兼容客户端。其实现见 mcp_local.py：它本质上仍是启动完整 hindsight-api 服务，只是预先设置HINDSIGHT_API_DATABASE_URL=pg0://hindsight-mcp（内嵌库 + 独立实例名）并采用 warning 级日志等本地默认值。

结合源码中给出的 HTTP 传输用法，与 Claude Code 集成的标准姿势是：

# 默认多银行模式 claude mcp add --transport http hindsight http://localhost:8888/mcp/ # 或固定到某个银行（单银行模式） claude mcp add --transport http hindsight http://localhost:8888/mcp/default/

hindsight-local-mcp支持的环境变量与完整服务一致（HINDSIGHT_API_LLM_API_KEY必填；HINDSIGHT_API_LLM_PROVIDER/HINDSIGHT_API_LLM_MODEL/HINDSIGHT_API_DATABASE_URL可选）。仓库中还有大量现成的 MCP 客户端集成（如 hindsight-integrations/claude-code、hindsight-integrations/codex、hindsight-integrations/cursor 等），可参考它们的配置模板。

服务端 MCP 相关配置还包括HINDSIGHT_API_MCP_ENABLED（是否启用/mcp）、HINDSIGHT_API_MCP_ENABLED_TOOLS（工具白名单）、HINDSIGHT_API_MCP_STATELESS、HINDSIGHT_API_MCP_AUTH_TOKEN（鉴权令牌）与HINDSIGHT_API_MCP_INSTRUCTIONS（注入给客户端的指令）。

Key Features 深度解读：从文档到源码

README 列出五大核心特性，这里逐一给出源码层面的印证与展开：

1. Multi-Strategy Retrieval（TEMPR）

Semantic, keyword, graph, and temporal search combined with RRF fusion

即"语义 + 关键词 + 图谱 + 时间"四条检索臂并行，再通过RRF（Reciprocal Rank Fusion）融合排序。这在 memory_engine.py 的recall路径（约第 7068 行起）中实现为"4-way parallel retrieval"，并通过 engine/search/recall_boost.py 提供按策略的加分调整（HINDSIGHT_API_RECALL_STRATEGY_BOOSTS，如graph:high,semantic:low）。engine/reflect/tools.py 中的反思工具也明确标注 "Search memories using TEMPR retrieval"。相关测试可参考 tests/test_recall_boost.py 与 tests/test_combined_scoring.py。

2. Entity Graph（实体图谱）

自动抽取实体并追踪实体间关系。从 memory_engine.py 的模块注释可以看到其设计：时间链接（时间上邻近的记忆）、语义链接（含义相近）、实体链接（共享人物/组织等实体）、扩散激活（带衰减的图搜索）与动态加权（基于新鲜度与频率的重要性）。对应的端点包括GET /v1/default/banks/{bank_id}/graph、/entities、/entities/graph、/entities/{entity_id}（见 api/http.py）。

3. Temporal Reasoning（时间推理）

原生支持基于时间的查询（如"去年春天发生了什么"）。相关实现模块包括 engine/temporal_periods.py、engine/chinese_temporal_periods.py（中文时间表达支持）、engine/temporal_language_detection.py 与 engine/query_analyzer.py（查询分析器负责解析时间约束）；时间语义检索的相似度阈值由HINDSIGHT_API_TEMPORAL_SEMANTIC_MIN_SIMILARITY控制。recall 的created_after/created_before等参数（见recall_async）也直接透出时间窗口过滤能力。

4. Disposition Traits（性格特质）

可配置的怀疑度（skepticism）、字面化（literalism）、同理心（empathy）会影响观点的形成方式——即反思（reflect）与观察整合（consolidation）阶段"怎么说话"。对应测试为 tests/test_disposition_config.py，相关配置属于银行级层级字段，可通过ConfigResolver按银行覆盖。

5. Three Memory Types（三类记忆）

• World facts（世界事实）：关于人物、地点、事件等的一般性知识；
• Experience facts（经验事实）：记忆库自身的行为——对话、采取的动作、完成的任务；
• Observations（观察）：由事实整合综合出的知识。

recall 端点文档中对这三类有明确说明（见 api/http.py）：请求体types可选填world/experience/observation，缺省时召回全部类型；观察还支持自动整合（consolidation，对应 engine/consolidation）与历史保留（HINDSIGHT_API_ENABLE_OBSERVATION_HISTORY）。此外还有第四种衍生结构——mental models（心理模型），通过refresh_mental_model等异步操作定时/触发式刷新，相关测试覆盖在 tests/test_mental_models.py 等文件中。

REST API 速览：常用端点

除 Python SDK 外，所有记忆操作都有等价 HTTP 端点（实现见 api/http.py）。以下为从源码确认的常用路径：

健康探针的使用姿势在 api/http.py 有详细注释：/health/live只回答"进程活着"，不碰数据库，适合 livenessProbe；/health（/health/ready）校验数据库连通性，适合 readinessProbe 用来摘流量，而不是重启 Pod。

小结：一条完整的学习闭环

从本文梳理的链路可以看到，Hindsight API 的完整记忆闭环是：

1. retain：Agent 把一次交互/文档写入银行，LLM 抽取事实、实体与关系，连同时间戳一起入库存为 memory unit；
2. consolidation（后台异步）：对事实去重、整合，沉淀为 observation 与 mental model；
3. recall：查询时语义/关键词/图谱/时间四路并行检索 + RRF 融合 + 重排（rerank）与时间衰减，返回最相关记忆；
4. reflect：只读 agentic 循环综合记忆给出带推理的回答。

整个过程由 PostgreSQL + pgvector 持久化，LLM 只负责抽取与推理，不承担存储职责——这正是"Agent Memory That Learns"的含义所在。如果你要动手实践，最快路径就是：pip install hindsight-api→ 设置HINDSIGHT_API_LLM_API_KEY→hindsight-api→ 用文中的 Python SDK 代码跑通 retain/recall/reflect，再按需切换到外部 PostgreSQL 或 Docker Compose 部署。

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