企业官网建设流程全解析

Hindsight 成为 Hermes Agent 原生内存提供者：两分钟接入持久记忆的完整配置指南

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

Hindsight 现已作为 Hermes Agent 的原生内存提供者（Native Memory Provider）随代理内置发布，用户无需安装任何额外插件，只需运行一条向导命令即可为代理接入跨会话的持久记忆。本文将完整讲解 Hermes 原生内存提供者的工作原理（turn 前自动召回、turn 后异步留存）、hybrid/context/tools三种记忆模式的选型与切换、config.json全部配置项、从旧版hindsight-hermes插件的迁移路径，以及本地嵌入模式与云端模式的部署差异，并结合本仓库源码给出底层实现佐证。

为什么 Hermes 需要原生内存提供者

Hermes Agent 自带一套内置记忆工具：它把模型明确决定记下的内容保存为本地 Markdown 文件（MEMORY.md与更精简的USER.md档案）。这种方式能工作，但存在本质局限——它只能捕获模型"显式决定写下来"的内容，无法捕获模型从对话中"隐式学到"的东西，上下文不会自动累积。周一你让 Hermes 帮忙规划一次 Sprint，周五开启新会话时，它已经不记得项目、团队成员和截止日期，除非你重新建立上下文。

Hindsight 用跨会话的持久记忆解决这个问题：你只需提一次产品发布日期，一周后在一个完全不同话题的新会话中，Hermes 已经知道这个日期。你不需要重复自己，不需要粘贴上下文，记忆会被自动召回。

从仓库源码结构看，这套能力建立在一套完整的记忆后端之上：事实提取、实体消解、知识图谱、多策略检索与交叉编码器重排（cross-encoder reranking）都在 Hindsight 服务端完成。内置记忆只是扁平文本，而 Hindsight 提供结构化的事实、实体与关系，这正是两者最根本的差异，详细对比可参见早期的插件教程 Give the Only Self-Improving AI Agent (Hermes) a Memory Upgrade It Deserves。

工作原理：在 Hermes 生命周期中两个接入点

Hindsight 原生提供者在 Hermes 的每次对话轮次（turn）中，于两个位置介入：

每一轮开始前（pre_llm_call hook）：Hindsight 排队执行一次异步预取（prefetch）。过去会话中的相关记忆被检索出来，在 LLM 看到你的消息之前注入到系统提示词中。模型因此拥有此前对话的上下文，而你无需重复任何内容。

每一轮响应后（post_llm_call hook）：你的对话被异步留存（retain）。Hindsight 在后台提取事实、实体和关系，本轮的对话内容从下一次调用起即可被检索到。

这个设计是有意为之：预取模式意味着当前轮次的记忆要到下一轮才会出现，这保证了每一次调用的速度。集成文档 Hermes Agent Persistent Memory with Hindsight 明确列出了提供者注册到 Hermes 的全部组件：

注意：pre_llm_call/post_llm_call生命周期钩子要求 hermes-agent 具备对应 PR（#2823）之后的版本；在更老的版本上只注册三个工具，钩子会被静默跳过，自动注入不生效。

底层 API 路由在源码中有明确对应：召回与反射分别注册为POST /banks/{bank_id}/memories/recall与POST /banks/{bank_id}/reflect等端点（见 hindsight-api-slim/hindsight_api/api/http.py 附近的路由表），而重排层由跨编码器抽象统一封装（见 hindsight-api-slim/hindsight_api/engine/cross_encoder.py），支持本地进程内模型与远程 TEI 端点，说明"召回"背后确实是一条多策略检索加重排的完整流水线。

为什么选择 Hindsight：BEAM 基准与规模效应

在所有受支持的内存提供者中，Hindsight 是唯一一个在 BEAM 基准上公布了结果的提供者。BEAM（"Beyond a Million Tokens"）专门测试 1000 万 token 级别的记忆能力——在这个规模下，把全部上下文塞进提示词（context stuffing）在物理上已经不可能，只有真正的记忆架构才能存活。相关完整解读见 Hindsight Is #1 on BEAM — the Benchmark That Tests Memory at 10 Million Tokens。

BEAM 各档位上的公开结果：

在 10M 档位，Hindsight 得分为 64.1%，第二名的公开成绩是 40.6%（领先 58%）；相对论文基线则是 2.4 倍以上。值得注意的细节是：Hindsight 的 1M 得分（73.9%）高于其 500K 得分（71.1%）——随着 token 量增加性能不降反升，而大多数系统呈现相反趋势，这正是记忆架构在规模效应下应有的表现。

两分钟接入：设置向导与状态确认

全新接入只有一条向导命令，选择hindsight即可：

hermes memory setup # 选择 "hindsight"

然后确认记忆已激活：

hermes memory status

向导会提示你输入 API Key 与 API URL 并自动完成全部配置。如果你偏好手动配置，也可以直接设置提供者并写入环境变量（env var 优先级高于配置文件）：

hermes config set memory.provider hindsight echo "HINDSIGHT_API_KEY=your-key" >> ~/.hermes/.env echo "HINDSIGHT_API_URL=https://api.hindsight.vectorize.io" >> ~/.hermes/.env

云端 API 端点为https://api.hindsight.vectorize.io，API Key 可在控制台申请。配置落盘在$HERMES_HOME/hindsight/config.json（默认即~/.hermes/hindsight/config.json），主文档给出了这份核心配置表：

集成文档 hermes.md 进一步列出了每个配置项对应的环境变量覆盖方式，常用几组如下：

• 连接与守护进程：mode（HINDSIGHT_MODE）、api_url（HINDSIGHT_API_URL）、api_key（HINDSIGHT_API_KEY）、apiPort（HINDSIGHT_API_PORT，本地守护进程端口默认9077）、embedVersion（HINDSIGHT_EMBED_VERSION，指定hindsight-embed版本）
• LLM 提供者（仅 local 模式）：llm_provider（HINDSIGHT_LLM_PROVIDER，支持openai、anthropic、gemini、groq、minimax、ollama、lmstudio）、llm_api_key（HINDSIGHT_LLM_API_KEY）、llm_model（HINDSIGHT_LLM_MODEL）。各提供者默认模型为：openai→gpt-4o-mini、anthropic→claude-haiku-4-5、gemini→gemini-2.5-flash、groq→openai/gpt-oss-120b、minimax→MiniMax-M3、ollama→gemma3:12b
• 记忆库：bank_id（HINDSIGHT_BANK_ID）、bankMission（HINDSIGHT_BANK_MISSION，代理身份/用途描述）、retainMission（自定义留存任务，决定从对话中提取什么）
• 自动召回：autoRecall（HINDSIGHT_AUTO_RECALL，默认true）、recallBudget（HINDSIGHT_RECALL_BUDGET，即low/mid/high）、recallMaxTokens（HINDSIGHT_RECALL_MAX_TOKENS，默认4096）、recallMaxQueryChars（HINDSIGHT_RECALL_MAX_QUERY_CHARS，默认800）、recallPromptPreamble（注入在召回记忆之前的引导文案）
• 自动留存：autoRetain（HINDSIGHT_AUTO_RETAIN，默认true）、retainEveryNTurns（默认1）、retainOverlapTurns（额外重叠轮次，默认2）、retainRoles（默认["user", "assistant"]）
• 调试：debug（HINDSIGHT_DEBUG，默认false）

其中budget（召回力度）直接影响召回阶段投入的检索与重排计算量，与recallBudget是同一配置的不同视角：low追求速度、mid为默认平衡、high追求彻底。

记忆模式：hybrid / context / tools

自动召回是核心行为：每一轮开始前，Hindsight 自动从历史中获取相关记忆并注入系统提示词——Hermes 无需调用任何工具、你也无需重复自己，每次调用都会透明发生。memory_mode设置决定自动召回是否启用、以及显式工具是否暴露给模型：

三种模式的选型逻辑（详见指南 Hermes Memory Modes with Hindsight）：

• hybrid：最安全的默认值，适合大多数用户。自动上下文加显式工具，既方便调试又保留控制力；适合内部助手与技术用户。
• context：面向最终用户的隐形个性化。工具面更干净、行为噪声更少，适合客服型助手——模型"天然"带着历史开始对话，不需要记得"记忆"是一个工具类别。
• tools：模型自行决定何时查询记忆。提示词控制更紧，适合把hindsight_recall/hindsight_reflect当作一等推理工具的实验性代理策略。代价是明显的：如果模型提示词不佳，它可能干脆忘记使用记忆。请记住一条规则——tools模式下自动召回消失不是故障，这正是设计。

prefetch_method控制自动召回阶段记忆的获取方式：

• recall（默认）：语义检索、关键词匹配、实体图谱遍历加重排，速度快。
• reflect：LLM 把全部相关记忆综合成一份连贯摘要，更慢，但在复杂上下文场景下更有用。

从源码结构看，recall的"多策略检索加重排"有据可循：服务端召回路由之后会经过跨编码器统一重排层（cross_encoder.py 中的CrossEncoderModel抽象及其本地/远程实现），而reflect则对应独立的/reflect端点（见 http.py 附近路由），其内部走 LLM 合成路径。

实际选型建议：hybrid+prefetch_method="recall"是最省心的起点；需要连贯摘要胜过逐条事实时（复杂规划、开放式推理）再切换到reflect。切到tools模式时要注意prefetch_method不生效（自动召回已关闭），但留存（retention）仍然照常运行——tools只改变召回进入代理的方式，不关闭留存。

从旧插件迁移：替换hindsight-hermes

如果你此前按早期教程把hindsight-hermes作为 pip 插件安装过（通过hermes_agent.pluginsentry point 注册进 Hermes 虚拟环境），这个路径已废弃——在当前的 Hermes 构建中其工具会报{"error": "Timeout context manager should be used inside a task"}。迁移分两步：

第一步，卸载旧插件（使用与 Hermes 相同的 Python 环境）：

uv pip uninstall hindsight-hermes --python $HOME/.hermes/hermes-agent/venv/bin/python

不用uv时的等价命令：

$HOME/.hermes/hermes-agent/venv/bin/python -m pip uninstall -y hindsight-hermes

卸载后可通过 entry point 检查确认清理干净：

$HOME/.hermes/hermes-agent/venv/bin/python - <<'PY' import importlib.metadata for ep in importlib.metadata.entry_points(group='hermes_agent.plugins'): print(f"{ep.name}: {ep.value}") PY

如果仍能看到hindsight条目，说明卸载错了环境。

第二步，运行设置向导配置原生提供者：

hermes memory setup

迁移的关键是保留同一个bank_id。记忆属于 Hindsight 记忆库（bank），而不属于废弃的插件包本身——只要新提供者指向同一个后端、同一个bank_id，就能继续使用原有的记忆历史，无需导出导入、无需重新教代理。完整的逐步迁移流程（含备份、验证与常见问题排查）见指南 Migrate hindsight-hermes to Native Hermes Memory，其要点包括：迁移前备份~/.hermes与~/.hindsight、迁移后运行hermes memory status、在工具列表中确认三个 Hindsight 工具可见、并做一次"下一轮召回"的跨会话实测。

迁移过程中还应考虑禁用 Hermes 内置的扁平文件记忆，避免两条记忆路径互相竞争（模型可能出于习惯优先选择它已经认识的内置memory工具）：

hermes config set memory.memory_enabled false # 关闭 MEMORY.md hermes config set memory.user_profile_enabled false # 可选，关闭 USER.md

两个标志都设为false后，内置memory工具会从代理中完全移除；需要时再设回true即可恢复。

本地模式与云端模式

本地模式（local）：Hindsight 运行一个内嵌服务器，自带 PostgreSQL。守护进程在首次使用时自动于后台启动，无需手动设置。记忆提取需要 LLM API Key：

{ "mode": "local", "llm_provider": "groq", "llm_api_key": "your-groq-key" }

本地守护进程的关键行为与路径：

• 守护进程在 Hermes 显示 "starting agent"（你发送第一条消息）时才启动，而非启动时；全新系统上内嵌 PostgreSQL 初始化可能耗时超过一分钟，后续启动则很快。
• 启动日志位于~/.hermes/logs/hindsight-embed.log，运行日志位于~/.hindsight/profiles/<profile>.log，排查问题时可查看。
• 本地 API 健康检查：curl http://localhost:9077/health。
• uvx hindsight-embed可以独立启动本地守护进程，免安装，代理连接http://localhost:8888（这是独立运行模式下的默认端口；作为 Hermes 原生提供者时守护进程端口由apiPort控制，默认9077）。

云端模式（cloud）：需要跨机器持久记忆、或多个 Hermes 实例共享同一份记忆时，使用云端模式（https://api.hindsight.vectorize.io）。两种模式使用同一套 API，切换只是一行配置的改动，而不是一次迁移。

一个常见误区需要澄清：留存是异步的。API 立即返回，事实提取在后台完成。如果在同一轮里"留存"后立刻"召回"，新事实可能尚未完成索引——这不是故障，而是设计。测试记忆时务必在下一轮或新会话中提问（详见迁移指南中的实测章节）。这正好呼应了主文档的说明：预取模式意味着当前轮次的记忆要到下一轮才会出现。

实战验证清单

接入完成后，建议按下面的分层方式验证，而不是只依赖单一检查：

1. hermes memory status——确认 Hermes 识别到 Hindsight 提供者处于激活状态。
2. 检查配置文件中的mode、bank_id、memory_mode、prefetch_method四个关键值是否符合预期。
3. 检查工具可见性——hybrid模式应能看到hindsight_retain、hindsight_recall、hindsight_reflect；context模式不应看到。
4. 跨会话行为实测——先让 Hermes 记住一个事实，然后在下一轮或新会话中提问验证自动召回。
5. 本地模式下验证守护进程健康：curl http://localhost:9077/health。

如果自动召回始终不生效，优先检查：memory_mode是否被误设为tools（该模式下无自动注入属正常）；Hermes 构建是否支持生命周期钩子（老版本只注册工具、静默跳过自动注入）；以及api_url/HINDSIGHT_API_KEY是否已配置（未配置时提供者会静默跳过工具注册）。

延伸阅读

• Hermes 集成完整参考：Hermes Agent Persistent Memory with Hindsight
• BEAM 基准完整数据与背景：Hindsight Is #1 on BEAM
• 迁移逐步指南：Migrate hindsight-hermes to Native Hermes Memory
• 记忆模式选型指南：Hermes Memory Modes with Hindsight
• 早期插件方案（已废弃）与架构对比：Give Hermes a Memory Upgrade
• 后端检索与重排实现：cross_encoder.py、API 路由表 http.py

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