Hermes 一键接入
更新日期:2026-10-22
接入组成
Hermes 接入同时安装两条互补路径:
| 能力 | 实现 |
|---|---|
| 每轮自动召回 | 原生 Python MemoryProvider 的 queue_prefetch/prefetch 生命周期 |
| 显式查询与诊断 | MCP Server + memhub-recall Skill |
| 会话写入 MemHub | Core 扫描 Hermes state.db / Session 文件 |
| 原生 Provider 自动写入 | 不启用,避免召回内容回流形成套娃 |
Python Provider 源码位于仓库
plugins/hermes/hy_memory,发行构建将其作为
Host Bridge 受管资源打包。
打开“一键接入”
用户点击接入即确认 MemHub 可以切换 Hermes 的唯一
memory.provider slot。安装事务:
- 创建 Hermes Installation、Credential 与 Recall Grant;
- 安装受管 Python Provider;
- 将
memory.provider设为hy_memory; - 写入 MCP Server 与
memhub-recallSkill; - 写安装 Journal,并执行连接 Probe。
~/.hermes/plugins/hy_memory/
__init__.py
plugin.yaml
provider.py
connection.json
~/.hermes/config.yaml
memory.provider: hy_memory
mcp_servers.one-memory: ...
~/.hermes/skills/memhub-recall/SKILL.md
~/.hermes/.one-memory/recall-install.json
<MemHub dataDir>/host-permissions/...
Hermes Credential、Installation、Grant
connection.json 只保存 Broker discovery 和 credential file 的路径,不保存
Core token 或 memory 内容。Provider 每次请求重新读取 discovery/credential,经
MemHub Broker /context 完成授权查询;不直连裸 Hy Memory HTTP server。
Hermes 必须完全退出并重新启动,原生 Provider 才会可靠生效。
自动 Recall 与 Session 去重
Hermes 在 turn N 结束后后台执行 queue_prefetch,turn N+1 开始时由
prefetch 消费已完成结果。前后 query 不要求完全相同;cache miss 不在当前轮次
重复发起第二次搜索。
Hermes 不会清除历史轮次中已注入的 memory。Provider 因此按 Hermes
session_id 保存已注入的 opaque memory_id 集合:
- 本 session 已出现的 ID 不再注入;
- 一次响应中的重复 ID 只保留首项;
- 相同正文、不同 ID 仍视为不同 memory;
- 切换 Session 使用各自的集合;
- reset / rewind 清理目标 Session 的集合;
- 搜索完成但没有实际注入的 ID 不进入集合。
集合以 session hash → opaque memory ID 的形式保存在
~/.hermes/.one-memory/hy-memory-seen.json,不保存 memory 正文,因此 Hermes
重启并恢复同一 Session 后仍可去重。
召回正文始终标记为不可信参考数据,不是指令。
注入块使用受控的 memhub_memory_context 边界,并对正文中的保留 tag 做转义;
即使宿主把注入内容写回历史,Source Adapter 也会在入库前剥离该块。
防止 memory 套娃
MemHub-managed Provider 是只读的:
- 自动 capture 关闭;
- 不暴露
hy_memory_add; - Hermes 会话写入继续由 MemHub Source Adapter 扫描完成;
- Adapter 排除 system 注入内容,Provider 也不会把 assistant 对召回内容的复述 作为另一条写入路径提交。
这样同一份 memory 不会因为被 prefetch 到 Hermes 后再次进入 memory 生成链路。
关闭与卸载
通过 MemHub 关闭接入时:
- 先撤销 Hermes Credential;
- 如果
memory.provider仍是 MemHub 安装的值,恢复接入前的 provider; - 如果 Provider 文件与安装 hash 一致,删除或恢复受管目录;
- 恢复/删除 MCP、Skill 和 Journal。
如果用户在安装后修改了 Provider 文件或配置,MemHub 停止自动清理并要求人工核对, 不会覆盖用户的新值。
用户直接从 /Applications 删除 MemHub 时,系统不保证有卸载回调,因此无法保证
恢复 Hermes 配置。遗留 Provider 会失败安全:Broker 不可用时只是不召回,不影响
Hermes 正常启动和对话。
同步开关
同步开关与一键接入相互独立:
- 打开:Core 校验
.hermesRoot,扫描历史和新增 Session,并调度 SDK 写入; - 关闭:停止发现和 claim 新 Job,已运行 Job 可以结束;
- 关闭同步不会卸载 Provider、MCP 或 Skill;
- 关闭一键接入不会删除已经进入 SDK 的 memory。
安全边界
- Provider 使用 host credential 和 Recall Grant,不持有 Core bearer。
- Broker 只接受 loopback、拒绝 proxy/redirect,并在释放结果前重新校验授权。
memory_id是去重身份,不是授权凭据。- 用户原文、memory 内容、token、路径和后端错误正文不写入诊断错误。
- Python Provider 不安装 SDK、不启动 sidecar、不直接操作 memory store。