企业官网建设流程全解析

为 Hermes Agent 接入 Hindsight 原生记忆：配置、模式与深度实践指南

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

本指南围绕 Hermes Agent 的原生 Hindsight 记忆提供方展开，讲解如何让 Hermes 在每次 LLM 调用前自动召回相关历史记忆、在每次响应后异步沉淀对话，并通过 retain/recall/reflect 三件工具实现显式记忆控制。读完本文，你将掌握hermes memory setup的完整配置面（Cloud 与本地嵌入式两种连接模式、全部配置项与环境变量覆盖）、hybrid/context/tools三种集成模式的选择逻辑，以及从旧版插件平滑迁移和排查"记忆不生效"的完整方法。

背景：从独立插件到原生记忆提供方

Hermes Agent 现已内置可插拔的记忆提供方（memory provider）体系，Hindsight 是其中一个受支持的记忆后端。它通过两个生命周期钩子与 Hermes 深度集成：

• 每次对话前（pre_llm_call钩子）：异步预取（prefetch）与当前对话相关的历史记忆，注入到 system prompt 中，让模型在收到用户消息前就拥有此前会话的上下文；
• 每次响应后（post_llm_call钩子）：异步将本轮用户/助手对话沉淀（retain）到 Hindsight，由 Hindsight 在后台抽取事实、实体与关系，供后续会话检索。

这个"响应后才保留、下一轮才可见"的设计是刻意的：它保证每一轮 LLM 调用都保持快速，代价是当前轮产生的新记忆要到下一轮才会出现。

⚠️ 弃用说明：独立插件hindsight-hermes

旧的独立hindsight-hermespip 插件（安装进 Hermes 虚拟环境、通过hermes_agent.pluginsentry point 注册）已被弃用。在当前 Hermes 版本上，它的工具会报{"error": "Timeout context manager should be used inside a task"}。

Hermes 现在自带原生 Hindsight 记忆提供方，本页即围绕它展开——无需额外安装任何东西，只需运行hermes memory setup并选择hindsight。若你仍在用旧插件，可参考迁移指南切换，同时保留同一 memory bank。

💡 提示

使用Hermes 桌面应用？你可以在 Settings 中完全通过界面完成 Hindsight 的选配，无需终端，参见 Hermes Desktop。

快速开始：三分钟让 Hermes 拥有长期记忆

1. 获取 API Key：在 Hindsight Cloud 控制台获取，API 端点为https://api.hindsight.vectorize.io。

2. 运行设置向导：

hermes memory setup # select "hindsight"

向导会提示输入 API Key 和 API URL，并自动完成全部配置。

也可以手动配置：

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

3. 确认记忆已激活：

hermes memory status

若hermes memory status输出中显示Provider: hindsight且Status: available，则说明 Hindsight 已被 Hermes 识别为激活的记忆提供方。

核心特性

• 自动召回（Auto-recall）——每轮对话都向 Hindsight 查询相关记忆，并通过pre_llm_call钩子注入 system prompt；
• 自动沉淀（Auto-retain）——每次响应后通过post_llm_call钩子将用户/助手对话沉淀到 Hindsight；
• 显式工具（Explicit tools）——hindsight_retain、hindsight_recall、hindsight_reflect三个工具供模型直接调用；
• 记忆模式（Memory modes）——可在自动注入、纯工具、混合三种模式间选择；
• 零配置开销（Zero config overhead）——环境变量可作为覆盖项，方便 CI/自动化场景。

📝 注意

pre_llm_call/post_llm_call生命周期钩子需要 hermes-agent PR #2823 及以后的版本。在旧版本上，只有三个工具会被注册，钩子会被静默跳过（即"工具可用但自动注入不生效"）。

架构：钩子与工具的分工

原生提供方在 Hermes 中注册如下钩子与工具：

这一"异步预取 + 异步沉淀"的结构在仓库的兼容性测试脚本中有完整印证。scripts/test-hermes-compat.sh 从 5 个层次验证 Hermes 与 Hindsight 的协同：依赖解析与pip check（针对 #3251 中 Hermes 精确锁定cryptography、pillow版本导致的冲突）、hermes memory status的 provider 接线检查、嵌入式运行时模块导入探测，最后实际启动嵌入式 daemon（pg0 + 本地 embedding 模型）完成建库、retain、recall 的往返验证。其中 daemon 的管理正是通过 hindsight-all/hindsight/embedded.py 中的HindsightEmbedded客户端完成——该客户端复用hindsight-embed的 daemon 管理接口，首次使用时自动拉起后台 daemon，并暴露retain()、recall()、reflect()、create_bank()等与HindsightClient一致的方法。

连接模式

1. Cloud（生产环境推荐）

连接 Hindsight Cloud（https://api.hindsight.vectorize.io），在控制台获取 API Key。无需自托管任何基础设施，存储、抽取与检索均由云端完成。

{ "mode": "cloud", "api_url": "https://api.hindsight.vectorize.io", "api_key": "hsk_your_token", "bank_id": "hermes" }

Cloud 模式适合需要跨机器共享记忆、或在多个 Hermes 实例间复用同一份记忆的场景；两种模式使用同一套 API，切换只需改一行配置，并非一次迁移。

2. Local（嵌入式）

运行内嵌的 Hindsight 服务器与自带 PostgreSQL。需要提供 LLM API Key 用于记忆抽取与综合（synthesis）。首次使用时 daemon 会在后台自动启动。

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

📝 注意

嵌入式服务器在 Hermes 显示 "starting agent"（即首条消息）时启动，而非启动时。全新系统上，嵌入式 PostgreSQL 初始化可能需要超过一分钟；后续启动会很快。

daemon 启动日志：~/.hermes/logs/hindsight-embed.logdaemon 运行日志：~/.hindsight/profiles/<profile>.log

从源码看，嵌入式 daemon 的数据隔离以profile为粒度：profile 环境（~/.hindsight/profiles/<profile>.env）与 pg0 数据目录（~/.pg0/instances/hindsight-embed-<profile>）都键控在 profile 名称上，见 scripts/test-hermes-compat.sh 中的相关注释。这也解释了为什么 CI 使用独立的hermes-ciprofile 即可避免与开发者的真实 profile 冲突。

配置参考

所有配置项都在~/.hermes/hindsight/config.json。每一项都可通过环境变量覆盖（环境变量优先级更高）。

连接与 Daemon

apiPort默认 9077 也是本地健康检查的端口（见下文 Troubleshooting 中的curl http://localhost:9077/health）。

LLM Provider（仅 local 模式）

各提供方默认模型：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。

值得注意的是，scripts/test-hermes-compat.sh 揭示了llm_api_key的一个关键行为：嵌入式 daemon 的 MemoryEngine 在没有 LLM Key 时拒绝构造，因此兼容性测试即使没有真实凭证也会用占位 key 启动 daemon 来证明依赖集"能跑"，但 retain/recall 往返只有在设置了HERMES_COMPAT_LLM_API_KEY时才会执行。

Memory Bank

bank_id是记忆归属的关键：记忆附着在 Hindsight 的 bank 上，而非某个插件包上。迁移或排查时若更换了bank_id，等于把 Hermes 指向了一个不同的"大脑"。

Auto-Recall

默认引导文案（preamble）：

Relevant memories from past conversations (prioritize recent when conflicting). Only use memories that are directly useful to continue this conversation; ignore the rest:

Auto-Retain

集成模式

memory_mode：

• hybrid—— 每轮对话前自动注入上下文，同时向 LLM 暴露工具
• context—— 仅自动注入；不向模型暴露工具
• tools—— 仅工具（hindsight_retain、hindsight_recall、hindsight_reflect）；无自动注入

prefetch_method：

• recall—— 将原始记忆事实注入 system prompt（快速）
• reflect—— 注入基于相关记忆的 LLM 综合摘要（较慢，但更连贯）

其他

三种集成模式：何时选 hybrid / context / tools

memory_mode决定记忆以何种方式进入 agent 循环，这是 Hermes 记忆体验的分水岭：

关键规则：tools模式下自动召回消失不是故障，而是设计使然。若模型提示词引导不足，它可能干脆忘记查记忆——tools模式给你控制权，但牺牲了可靠性。

prefetch_method仅在自动召回激活时（即hybrid与context）生效：

不确定时保持recall：更易推理、更易调试。当模型反复需要连贯的记忆摘要而非零散事实时，再切换到reflect。更深入的选型讨论可参考Hermes 记忆模式专项指南。

Hermes Gateway（Telegram、Discord、Slack）

在 gateway 模式（多平台消息）下，提供方在所有平台均可用。Hermes 为每条消息创建全新的AIAgent，而提供方的pre_llm_call钩子确保无论消息来自哪个平台，每一轮都会召回相关记忆——记忆跟随用户，而不是跟随某个会话实例。

禁用 Hermes 内置记忆

Hermes 自带一个内置记忆存储，将内容写入本地 markdown 文件（MEMORY.md，以及更精简的USER.md用户档案）。如果两套记忆同时启用，LLM 可能更倾向于使用内置的那一套。关闭扁平文件存储：

# 关闭内置 MEMORY.md 存储 hermes config set memory.memory_enabled false # 可选——同时关闭精简的 USER.md 档案存储 hermes config set memory.user_profile_enabled false

将两者都设为false后，内置memory工具会从 agent 中完全移除。后续想恢复，将相同标志改回true即可。这一配置也出现在 scripts/test-hermes-compat.sh 的步骤 3 中：CI 在验证hermes memory status时同时置memory_enabled: false与user_profile_enabled: false，以确保"关闭扁平文件存储不会把 Hindsight provider 一起拖垮"。

从旧插件迁移到原生提供方

若你正在使用已弃用的hindsight-hermes插件，迁移本身通常比想象中小。多数情况下流程是：卸载旧插件包、让 Hermes 指向原生 provider、保持相同bank_id、在下一轮验证自动召回。

先检查旧插件是否存在：

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

随后按顺序执行：

# 1. 备份当前配置 mkdir -p ~/hermes-memory-migration-backup cp -R ~/.hermes ~/hermes-memory-migration-backup/hermes cp -R ~/.hindsight ~/hermes-memory-migration-backup/hindsight 2>/dev/null || true # 2. 从 Hermes 环境卸载旧插件 uv pip uninstall hindsight-hermes --python $HOME/.hermes/hermes-agent/venv/bin/python # 或使用 pip 回退方案： # $HOME/.hermes/hermes-agent/venv/bin/python -m pip uninstall -y hindsight-hermes # 3. 配置原生 provider hermes memory setup # 选择 hindsight # 或手动配置： # hermes config set memory.provider hindsight # printf '%s\n' 'HINDSIGHT_API_KEY=your-key' >> ~/.hermes/.env # printf '%s\n' 'HINDSIGHT_API_URL=https://api.hindsight.vectorize.io' >> ~/.hermes/.env

迁移中最容易遗漏的关键点是bank_id保持一致。记忆附着在 Hindsight 的 bank 上，而非旧插件包本身。只要新 provider 指向同一后端、同一bank_id，就能继续使用原有的记忆存储——无需导出/导入任何数据。完整的迁移步骤、验证流程与常见错误（如卸载到错误环境导致 entry point 残留、迁移后 agent 什么都不记得等）详见迁移指南。

Troubleshooting

工具没有出现在/tools中：检查api_url（或HINDSIGHT_API_URL）是否已设置，或 cloud 模式下HINDSIGHT_API_KEY是否已设置。未配置时 provider 会静默跳过工具注册。

连接被拒绝（Connection refused）：验证 Hindsight API 是否在运行：

curl http://localhost:9077/health

本地 daemon 无法启动：检查 daemon 日志中的错误：

cat ~/.hermes/logs/hindsight-embed.log

召回返回空（Recall returning no memories）：记忆至少需要一个 retain 周期才会进入 bank。先存入一条事实，再在新会话中提问。

当"记忆不生效"时，可按此顺序逐层排查（详见调试指南）：

1. 先查memory_mode：tools模式默认不做自动召回，这是最常见也最容易误判的原因；
2. 确认后端健康：local 模式直接curl http://localhost:9077/health；cloud 模式看hermes memory status与~/.hermes/.env中HINDSIGHT_开头的变量是否齐全；
3. 用"下一轮"做受控测试：先让 Hermes 记住一条事实，等响应结束，在下一轮再询问。沉淀是异步的，同一轮内立即验证会把正常异步行为误判为故障；
4. 确认钩子可用：若显式hindsight_recall可用但hybrid/context下从不自动注入，很可能是 Hermes 版本过旧、缺少原生生命周期钩子；
5. 检查模型是否在用错误路径：内置 markdown 记忆未关闭时，模型可能仍在用旧的memory工具；排查期可先关闭以消除歧义；
6. 看日志而不是猜：tail -f ~/.hindsight/profiles/*.log查看运行期日志，或将debug设为true后重启复现；
7. 核对bank_id：有时召回是健康的，只是 Hermes 指向了错误的 bank——迁移或手改配置后最容易发生。

结语

Hindsight 原生记忆提供方让 Hermes Agent 获得了跨会话的持久记忆能力：pre_llm_call/post_llm_call钩子承载自动召回与自动沉淀，三个显式工具提供模型级控制，memory_mode与prefetch_method则让记忆的注入方式可按场景自由调节。无论选择 Cloud 的零运维、Local 嵌入式的数据自治，还是从旧插件平滑迁移，保持bank_id一致与遵循"下一轮验证"的异步节奏，都是让记忆真正生效的两个关键原则。

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