Hindsight 核心演进全览：从 v0.1 到 v0.9 的 API、CLI 与控制平面 Changelog 深度解读

Hindsight 核心演进全览从 v0.1 到 v0.9 的 API、CLI 与控制平面 Changelog 深度解读【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文以 Hindsight 官方文档站 Changelog 页面 为骨架系统梳理 Hindsight 核心组件API、CLI、控制平面从 v0.1.2 到 v0.9.2 的演进脉络覆盖召回Recall、心智模型Mental Models、记忆摄取Retain、Embedding、LLM 提供方生态、知识库页面Knowledge Pages与多租户部署等关键主题。读完本文你将理解 Hindsight 各主要能力的引入版本、设计意图与实现佐证对应仓库源码路径可作为评估升级影响、排查兼容性问题与规划二次开发的技术参考。需要说明的是按官方约定本 Changelog 只收录用户可见User-facing的变更内部维护与基础设施更新被省略每个集成integration拥有独立发布节奏与独立 Changelog不在本文范围内。一、版本脉络总览核心能力的引入时间线从 Changelog 可以清晰看到 Hindsight 核心的演进节奏v0.4.0 之前0.1.x0.3.x基础能力搭建期。加入 extensions 扩展系统v0.1.12、LiteLLM 集成与 MPFP 图检索器v0.1.5、Gemini 3 Pro 与 GPT-5.2 模型支持、本地 MCP Server 选项v0.1.6并完成嵌入式 Postgres 层向 pg0-embedded 的切换。v0.4.x多租户与可观测性成熟期。引入分层配置作用域system/tenant/bankv0.4.11、OpenTelemetry 追踪、Webhooksconsolidation.completed与retain.completedv0.4.16、审计日志v0.4.21、批量 LLMOpenAI/Groq Batch APIv0.4.12、文档与记忆时间线视图。v0.5.x摄取管线重构期。3 阶段 retain 管线pre-resolve / insert / post-linkv0.5.0、内置 llama.cpp LLM Provider、Bank Template 导入导出、保留更新模式update_modeappend以及一度引入又迅速回退的 JSON Schema 简化详见下文升级警告。v0.6.xv0.7.x检索与观测质量提升期。只读数据库后端recall 走副本、AlloyDB ScaNN 索引、litellmrouter多端点自动回退、ParadeDB pg_search 与 PGroonga 多语言检索、按银行优先级调度 consolidation、多租户 schema 迁移并行化。v0.8.x可扩展性与成本优化期。按银行 HNSW 索引、批量 LLMAnthropic/Gemini/Fireworks、多 LLM 故障转移与轮询选择、持久化进度快照、语义去重consolidation 阶段默认开启Oracle 除外、全银行导出/导入迁移、控制平面 i18n 与 8 种语言支持。v0.9.x知识库与订阅 Provider 期。引入 Knowledge Pages 与hindsight fsCLI、Coding Agents、显式时间窗口召回、基于 Copilot/SuperGrok 订阅的 LLM Provider并在 v0.9.2 中将知识库以原生 MCP 工具暴露。二、召回Recall能力的持续增强Recall 是 Hindsight 面向 Agent 检索记忆的核心接口Changelog 显示其能力在多个版本中被不断打磨2.1 显式时间窗口v0.9.2v0.9.2 起调用方可以为 Recall 提供显式时间窗口explicit temporal window而不必依赖从自然语言查询中解析出的时间表达式。仓库中对应实现位于 engine 目录 的召回相关模块这一改动让程序化调用SDK、CLI、MCP 工具可以精确圈定时间范围与查询分析器query analyzer的时间解析解耦。2.2 分段评分与两级阈值v0.8.4Recall 返回结构化的分段评分per-stage scores并支持两级min_scores过滤实现对结果的更细粒度控制。对应的min_scores参数在 Python/TypeScript SDK 封装中均有透传见 v0.8.4 Bug Fixes 中 Python and TypeScript SDK wrappers now correctly pass recall min_scores filtering options。2.3 排序与预算的可配置化v0.8.4v0.9.0可配置的时效衰减recency decay支持linear、exponential、none三种模式用于调节排序对近期记忆的偏好。偏好观测observations可配置让 Recall 优先返回观测而非已被取代的原始事实v0.8.4、v0.9.0 经 OpenClaw 集成。逐策略检索增强per-strategy retrieval boostsv0.8.0通过环境变量配置各检索策略的权重。语义相似度阈值HINDSIGHT_API_SEMANTIC_MIN_SIMILARITY可调节召回灵敏度v0.8.0。Reranker 候选预算上限与故障转移链v0.9.0可为每个预算配置 reranker 考虑的最大候选数并支持在多个 reranker 配置间按链回退。按银行开关v0.9.0可按银行单独启用/禁用时间搜索temporal search、图扩展graph expansion与重排reranking。2.4 查询稳健性修复多个版本修复了召回相关的边界问题包括极端相对日期偏移导致崩溃v0.9.1、长 BM25 查询仅保留最具选择性的词项v0.9.2、查询分析器不再把孤立四位数字误判为年份v0.9.2、空查询返回明确 400 错误v0.4.20、无效事实类型返回 422v0.9.0、created_after/created_before同时约束图扩展v0.9.0、内部非 HTTP召回路径也执行查询 token 上限v0.9.0等。这些改动共同保证了召回结果在超长查询、极端输入与并发下的稳定性。三、心智模型Mental Models与 Reflect心智模型是 Hindsight Agent Memory That Learns 的核心体现Changelog 中相关条目最多。3.1 自动刷新与最小间隔v0.9.2v0.9.2 起自动心智模型刷新强制执行最小刷新间隔防止过于频繁的刷新循环。仓库中对应配置项为HINDSIGHT_API_MENTAL_MODEL_MIN_REFRESH_INTERVAL_SECONDS见 config.py 中ENV_MENTAL_MODEL_MIN_REFRESH_INTERVAL_SECONDS触发级别trigger.min_refresh_interval_seconds可覆盖全局默认值 0max()合并逻辑位于环境解析处保证任意一侧的取值都不会低于下限。3.2 水印语义拆分v0.9.2重要行为变更v0.9.2 中last_refreshed_at恢复为记录刷新完成时刻而源数据水印改由新增的last_memory_seen_at承载。Changelog 明确提示Clients testing staleness against last_memory_write_at should compare last_memory_seen_at——即以last_memory_write_at判断陈旧度的客户端应改用last_memory_seen_at比较。仓库中该字段的建模与迁移可参见 alembic 迁移 与 mental_model_refresh.py 中delta refresh 只看到写入/编辑晚于last_memory_seen_at的记忆的水印逻辑。3.3 增量刷新Delta Refresh自 v0.5.4 起心智模型支持Delta 刷新召回范围限定为上次刷新之后创建的记忆使更新更快更准v0.8.6 又修复了 no-op 刷新仍推进水印、避免重复处理的问题。刷新期间的变化以verbatim Markdown 块存储v0.9.2保证模型变更追踪更忠实、可读。3.4 排程、调试与运维工具cron 排程刷新v0.8.4心智模型可按 cron 自动刷新。dry-run 模式与 trace 保留v0.9.0提供刷新故障排查工具。唯一排队保证v0.9.2同一心智模型同一时刻只排队一次刷新防止积压与重复。失效引用清理v0.9.2刷新时移除对已不存在事实的引用避免陈旧引用。失败即失败v0.9.2Reflect 无答案产出时直接失败防止占位记忆被写入内容策略拒绝content-policy refusal在 retain 中被视为永久失败而不再无限重试。3.5 触发Triggers与指令Directivesv0.4.22 起心智模型触发器支持完整配置 schema含 tag 匹配与 tag 组过滤v0.9.2 修复了触发器在 create/update 时补丁patch而非替换保留已有触发器设置。Reflect 指令方面v0.8.6 增加跨所有 scope 应用指令的选项v0.9.1 修复了刷新触发不会意外重置知识页面 scope 的问题。四、Embedding 与重排Reranking4.1 非对称前缀v0.9.2文本嵌入text-inProvider 现在可配置非对称的 query/passage 前缀以提升检索质量同时修复了 Voyage embeddings 保留非对称行为的问题。仓库中该能力在 config.py 中以embeddings_query_prefix/embeddings_passage_prefix建模并在 embeddings.py 中通过_encode_prefixed在编码前拼接前缀E5 风格的query: /passage: 前缀即为典型用例。4.2 输入长度与维度控制通用逐输入 token 上限v0.9.0跨 Provider 限制单条嵌入输入长度超限输入在嵌入前截断v0.8.5。OpenAI 兼容嵌入 batch size 可配置v0.5.4输出维度可配置v0.4.20 LiteLLM SDK、v0.5.5 Cohere。嵌入向量维度写入前校验v0.8.0防止 pgvector 存储/查询错误v0.4.14 对超过 pgvector HNSW 维度上限的情况提前报错。4.3 本地嵌入与重排本地 ONNX 嵌入 Providerv0.8.0无托管嵌入 API 也可生成向量。Jina MLX 重排器v0.4.18针对 Apple Silicon、Intel XPU 加速检测v0.8.3 嵌入、v0.8.4 重排。Apple Silicon 上本地嵌入/重排默认使用 CPU以避免 MPS 内存泄漏v0.8.6Torch 默认 dtype 被全局修改的并发问题在 v0.8.2 修复。FlashRank 通过分页批处理代替无界单次打分v0.9.1TEI 嵌入/重排在 HTTP 429 背压下自动重试v0.8.6。4.4 重排链与故障转移v0.9.0 引入 reranker failover chain多配置间回退与按预算的候选数上限v0.7.1 增加按 Provider 的 reranker HTTP 超时环境变量。相关测试可见 test_reranker_failover_chain.py 等用例。五、Knowledge Pages知识库页面v0.9.0 引入v0.9.0 引入Knowledge Pages——客户端托管的持久知识内容配套控制平面 UI 与hindsight fsCLI 管理。这是 Hindsight 从隐式记忆走向显式知识的关键一步scope 保真v0.9.2知识页面可靠地保持预期 scope触发器更新不再意外重置它。按 scope 计算陈旧度v0.9.2页面陈旧度改为按 scope 计算而非依据银行水印准确性更高。刷新触发器可视化v0.9.2知识树暴露每页的刷新触发器便于检查刷新行为。原生 MCP 工具v0.9.2Agent 可通过 MCP 浏览、搜索与维护知识页面无需回退 HTTPAgent SDK 的agent_knowledge_get_page也支持detailcontent获取完整页面内容v0.6.2。并发写保护v0.9.2知识树写入被序列化防止并发写冲突与损坏知识库搜索在无原生文本搜索后端的部署上不再报错v0.9.1并支持在配置 PGroonga 时使用 PGroonga 检索v0.9.1。六、LLM 提供方生态的扩展Changelog 中 Provider 相关条目贯穿始终可按第一方 Provider / 路由与网关 / 批量 API / 缓存四个维度归纳6.1 新增 Provider第一方 ProviderOpenAI Codex 与 Claude Codev0.4.8、Vertex AIv0.4.3、DeepSeekv0.5.5、MiniMaxv0.4.18、z.ai 智谱v0.6.1、OpenAI Responses API 新 Provideropenai-responsesv0.9.0、Nous Portal 原生 OAuth Providerv0.8.2、OpenCode Go Providerv0.7.0、xAI OAuthSuperGrok 订阅v0.9.1、GitHub Copilot 订阅 Providerv0.9.2。OpenAI 兼容/网关Requestyv0.8.4、Atlas Cloudv0.8.4、Ollama Cloudv0.7.0、LiteLLM SDK 嵌入/重排v0.4.11、litellmrouter多端点自动回退链v0.6.1。批量推理Anthropic Message Batchesv0.8.5、Gemini Batch APIv0.8.2、Fireworks AIv0.7.2、OpenAI/Groq Batchv0.4.12。嵌入/重排ZeroEntropyv0.7.0、SiliconFlow 重排v0.5.1、Google 嵌入与重排v0.5.0、Cohere 嵌入与重排v0.4.0、OpenRouterv0.5.0。6.2 成本与缓存优化Anthropic prompt cachingv0.8.5含批量 system prompt 中携带缓存标记服务端 prompt 前缀缓存默认开启v0.8.0reduce retain/consolidation/reflect 的重复 LLM 工作。Gemini 工具循环逐步上下文缓存v0.8.5与隐式缓存比例配置对应测试 test_gemini_implicit_cache_ratio.py。Azure OpenAI 禁用自动缓存亲和性v0.9.2以避免路由问题负载均衡 OpenAI 兼容后端的服务端缓存恢复v0.9.1。6.3 请求级控制全局HINDSIGHT_API_LLM_EXTRA_BODYv0.8.0与按操作覆盖v0.9.0的额外请求字段HINDSIGHT_API_LLM_STRICT_SCHEMA在所有支持 JSON Schema 的 Provider 上生效v0.8.0。按操作的温度控制v0.8.4与reasoning_effort覆盖v0.8.6HINDSIGHT_API_LLM_REASONING_EFFORT环境变量v0.7.1。工具调用兼容性OpenAI 风格规范 tool-result 消息v0.8.5、对错误处理tool_choicerequired的服务器的安全回退v0.8.0、LiteLLM 强制工具模式产生结构化输出v0.9.1。七、Retain 摄取管线与记忆工程7.1 3 阶段管线与流式子批次v0.5.0 将 retain 重构为pre-resolve / insert / post-link 三阶段把慢速读操作移出写事务大幅提升并发吞吐。v0.9.2 进一步以流式子批次拆分处理大批次降低内存占用并提高大文件处理效率超大单条在批量 retain 中被自动拆分v0.7.0。7.2 记忆预算与容量保护v0.9.2 起 retain 强制执行记忆预算memory budget而非单文档上限防止大输入导致内存失控同时修复了 re-retain 在内容减少时正确删除被移除的 chunk、空元数据值在 retain/recall 中被丢弃、超大追加文档再次被识别为 append避免全量重提取等问题。7.3 实体解析控制v0.9.2 为 retain 与 update_memory 增加可选实体解析开关dedicated flag实现更可控的实体处理v0.9.2 修复了实体解析仅凭历史匹配名称就合并实体的问题减少错误合并。v0.8.5 retain 在链接前重新断言已解析实体并将提取实体规范化为纯字符串v0.9.0 修复了批内实体去重。v0.9.2 retain 写入将实体 postings 与 witness 覆盖在同一写组内一致应用。7.4 失败语义与审计事实提取遇 schema 漂移时明确重试并失败v0.9.2而非静默产出坏数据错误配置的 retain 设置响亮失败而非静默回退默认值v0.9.2。内容策略拒绝视为永久失败v0.9.2畸形 memory-defense 策略下 fail-closedv0.9.2token 边界采用 ASCII 规则以正确处理中文相邻的秘密文本脱敏v0.9.2。记忆updated_at在所有变更记忆的写入时刷新v0.9.2保留清理retention sweep分批执行以免阻塞前台查询v0.9.2。八、数据库、存储与多租户部署8.1 后端与索引演进Oracle Database 后端v0.6.0与持续兼容修复v0.8.6 全文本/向量/审计 SQL、v0.8.0 后端区别处理只读副本后端v0.6.1让 recall 流量走副本、写入留在主库。向量索引从每银行固定创建 3 个索引改为随银行规模按比例创建v0.9.2降低 DB 膨胀v0.4.18 切到按银行 HNSW 索引支持 pgvectorscale DiskANNv0.4.12、Azure pg_diskannv0.4.12、AlloyDB ScaNNv0.6.1、VectorChord BM25 门控v0.8.0。文本/多语言检索ParadeDB pg_searchv0.7.0含 tokenizer 配置、可配置 BM25 语言/分词与 PGroonga 后端v0.7.0、TimescaleDB pg_textsearch 与 vchord/pgvectorv0.4.11。连接串pg0://URL 支持可选 user/passwordv0.8.5外部 PostgreSQL 接受 asyncpg 风格 URLv0.5.5启动时尊重 URL 内嵌凭据v0.8.5。8.2 Worker 与运维Worker 轮询每周期使用池化连接并合并会话设置v0.9.2后台 worker 运行纳入调用方 tracev0.9.2。多租户维护清理maintenance sweep随租户数量伸缩v0.9.2schema 并发变更时维护跳过而非死锁v0.9.2。命名从HINDSIGHT_API_WORKER_TYPE_MAX_SLOTS改为_RESERVED_SLOTS语义为保留最小额度而非并发上限v0.8.6旧名继续可用但记录弃用警告。新增decommission-workers、worker-status管理 CLIv0.5.4worker 启动前探测pg_proc兼容无schemas_with_pending_work()的旧库v0.6.1。8.3 备份、迁移与导入导出全银行导出/导入v0.8.0跨实例迁移与文档级导出/导入不重跑 LLM复用已有抽取结果导入时保留 Knowledge Pages 树并重建搜索状态v0.9.1。Bank Template 全字段可导出导入v0.9.1template 校验与可配置字段对齐v0.5.2。迁移相关多租户 schema 迁移并行化v0.8.3、v0.4.22→v0.5.x 迁移路径修复v0.5.3、分叉 Alembic head 合并v0.5.4。九、CLI、客户端与控制平面9.1 CLIRust 实现CLI 源码位于 hindsight-cli/srcRust含api.rs、config.rs、output.rs、ui.rs与按命令组织的 commands 目录。Changelog 中的关键演进非交互友好v0.9.2非 TTY 环境下禁用 ANSI 颜色与 spinnerRust 侧通过OutputFormat::Pretty等枚举控制输出样式见 commands/bank.rs。脚本友好v0.9.2配置无效 API URL 时以非零状态退出HTTP 400 错误详情保留v0.8.6响应体纳入错误输出v0.5.1。运维命令--import-conversationsv0.9.0、memory retain-files --strategyv0.6.1、--wait/--date过滤v0.4.3、命名连接 profile-p/--profilev0.5.3、CLI 覆盖全部 OpenAPI 端点与请求体参数v0.5.1。9.2 官方客户端仓库中的客户端包括 Python、TypeScript、Go 与 RustGo 客户端 v0.4.12 引入。Changelog 中与客户端相关的重要变更Agent SDKagent_knowledge_recall的max_results重命名为max_tokens且默认从 10 提升到 1024v0.6.2TS 客户端支持 AbortSignalv0.6.0、自定义请求头v0.8.6、版本经 tsup define 注入v0.6.1Python 客户端暴露retain_asyncv0.6.0与 mental-model 查询控制v0.8.6。9.3 控制平面i18nv0.7.0 支持 8 种语言v0.7.1 增加中文变体。可视化Constellation 实体关系画布v0.5.0、共现图视图v0.5.2、记忆时间线、操作类型过滤与自动刷新v0.4.17。运维按模型展示陈旧度v0.9.2、文档标签过滤与 facet chip UIv0.8.6、上传大小限制可配置v0.8.4、Access Key 登录v0.6.1。十、升级注意事项与破坏性变更Changelog 明确标注了需要读者特别关注的版本10.1 v0.5.5 的回归警告重要0.5.5 包含一个可能导致 retain 期间提取 0 个事实的回归。JSON Schema 简化改动commit5b1c3486在 v0.5.6 中被回退。请立即升级到 v0.5.6。该改动将$ref/$defs内联为一个大 blob导致部分 LLM尤其是软强制模式下的 GPT-4o-mini回显 schema 结构而非产出有效响应。v0.5.6 的修复说明中还提到如果你正在使用 0.5.5请立即升级。10.2 v0.9.2 的水印语义变更如前所述last_refreshed_at与last_memory_seen_at语义拆分依赖last_memory_write_at判断陈旧度的客户端需改用last_memory_seen_at。10.3 v0.5.0 的破坏性变更移除 BFS 与 MPFP 图检索策略LinkExpansionRetriever成为唯一图检索算法。移除hindsight-hermes集成包之后 v0.9.0 又以 Coding Agents 形式提供 harness 可插拔记忆。10.4 其他明确提示v0.7.1修复了超过单次 LLM 调用的大文档 retain 可能丢失部分提取记忆的问题——升级后请对受影响文档重新 retain。v0.5.5GET /banks/{bank_id}/profile不再有创建银行的副作用。v0.8.6worker 槽位环境变量改名旧名保留但记录弃用警告。十一、源码验证索引以下仓库路径可作为深入研读本文所涉功能的入口主题仓库路径Changelog 原文hindsight-docs/src/pages/changelog/index.md全局配置与环境变量前缀、间隔、strict schema、extra bodyconfig.py心智模型水印与 delta 刷新engine/mental_model_refresh.py非对称嵌入前缀实现engine/embeddings.py检索与重排相关测试tests/test_recall_*.pyCLIRusthindsight-cli/src官方客户端hindsight-clients集成各框架独立发布hindsight-integrations结语纵观 v0.1.2 到 v0.9.2Hindsight 核心的演进遵循一条清晰主线先打通摄入-存储-召回的基础管线再逐步引入心智模型、知识库页面等学会学习的高级机制同时在多租户、多后端、多 Provider 与可观测性上持续加固。本文依据官方 Changelog 与仓库源码将分散在十余个版本中的数百条变更组织为可检索的主题式解读在升级或二次开发时建议以本文的时间线与语义变更为索引回到对应版本的 Changelog 原文 核对细节。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考