Hindsight API 使用指南为 AI Agent 构建会学习的时间—语义—实体记忆系统【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 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也揭示了依赖选型的关键信息可作为排障参考数据库驱动asyncpg0.30.0提供异步 PostgreSQL 访问sqlalchemy2.0.44,2.1特意钉在 2.0 线因为 2.1 起默认 DBAPI 切换为 psycopg3裸装环境会因缺少psycopg模块导致迁移失败pgvector0.4.1提供向量类型支持LLM 层openai1.66.0Responses API、anthropic0.40.0、google-genai1.72.0、litellm1.93.0macOS 上钉在 1.91.x 纯 Python wheel 线Web/服务层fastapi[standard]0.120.3、uvicorn0.38.0、fastmcp3.2.0MCP 协议支持附加依赖组extrasembedded-dbpg0-embedded0.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 Start60 秒跑起记忆服务器启动服务端# 设置 LLM 提供商 export HINDSIGHT_API_LLM_PROVIDERopenai export HINDSIGHT_API_LLM_API_KEYsk-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 APIfrom hindsight_api import MemoryEngine # 创建并初始化记忆引擎 memory MemoryEngine() await memory.initialize() # 为你的 Agent 创建一个记忆库memory bank bank await memory.create_memory_bank( namemy-assistant, backgroundA helpful coding assistant ) # 存储一条记忆 await memory.retain( memory_bank_idbank.id, contentThe user prefers Python for data science projects ) # 召回记忆 results await memory.recall( memory_bank_idbank.id, queryWhat programming language does the user prefer? ) # 带推理的反思 response await memory.reflect( memory_bank_idbank.id, queryShould I recommend Python or R for this ML project? )上面四个核心操作在源码中的对应关系如下便于深入阅读MemoryEngine.initialize()并行完成 pg0 启动、嵌入模型加载、连接池与后台任务初始化见 memory_engine.pycreate_memory_bank走ensure_bank路径幂等创建银行行与存储见 memory_engine.py同名/同 ID 的 bank 重复创建不会产生副作用retainMemoryEngine.retain()是同步便捷包装内部asyncio.run调retain_async见 memory_engine.py生产环境建议直接用retain_async以获得更高吞吐recall同样提供同步包装底层是4 路并行检索见 memory_engine.pyreflectreflect_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:mainhindsight-local-mcp本地 stdio MCP 服务器hindsight_api.mcp_local:mainhindsight-admin管理 CLIhindsight_api.admin.cli:main支持备份恢复、银行转账等运维操作。配置环境变量即配置面所有配置都通过HINDSIGHT_API_前缀的环境变量注入集中定义在 config.py并由load_dotenv_for_entrypoint()在入口处加载.env文件.env优先于进程环境见 config.py。README 给出的核心变量如下变量说明默认值HINDSIGHT_API_DATABASE_URLPostgreSQL 连接串pg0内嵌HINDSIGHT_API_LLM_PROVIDERLLM 提供商支持openai、anthropic、gemini、groq、ollama、lmstudio、github-copilot等openaiHINDSIGHT_API_LLM_API_KEYLLM 提供商的 API Key-HINDSIGHT_API_LLM_MODEL模型名gpt-4o-miniHINDSIGHT_API_HOST服务绑定地址0.0.0.0HINDSIGHT_API_PORT服务端口8888上述默认值在源码中均有对应常量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_URLpostgresql://user:passlocalhost:5432/hindsight export HINDSIGHT_API_LLM_PROVIDERgroq export HINDSIGHT_API_LLM_API_KEYgsk_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_ENABLEDOpenTelemetry 追踪、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.yamlcd docker/docker-compose/external-pg export HINDSIGHT_DB_PASSWORDyour-strong-password export HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx docker compose up -d该编排包含两个服务dbpgvector/pgvector:pg18镜像预装 pgvector 扩展数据落卷pg_datahindsightghcr.io/vectorize-io/hindsight:latest应用容器通过HINDSIGHT_API_DATABASE_URL指向db服务postgresql://user:passdb:5432/dbname并暴露8888API与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端点对外提供 MCPModel Context Protocol服务针对不启动完整 API 服务、仅本地进程内集成的场景README 提供了独立入口hindsight-local-mcp这会运行一个stdio 传输的 MCP 服务器可直接对接任意 MCP 兼容客户端。其实现见 mcp_local.py它本质上仍是启动完整 hindsight-api 服务只是预先设置HINDSIGHT_API_DATABASE_URLpg0://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 RetrievalTEMPRSemantic, keyword, graph, and temporal search combined with RRF fusion即语义 关键词 图谱 时间四条检索臂并行再通过RRFReciprocal 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。以下为从源码确认的常用路径方法路径说明GET/health、/health/ready、/health/live就绪/存活探针live 不访问数据库ready 校验数据库可达性GET/version版本号与功能开关observations/mcp/worker/bank_config_api 等GET/metricsPrometheus 指标GET/v1/default/banks列出记忆库支持q搜索、limit/offset分页按最近写入排序GET/v1/default/banks/{bank_id}/stats银行统计可refreshtrue强制重算POST/v1/default/banks/{bank_id}/memories/recall召回记忆types可限定事实类型GET/v1/default/banks/{bank_id}/memories/list列出记忆单元GET/v1/default/banks/{bank_id}/graph获取记忆图谱POST/v1/default/banks/{bank_id}/reflect反思回答只读GET/v1/default/banks/{bank_id}/entities、/entities/graph、/entities/{entity_id}实体与关系查询POST/v1/default/banks/{bank_id}/memories/dry-run-extract事实抽取预演不落库可 A/B 对比配置POST/v1/default/banks/{bank_id}/prompts/preview预览 retain/consolidation/reflect 实际发送的 prompt不调用 LLM健康探针的使用姿势在 api/http.py 有详细注释/health/live只回答进程活着不碰数据库适合 livenessProbe/health/health/ready校验数据库连通性适合 readinessProbe 用来摘流量而不是重启 Pod。小结一条完整的学习闭环从本文梳理的链路可以看到Hindsight API 的完整记忆闭环是retainAgent 把一次交互/文档写入银行LLM 抽取事实、实体与关系连同时间戳一起入库存为 memory unitconsolidation后台异步对事实去重、整合沉淀为 observation 与 mental modelrecall查询时语义/关键词/图谱/时间四路并行检索 RRF 融合 重排rerank与时间衰减返回最相关记忆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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hindsight API 使用指南：为 AI Agent 构建会学习的时间—语义—实体记忆系统
Hindsight API 使用指南为 AI Agent 构建会学习的时间—语义—实体记忆系统【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 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也揭示了依赖选型的关键信息可作为排障参考数据库驱动asyncpg0.30.0提供异步 PostgreSQL 访问sqlalchemy2.0.44,2.1特意钉在 2.0 线因为 2.1 起默认 DBAPI 切换为 psycopg3裸装环境会因缺少psycopg模块导致迁移失败pgvector0.4.1提供向量类型支持LLM 层openai1.66.0Responses API、anthropic0.40.0、google-genai1.72.0、litellm1.93.0macOS 上钉在 1.91.x 纯 Python wheel 线Web/服务层fastapi[standard]0.120.3、uvicorn0.38.0、fastmcp3.2.0MCP 协议支持附加依赖组extrasembedded-dbpg0-embedded0.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 Start60 秒跑起记忆服务器启动服务端# 设置 LLM 提供商 export HINDSIGHT_API_LLM_PROVIDERopenai export HINDSIGHT_API_LLM_API_KEYsk-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 APIfrom hindsight_api import MemoryEngine # 创建并初始化记忆引擎 memory MemoryEngine() await memory.initialize() # 为你的 Agent 创建一个记忆库memory bank bank await memory.create_memory_bank( namemy-assistant, backgroundA helpful coding assistant ) # 存储一条记忆 await memory.retain( memory_bank_idbank.id, contentThe user prefers Python for data science projects ) # 召回记忆 results await memory.recall( memory_bank_idbank.id, queryWhat programming language does the user prefer? ) # 带推理的反思 response await memory.reflect( memory_bank_idbank.id, queryShould I recommend Python or R for this ML project? )上面四个核心操作在源码中的对应关系如下便于深入阅读MemoryEngine.initialize()并行完成 pg0 启动、嵌入模型加载、连接池与后台任务初始化见 memory_engine.pycreate_memory_bank走ensure_bank路径幂等创建银行行与存储见 memory_engine.py同名/同 ID 的 bank 重复创建不会产生副作用retainMemoryEngine.retain()是同步便捷包装内部asyncio.run调retain_async见 memory_engine.py生产环境建议直接用retain_async以获得更高吞吐recall同样提供同步包装底层是4 路并行检索见 memory_engine.pyreflectreflect_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:mainhindsight-local-mcp本地 stdio MCP 服务器hindsight_api.mcp_local:mainhindsight-admin管理 CLIhindsight_api.admin.cli:main支持备份恢复、银行转账等运维操作。配置环境变量即配置面所有配置都通过HINDSIGHT_API_前缀的环境变量注入集中定义在 config.py并由load_dotenv_for_entrypoint()在入口处加载.env文件.env优先于进程环境见 config.py。README 给出的核心变量如下变量说明默认值HINDSIGHT_API_DATABASE_URLPostgreSQL 连接串pg0内嵌HINDSIGHT_API_LLM_PROVIDERLLM 提供商支持openai、anthropic、gemini、groq、ollama、lmstudio、github-copilot等openaiHINDSIGHT_API_LLM_API_KEYLLM 提供商的 API Key-HINDSIGHT_API_LLM_MODEL模型名gpt-4o-miniHINDSIGHT_API_HOST服务绑定地址0.0.0.0HINDSIGHT_API_PORT服务端口8888上述默认值在源码中均有对应常量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_URLpostgresql://user:passlocalhost:5432/hindsight export HINDSIGHT_API_LLM_PROVIDERgroq export HINDSIGHT_API_LLM_API_KEYgsk_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_ENABLEDOpenTelemetry 追踪、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.yamlcd docker/docker-compose/external-pg export HINDSIGHT_DB_PASSWORDyour-strong-password export HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx docker compose up -d该编排包含两个服务dbpgvector/pgvector:pg18镜像预装 pgvector 扩展数据落卷pg_datahindsightghcr.io/vectorize-io/hindsight:latest应用容器通过HINDSIGHT_API_DATABASE_URL指向db服务postgresql://user:passdb:5432/dbname并暴露8888API与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端点对外提供 MCPModel Context Protocol服务针对不启动完整 API 服务、仅本地进程内集成的场景README 提供了独立入口hindsight-local-mcp这会运行一个stdio 传输的 MCP 服务器可直接对接任意 MCP 兼容客户端。其实现见 mcp_local.py它本质上仍是启动完整 hindsight-api 服务只是预先设置HINDSIGHT_API_DATABASE_URLpg0://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 RetrievalTEMPRSemantic, keyword, graph, and temporal search combined with RRF fusion即语义 关键词 图谱 时间四条检索臂并行再通过RRFReciprocal 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。以下为从源码确认的常用路径方法路径说明GET/health、/health/ready、/health/live就绪/存活探针live 不访问数据库ready 校验数据库可达性GET/version版本号与功能开关observations/mcp/worker/bank_config_api 等GET/metricsPrometheus 指标GET/v1/default/banks列出记忆库支持q搜索、limit/offset分页按最近写入排序GET/v1/default/banks/{bank_id}/stats银行统计可refreshtrue强制重算POST/v1/default/banks/{bank_id}/memories/recall召回记忆types可限定事实类型GET/v1/default/banks/{bank_id}/memories/list列出记忆单元GET/v1/default/banks/{bank_id}/graph获取记忆图谱POST/v1/default/banks/{bank_id}/reflect反思回答只读GET/v1/default/banks/{bank_id}/entities、/entities/graph、/entities/{entity_id}实体与关系查询POST/v1/default/banks/{bank_id}/memories/dry-run-extract事实抽取预演不落库可 A/B 对比配置POST/v1/default/banks/{bank_id}/prompts/preview预览 retain/consolidation/reflect 实际发送的 prompt不调用 LLM健康探针的使用姿势在 api/http.py 有详细注释/health/live只回答进程活着不碰数据库适合 livenessProbe/health/health/ready校验数据库连通性适合 readinessProbe 用来摘流量而不是重启 Pod。小结一条完整的学习闭环从本文梳理的链路可以看到Hindsight API 的完整记忆闭环是retainAgent 把一次交互/文档写入银行LLM 抽取事实、实体与关系连同时间戳一起入库存为 memory unitconsolidation后台异步对事实去重、整合沉淀为 observation 与 mental modelrecall查询时语义/关键词/图谱/时间四路并行检索 RRF 融合 重排rerank与时间衰减返回最相关记忆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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考