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 模块而非 CommonJS，import 中始终使用 .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.0（v2026.5.16）起内置了 Hindsight 原生集成。搭建只需一条向导命令：

hermes memory setup # 选择 "hindsight"

确认记忆已激活：

hermes memory status

配置存放在$HERMES_HOME/hindsight/config.json，默认值已适配大多数工作流：

memory_mode：记忆以何种方式浮现

memory_mode控制记忆在 Hermes 中呈现的方式：

• hybrid（默认）：每轮对话前自动注入记忆，同时模型可用hindsight_recall、hindsight_retain、hindsight_reflect工具
• context：仅自动召回，无显式工具，无需模型操心
• tools：模型必须显式调用hindsight_recall，不自动注入任何内容

对编码工作而言，hybrid是正确的默认值——每轮自动召回，同时还能让 Hermes 显式调出它对某个组件的认知。

部署形态：cloud 与 local

• cloud：跨机器工作或与团队共享记忆时使用。记忆保存在云端记忆库，多台设备、多位成员读写同一份数据。
• 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 的 N+1 模式都会重现，代码评审时需强制 DataLoader 落地"

这些不是你会在调试会话开头想起来粘贴的事实。它们是区分"盲调"与"带着完整上下文调试"的机构知识。

对本工作流，值得启用prefetch_method: reflect。与通过语义搜索检索单条事实不同，reflect让 LLM 在注入前，先把所有相关记忆综合成一份连贯摘要。速度更慢，但对"帮我理解这类 bug"的查询，综合后的上下文比单条事实列表有用得多。

从实现看，reflect 是一个完整的agentic 推理循环：代理使用多种检索工具自主搜索记忆库，应用记忆库的 disposition traits 塑造推理风格，最终产出基于证据的回答——而不是像 recall 那样返回原始事实列表（见 reflect.mdx）。

工作流三：接手别人的代码

如果你加入一个同事已经用 Hermes + Hindsight 在共享记忆库上工作过的项目，记忆库里已经有了他们会话沉淀的上下文。

直接向 Hermes 提问，它会浮现此前会话积累的事实：

你对 payments 模块了解多少？

auth 服务里出现过哪些坑或已知问题？

我们当初为什么弃用 SQLAlchemy？

Hermes 会带出架构上下文、已知边界情况、过去的决策及其背后的推理——不需要任何人把它们写进 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 Model（Creating a mental model）。定义一个由源查询（source query）构建的策展摘要，例如"这个项目的编码约定是什么？"。Hindsight 运行一次 reflect 操作，从所有已摄取的与会话提取的知识中综合出答案并保存结果。设置refresh_after_consolidation为 true，模型会在新事实到达时自行重新推导。reflect 调用时，Mental Model 会在单个 observation 与原始事实之前被优先检查，因此预计算的答案直接返回，无需现场重新推导。

从仓库文档看，Mental Model 的本质是"一个记忆库问题的常驻答案"：你定义一次问题，Hindsight 负责书写答案、持续存储，并在记忆库学到更多时于后台重写它（见 mental-models.mdx）。其检索优先级分层如下：

每一层都是其下一层更廉价、更稳定的版本。如果第一层命中的 Mental Model 足够新鲜且覆盖了问题，reflect 可以从它作答，不必下沉到 observations 和 raw facts——同样的节省，发生在 agentic 循环内部。

用 API 创建 Mental Model

Mental Model 的创建会触发一次后台 reflect 操作并保存结果。以下为 Python SDK 示例（完整可运行版本见 examples/api/mental-models.py）：

from hindsight_client import Hindsight client = Hindsight(base_url="http://localhost:8888") client.create_bank(bank_id="mental-models-demo-bank", name="Mental Models Demo") # 创建 Mental Model（后台运行 reflect） result = client.create_mental_model( bank_id="mental-models-demo-bank", name="Team Communication Preferences", source_query="How does the team prefer to communicate?", tags=["team", "communication"] ) # 返回 operation_id，可通过 operations 端点查询完成状态 print(f"Operation ID: {result.operation_id}")

核心参数：

自动刷新：让模型永远"不过时"

Mental Model 不是会静默过期的缓存答案。Hindsight 会追踪是否有新记忆进入模型的作用域，并在出现时重建它——或是在新知识整合后立即触发，或按你设定的计划执行。刷新只发生在该模型自身作用域内确实有变化时：繁忙的记忆库不会让无关模型空转，对未变化的记忆库做计划刷新也不产生成本。

trigger支持的关键设置：

refresh_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_id="mental-models-demo-bank", name="Project Status", source_query="What is the current project status?", trigger={"refresh_cron": "0 3 * * *"} )

版本、作用域与溯源

Mental Model 还具备几项工程化特性：

• 重写间保持稳定：被重写数百次的文档有一个 LLM 无法靠"好好说"解决的问题——告诉它"保留未变化的部分"，它仍会漂移（项目符号变编号、大小写漂移、句子被悄悄改写）。Hindsight 可以增量（delta）刷新——只应用新知识带来的变更，其余部分物理上保持原样。长期存在的 playbook 保持为你写的那份文档，只是加上了新内容。
• 作用域与隔离：Mental Model 的 tags 决定两件事——它能读取哪些记忆，以及哪些调用者能看到它。限定到某客户、团队或用户的模型，只从该作用域的记忆构建，也只对该作用域的请求浮现。
• 溯源（Provenance）：Mental 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 API：agentic 推理循环与 mental model 优先的检索阶梯

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