Hermes 编程助手接入 Hindsight：为你的代码库构建跨会话持久记忆

Hermes 编程助手接入 Hindsight为你的代码库构建跨会话持久记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight每次 AI 编码会话都从零开始Hermes 编程助手通过原生集成 Hindsight将每次编码会话沉淀为结构化的代码库事实让第 20 次会话的助手比第 1 次更懂你的项目。本文讲解 Hermes 记忆的底层机制、两分钟搭建步骤、三个高杠杆工作流以及团队共享记忆库与 Mental Model 高级玩法。引言编码助手缺的不是能力而是记忆你打开一个新的聊天窗口粘贴上下文、技术栈、团队约定、上周做的架构决策、三月花了两天排查的那个 bug——然后下一个会话再重复一遍。问题不在于 AI 编码工具不会写代码而在于它对你的代码库没有记忆。Hermes Agent 与 Hindsight 的组合是例外。每次会话都会沉淀它对项目的认知模块边界、命名约定、已知脆弱区域、反复出现的认证问题根因。到第 20 个会话时你不再解释它已经开始知道。本篇文章将说明 Hermes 究竟从编码会话中提取什么、如何两分钟完成搭建以及代码库持久记忆杠杆最高的三个工作流。Hermes 记住代码库的什么内容Hermes 不存储对话原文。Hindsight 提取并保留的是事实facts——从对话中抽出的原子化、可检索的知识片段。一次典型编码会话结束后类似下面的事实会自动进入记忆项目使用 ESM 模块而非 CommonJSimport 中始终使用 .js 扩展名认证中间件在 refresh token 过期时静默失败2026-03-14 起为已知问题二月性能测试后已用原生 asyncpg 取代 SQLAlchemy团队约定所有 async handler 用 handle_errors() 装饰器包裹这些都不需要你显式告诉 Hermes 去记住。Hindsight 的**写入管线write pipeline**从会话的自然流程中提取它们——从你问的问题、描述的 bug、解释的决策里自动完成。不会成为记忆的内容原始文件内容、逐行代码、冗长的终端输出。提取步骤本身就是一个过滤器。对话寒暄、重复的上下文铺垫、程序性噪音都不会存活下来。剩下的是 Hermes 带进未来每次会话的、不断增长的代码库事实索引。记忆生命周期贯穿每一轮对话的两端每轮对话之前Hindsight 预取prefetch与当前话题最相关的记忆注入系统提示词。Hermes 在看到你的消息之前就已经看到了这些上下文。每轮响应之后你的对话被异步保留retain。Hindsight 在后台提取事实。这一轮讨论的内容从下一轮开始变得可检索。从源码结构看这一写入—读取闭环对应 memory_engine.py 中retain/retain_async第 5179 行起与recall/recall_async第 7184 行起、reflect_async第 14104 行起等核心方法所有记忆操作统一抽象在 interface.py 的MemoryEngineInterface中。两分钟搭建原生 Hindsight 集成Hermes v0.14.0v2026.5.16起内置了 Hindsight 原生集成。搭建只需一条向导命令hermes memory setup # 选择 hindsight确认记忆已激活hermes memory status配置存放在$HERMES_HOME/hindsight/config.json默认值已适配大多数工作流Key默认值说明modecloudcloud云端或local本地bank_idhermes记忆库标识按项目修改budgetmid召回彻底程度low/mid/highmemory_modehybrid自动召回 显式工具prefetch_methodrecallrecall快速或reflectLLM 综合memory_mode记忆以何种方式浮现memory_mode控制记忆在 Hermes 中呈现的方式hybrid默认每轮对话前自动注入记忆同时模型可用hindsight_recall、hindsight_retain、hindsight_reflect工具context仅自动召回无显式工具无需模型操心tools模型必须显式调用hindsight_recall不自动注入任何内容对编码工作而言hybrid是正确的默认值——每轮自动召回同时还能让 Hermes 显式调出它对某个组件的认知。部署形态cloud 与 localcloud跨机器工作或与团队共享记忆时使用。记忆保存在云端记忆库多台设备、多位成员读写同一份数据。local希望一切本地化、无外部依赖时使用。本地模式在后台运行一个内嵌 PostgreSQL 守护进程对应仓库中的 hindsight-embed 包与 mcp_local.py 包装器。首次启动约需一分钟初始化数据库后续启动很快启动日志位于~/.hermes/logs/hindsight-embed.log。从旧版hindsight-hermes插件迁移先卸载插件uv pip uninstall hindsight-hermes --python $HOME/.hermes/hermes-agent/venv/bin/python再运行搭建向导。原生 provider 取代了插件的全部功能。工作流一在既有工作上开启新会话没有记忆时续接既有项目意味着在实际工作前先做一堆上下文铺垫粘贴 README、解释技术栈、重新说明上次做到哪里、提醒 Hermes 它本该知道的约定。复杂项目上这种开销每次会话吃掉 10–15 分钟。有记忆时Hermes 会在会话开始时就把此前会话沉淀的事实注入上下文。它知道技术栈、约定、你上周在调试什么。会话的第一条消息就是实际工作。注入多少由budget设置控制mid默认预取 10–15 条最相关记忆足以覆盖项目核心事实又不会淹没上下文窗口。对大多数编码工作流是最佳平衡。low快速简单检索适用于轻量查询。high检索更深上下文与 token 更多。当你要跨多个模块跳回一个复杂调查时值得付出额外成本。工作流二调试反复出现的问题代码库记忆最高杠杆的价值在于跨会话的模式识别。有些 bug 不是一次性事故而是深层架构问题的症状会在几个月内以不同形式反复浮现。没有记忆时你独立调试每一次实例可能在三次排障中追踪同一个根因而浑然不觉。有记忆时Hermes 会召回此前的实例你描述一个新故障模式它浮现相关上下文——两个月前定位的根因、撑到下次重构的临时方案、反复出现在这些故障中的那个组件。这类高回报事实的典型限流器对带 X-Internal: true 头的请求绕过认证检查两起提权未遂事故的根源Redis 连接重置时异步任务队列静默丢任务需要显式 ACK 处理不能 fire-and-forget每次新增 schema 后 GraphQL resolver 的 N1 模式都会重现代码评审时需强制 DataLoader 落地这些不是你会在调试会话开头想起来粘贴的事实。它们是区分盲调与带着完整上下文调试的机构知识。对本工作流值得启用prefetch_method: reflect。与通过语义搜索检索单条事实不同reflect让 LLM 在注入前先把所有相关记忆综合成一份连贯摘要。速度更慢但对帮我理解这类 bug的查询综合后的上下文比单条事实列表有用得多。从实现看reflect 是一个完整的agentic 推理循环代理使用多种检索工具自主搜索记忆库应用记忆库的 disposition traits 塑造推理风格最终产出基于证据的回答——而不是像 recall 那样返回原始事实列表见 reflect.mdx。工作流三接手别人的代码如果你加入一个同事已经用 Hermes Hindsight 在共享记忆库上工作过的项目记忆库里已经有了他们会话沉淀的上下文。直接向 Hermes 提问它会浮现此前会话积累的事实你对 payments 模块了解多少auth 服务里出现过哪些坑或已知问题我们当初为什么弃用 SQLAlchemyHermes 会带出架构上下文、已知边界情况、过去的决策及其背后的推理——不需要任何人把它们写进 README、wiki 页面或永远找不到的 Slack 线程。这不是文档。这是永远进不了文档的机构知识。好的代码库记忆长什么样在一个项目上经过 30 个会话后一个构建良好的记忆库通常覆盖项目约定模块结构与导入模式、错误处理要求、从代码看不出来的命名约定、与默认值不同的 lint 规则。已知脆弱区域在特定负载或输入条件下会出问题的组件、引发过生产事故的集成点、测试套件覆盖不到的边界情况。架构历史被替换的依赖及原因、考虑过又否决的模式、通过测试而非文档发现的性能特性。团队偏好代码评审优先级、部署雷区、与官方文档描述不一致的实际做法。其中大部分会从普通会话中自动积累。例外是重大架构决策和团队偏好值得显式声明。做出重要决定时把理由告诉 Hermes我们正从 SQLAlchemy 切换到 asyncpg因为我们的负载画像下 连接池在约 200 并发请求以上引发间歇性超时。问题不在调优 而在 ORM 抽象层。请记住这一点。在hybrid模式下模型也可以调用hindsight_retain显式标记某内容以供保留。但后台提取已经能捕获大部分重要信息这个步骤通常不是必需的。有/无记忆的会话开场对比没有记忆时会话开场可能是我在做一个用 asyncpg 访问数据库的 Python 服务。二月因负载下的连接池问题移除了 SQLAlchemy。所有 async handler 应该用handle_errors()包裹。帮我调试这个间歇性 500……有记忆时这些事实已经被注入。你只需开场帮我调试 payment handler 里这个间歇性 500。技术栈、约定、架构上下文都已经在那里了。团队代码库共享记忆库默认bank_id为hermes。同一项目的每位开发者可以通过设置相同的bank_id共享记忆库{ bank_id: payments-service, mode: cloud }多位开发者在同一代码库上使用 Hermes 并共享记忆库时记忆会从他们所有人的会话中复利增长。一个人积累的知识——某个棘手模块未记录在文档中的行为、来之不易的调试洞察、部署雷区——会自动对其他成员可用。几点注意事项适合共享的内容代码库事实、架构决策、已知问题、约定。这些描述的是代码库而非个人可以安全共享。应保持分离的内容个人工作流偏好、无关的个人上下文。请使用独立的记忆库存放。记忆库命名一个项目一个记忆库而不是一个开发者一个。三人共用却互不协调的hermes库会变成噪音支付团队所有人都使用的payments-service库则会沉淀为机构记忆。进阶播种结构化的 Mental Model从会话中自然提取是 Hindsight 构建代码库知识的主要方式。但你可以显式前置加载上下文——在既有代码库上起步、或关键约定需要在第一个会话运行前就进入记忆库时这很有用。Hindsight 通过 SDK 与 API 暴露了两个操作Hermes 之外也可调用二者写入的是 Hermes 读取的同一个记忆库摄取既有文档Ingesting existing docs。上传架构笔记、ADR 或约定文件。Hindsight 对内容运行事实提取将结果作为记忆存入记忆库。摄取完成后这些事实在下一个会话就对 Hermes 可用——无需等待自然提取慢慢赶上。创建 Mental ModelCreating a mental model。定义一个由源查询source query构建的策展摘要例如这个项目的编码约定是什么。Hindsight 运行一次 reflect 操作从所有已摄取的与会话提取的知识中综合出答案并保存结果。设置refresh_after_consolidation为 true模型会在新事实到达时自行重新推导。reflect 调用时Mental Model 会在单个 observation 与原始事实之前被优先检查因此预计算的答案直接返回无需现场重新推导。从仓库文档看Mental Model 的本质是一个记忆库问题的常驻答案你定义一次问题Hindsight 负责书写答案、持续存储并在记忆库学到更多时于后台重写它见 mental-models.mdx。其检索优先级分层如下层级产生方式粒度Mental Models你显式策展每个问题一份完整文档ObservationsConsolidation自动每个事实簇一条信念Raw factsRetain自动每个陈述一条事实每一层都是其下一层更廉价、更稳定的版本。如果第一层命中的 Mental Model 足够新鲜且覆盖了问题reflect 可以从它作答不必下沉到 observations 和 raw facts——同样的节省发生在 agentic 循环内部。用 API 创建 Mental ModelMental Model 的创建会触发一次后台 reflect 操作并保存结果。以下为 Python SDK 示例完整可运行版本见 examples/api/mental-models.pyfrom hindsight_client import Hindsight client Hindsight(base_urlhttp://localhost:8888) client.create_bank(bank_idmental-models-demo-bank, nameMental Models Demo) # 创建 Mental Model后台运行 reflect result client.create_mental_model( bank_idmental-models-demo-bank, nameTeam Communication Preferences, source_queryHow does the team prefer to communicate?, tags[team, communication] ) # 返回 operation_id可通过 operations 端点查询完成状态 print(fOperation ID: {result.operation_id})核心参数参数类型必填说明namestring是Mental Model 的人类可读名称source_querystring是用于生成内容的查询idstring否自定义 ID小写字母数字连字符缺省自动生成tagslist否界定模型作用域的标签刷新时同时过滤源记忆max_tokensint否Mental Model 内容的最大 token 数triggerobject否自动刷新设置自动刷新让模型永远不过时Mental Model 不是会静默过期的缓存答案。Hindsight 会追踪是否有新记忆进入模型的作用域并在出现时重建它——或是在新知识整合后立即触发或按你设定的计划执行。刷新只发生在该模型自身作用域内确实有变化时繁忙的记忆库不会让无关模型空转对未变化的记忆库做计划刷新也不产生成本。trigger支持的关键设置设置类型默认值说明modefull|deltafull刷新策略。delta对既有内容做外科手术式编辑未变化章节逐字节保留应对 LLM 重写漂移refresh_after_consolidationboolfalse观察整合后自动刷新refresh_cronstring | nullnullUTC 5 段 cron 表达式如0 3 * * *表示每天 03:00 UTCmin_refresh_interval_secondsint | nullnull两次自动刷新之间的最小间隔秒数限流用tags_matchstring | nullnull刷新时标签过滤模式any/all/any_strict/all_strict/exact。带标签模型默认all_strictrefresh_after_consolidation与refresh_cron互斥——模型要么在整合后刷新要么按固定 UTC 计划刷新不能两者兼有。刷新间隔限流的典型配置{ trigger: { refresh_after_consolidation: true, min_refresh_interval_seconds: 1800 } }窗口期内触发的刷新不会丢弃而是排队挂起直到窗口关闭期间到来的所有触发会合并进同一次排队刷新——二十次 retain 的突发只花费一次刷新而这次刷新仍读取那二十次 retain 新增的全部内容。带触发器的创建示例每天 03:00 UTC 检查并刷新作用域内变更result client.create_mental_model( bank_idmental-models-demo-bank, nameProject Status, source_queryWhat is the current project status?, trigger{refresh_cron: 0 3 * * *} )版本、作用域与溯源Mental Model 还具备几项工程化特性重写间保持稳定被重写数百次的文档有一个 LLM 无法靠好好说解决的问题——告诉它保留未变化的部分它仍会漂移项目符号变编号、大小写漂移、句子被悄悄改写。Hindsight 可以增量delta刷新——只应用新知识带来的变更其余部分物理上保持原样。长期存在的 playbook 保持为你写的那份文档只是加上了新内容。作用域与隔离Mental Model 的 tags 决定两件事——它能读取哪些记忆以及哪些调用者能看到它。限定到某客户、团队或用户的模型只从该作用域的记忆构建也只对该作用域的请求浮现。溯源ProvenanceMental Model 不是漂浮的散文。它记录构建自己所用的事实与 observation并在每次变更时保留上一版本的内容。你可以看到模型上个月说了什么、它当时依据的证据是什么——当模型说出令人意外的结论时这至关重要。完整的 Mental Model API 参考创建、刷新、配置、触发、作用域与历史见 Mental Models API仓库还提供了 CLI 示例 与 Go 示例。摄入的项目文档与会话提取的事实相结合让 Hermes 从两个角度获得完整图景什么被刻意记录了下来什么通过使用被发现。这也正是自主编码代理变得可行的原因——拥有丰富、新鲜的 mental model、约定、架构、已知脆弱区域的代理拥有足够的结构化上下文来做出决策并驱动变更而无需人类在每项任务开始时做简报。持久会话记忆就是通往那个基线的路。用越久你需要解释的越少Hermes Hindsight 是唯一一个上下文能跨会话积累的编码工作流。每次会话都在增加它对代码库的认知。其他工具会重置这个不会。价值随使用复利增长第一个会话Hermes 对你的项目一无所知第五个会话它知道技术栈和约定第 30 个会话它知道项目的历史、脆弱区域、塑造其当前形态的决策。到那时你不再解释那些东西——不是因为跳过了上下文而是因为你再也不需要提供它。一旦 mental model 足够丰富你面对的不只是一个编码助手而是一个和你一样了解代码库的代理。用hermes memory setup开始或在 Hermes 集成文档 中查看更完整的集成列表该目录下还包含 codex、claude-code、cursor 等大量编码代理的 Hindsight 集成方式。延伸阅读仓库内What Is Agent Memory? 相关背景——Hindsight 作为 Hermes Agent 原生记忆 provider 的发布说明同目录下另有 Adding Persistent Memory to Codex with Hindsight 等同类模式文章Recall 架构recall 的四种检索策略语义、BM25 关键词、图遍历、时间与 RRF 融合Observations由 retain 自动产生、按证据聚类的原子信念Reflect APIagentic 推理循环与 mental model 优先的检索阶梯【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考