给 Hermes Desktop 装上跨会话记忆：Hindsight 记忆配置完整指南

给 Hermes Desktop 装上跨会话记忆：Hindsight 记忆配置完整指南

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

Hermes Desktop 是 Nous Research 推出的 Hermes Agent 的桌面端形态。本文演示如何在应用内完成Hindsight 记忆配置：三步操作，不用打开终端。配置完成后，Agent 会在每次对话前自动回忆相关记忆，在每次响应后自动留存关键信息，获得跨会话、跨设备的长期记忆。

三步让 Agent 拥有跨会话记忆

整个过程在应用内完成，共三步。

第一步：打开 Memory & Context 选择 Hindsight 🖱️

1. 打开Settings → Memory & Context。
2. 找到Memory Provider（记忆提供方）下拉框。
3. 选择Hindsight。

如上图，Memory & Context 面板中 Memory Provider 下拉框已展开，选项包括 Builtin、Hindsight、Honcho，选择 Hindsight。它是唯一会渲染出完整配置面板的记忆提供方，选择其他提供方时设置区域保持空白。

第二步：填写设置面板的 5 个字段

选择 Hindsight 后，专属设置面板立即展开。

截图展示了 Mode、API key、API URL、Bank ID、Recall budget 五个字段，右下角是蓝色的Save按钮。各字段的作用如下：

第三步：粘贴 API Key 并点击 Save 💾

1. Cloud 模式下，从 Hindsight Cloud 控制台的 Connect 页面获取形如hsk_开头的 API Key。
2. 粘贴进API key输入框。
3. 点击Save。

至此 Hermes 就拥有了持久化的长期记忆。

Cloud 还是 Local External：两种模式怎么选

面板只提供两种模式，覆盖托管与自托管两大部署形态。

Cloud 模式 ☁️：粘贴 Key 即可

• 最快捷的路径：粘贴 Hindsight Cloud 控制台 Connect 页面获取的 API Key。
• Hindsight Cloud 负责存储、事实抽取（retain）与检索（recall）。
• 本地无需托管任何服务，零基础设施成本。
• 适合绝大多数个人用户与团队起步场景。

Local External 模式 🏠：连接自建实例

• 如果你已在自己的基础设施上运行 Hindsight 实例（Docker 或 Kubernetes 自托管），把Mode切到Local External。
• 将API URL指向你的实例，例如http://localhost:8888。
• 记忆数据完全不会离开你的基础设施，适合对数据主权、隐私合规有严格要求的场景。

这一模式对应 Hindsight 的标准服务端形态。用 README 中的 Docker 快速开始起一个本地实例即可，命令如下：

export OPENAI_API_KEY=sk-xxx docker run -it --pull always --name hindsight --restart unless-stopped -p 8888:8888 -p 9999:9999 \ -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \ -v hindsight-data:/home/hindsight/.pg0 \ ghcr.io/vectorize-io/hindsight:latest

启动后 API 位于http://localhost:8888（UI 位于http://localhost:9999），把该地址填入面板的API URL即可。另有pip install hindsight-api的裸机部署与 Helm 的 Kubernetes 部署，完整自托管方案见仓库中的 docker-compose 示例 与 Helm Chart。

配置字段逐个说：每个值最终落在哪里

API key 如何安全存储 🔒：只写不回读

• 保存时，API key 写入系统密钥存储区（secret store）。
• 属于只写密钥：保存后不会再被回读到表单，面板显示 "API key set" 徽章提示已配置。
• 这种设计避免密钥在 UI 层反复传输与展示，降低泄露面。
• Mode、API URL、Bank ID、Recall budget 则写入当前 Hermes 配置档案——密钥进密钥库、配置进档案，各归其位。

Bank ID 怎么设：记忆隔离的单元

• 记忆库是完整、隔离的存储单元：内部包含记忆（facts）、文档、实体、实体间关系（知识图谱）以及指令（directives）。
• 不同 bank 之间完全隔离，bank A 的记忆在 bank B 中不可见，详见 Memory Banks 文档。
• 默认值hermes意味着每个配置档案默认使用独立的记忆空间。
• 读取一个不存在的 bank 会返回 404，而非空结果：拼错或误删 Bank ID 时显式报错，不会静默给出看似健康的空数据。
• 每个 profile 指向一个 Bank ID，因此记忆按档案隔离，并随档案"漫游"——档案运行在哪台机器上，记忆就跟到哪台机器。
• 同一份档案在多台设备上使用时，Agent 的记忆全局一致、跨会话持续：偏好、决策、项目上下文都会在每次对话中被正确回忆。

Recall budget 怎么选 🎚️：low、mid、high

• 该字段对应 Hermes 侧HINDSIGHT_RECALL_BUDGET环境变量与recallBudget配置项。
• 服务端会把 recall 请求中的budget参数映射为内部检索的thinking_budget（整数），作用于语义检索、BM25、知识图谱、时序检索等每一条检索通道。
• fixed（默认）：thinking_budget直接取固定值，low/mid/high对应服务端默认100/300/1000，可由HINDSIGHT_API_RECALL_BUDGET_FIXED_LOW/MID/HIGH调整。
• adaptive：thinking_budget = round(max_tokens × 比例)，检索广度随请求的输出 token 预算伸缩；比例默认0.025/0.075/0.25，受HINDSIGHT_API_RECALL_BUDGET_MIN/MAX（默认20/2000）钳制。
• low适合追求低延迟的轻量对话，high适合需要深度回忆上下文的关键任务，mid兼顾速度与效果。
• 相关服务端环境变量清单见 Configuration 文档。

保存后记忆如何运转：两个钩子与三个工具 ⚙️

保存配置后，Hindsight 通过 Hermes 原生的记忆提供方机制自动接入 Agent 生命周期。

两个钩子：自动回忆与自动留存

• pre_llm_call钩子（自动回忆）：每次 LLM 调用前查询 Hindsight，将相关记忆注入上下文。
• post_llm_call钩子（自动留存）：每次响应后将用户/助手对话存入 Hindsight。
• 自动回忆的力度，就是Recall budget决定的。

三个工具：供模型显式调用

• hindsight_retain：显式记忆写入。
• hindsight_recall：显式记忆检索。
• hindsight_reflect：记忆综合。

GUI 与 CLI 配置互通：环境变量优先

• 桌面端字段与 CLI 侧config.json配置项一一对应（mode、api_url、api_key、bank_id、recallBudget），可随时切换，记忆后端不变。
• CLI 场景（hermes memory setup向导或手写~/.hermes/hindsight/config.json）中，API Key 通过HINDSIGHT_API_KEY环境变量注入，其余设置落在配置文件，且环境变量优先级高于配置文件。Desktop 面板只是把这些操作封装成了图形界面。
• 若同时使用 Hermes 内置的MEMORY.md扁平文件记忆，为避免两个记忆源互相干扰，可执行hermes config set memory.memory_enabled false（可选再加memory.user_profile_enabled false）将其关闭。
• 偏好命令行或需要以 CLI / gateway（Telegram、Discord、Slack 等多平台网关）模式运行的用户，可参考 Hermes 集成文档，其中包含hermes memory setup向导、完整配置参考与故障排查指引。

三个常见问题：按这个顺序排查 🛠️

先确认服务可达

检查本地守护进程健康状态，一条 curl：

curl http://localhost:9077/health

查看守护进程日志

出现异常时，先看本地守护进程日志~/.hermes/logs/hindsight-embed.log。

遇到 404：多半是 Bank ID 的问题

如果 recall 报 404，通常是 Bank ID 拼错或被删除，而不是服务故障。核对面板里的Bank ID与 Hindsight 中实际存在的库是否一致，改回正确名称即可恢复。

快速回顾：打开Settings → Memory & Context，在 Memory Provider 中选择Hindsight；Cloud 模式粘贴 API Key，Local External 模式再把API URL指向自建实例，点击Save。之后 pre_llm_call 钩子在每次对话前自动回忆，post_llm_call 钩子在每次响应后自动留存，记忆按Bank ID对应的档案隔离存储。Hermes 就这样在纯图形界面里，装上了跨会话、跨设备的长期记忆。

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