# Hermes

通过 PyPI 上的原生记忆插件连接 Hermes Agent，支持会话检查点、自动捕获和持久项目记忆。

- Canonical: https://docs.xmemo.dev/zh/docs/connect/hermes
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: bc9df4e1a62a317f42328c5fb35b354a1666ef85ea9f18ff6c96dbf5dccbdd9f
- Edition-Digest: 24fcf2223fe4ec7e21c1972e6bc10dd934ba524585e8b9f0dd821e940a1dd267
- Source-Revision: sha256:c1c2001f12dcea28dab430debe91620cc57ef3d7fced5162a27e2afa3fe87072

## 适用对象与具体接口

本指南将 Hermes Agent 连接到 XMemo 持久记忆。Hermes 通过 PyPI 上维护的原生记忆插件包 hermes-xmemo（版本 1.1.3）进行集成，代码锚定在活跃仓库 yonro/hermes-xmemo-plugin @ 30fe1bc20a (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md)。请注意，已归档仓库 yonro/xmemo-hermes-plugin @ eb47797a08 仅作为历史迁移参考；所有新安装均使用 hermes-xmemo。

## 前置条件

在连接之前，请确保以下运行时依赖和工具已准备就绪：

- Hermes Agent CLI 和运行时已安装 (Python 3.10+)。
- Python 包安装工具 (pip)。
- https://xmemo.dev 上的有效 XMemo 账户。
- 通过 HTTPS 访问 https://xmemo.dev/mcp 的网络连接。

## 安装

从官方 Hermes 插件市场安装 Hermes XMemo 提供方。如果您的 Hermes 版本未公开插件市场命令，请使用固定的 PyPI 回退方案。

```bash
hermes plugins install xmemo

# Fallback for older Hermes versions
pip install hermes-xmemo
hermes memory setup xmemo
```

## 授权与凭据配置

使用环境变量或 Hermes 配置设置身份验证。切勿将未加密的 bearer token 提交到版本控制中：

- 环境变量（推荐）：在启动 Hermes 的 shell 或环境中设置 XMEMO_KEY (export XMEMO_KEY='<your-xmemo-token>')。
- Hermes 设置向导：运行 hermes memory setup xmemo 会提示输入凭据并配置 ~/.hermes/config.yaml。
- 配置检查：确认 ~/.hermes/config.yaml 中 memory.provider 已设置为 xmemo。

## 加载与重启机制

守护进程重启或会话重新加载流程在 hermes-xmemo 插件 README (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md) 中未明确记载；请参考 Hermes Agent 宿主文档或重启您当前活跃的 Hermes 终端会话。

## 连接检查（只读）

在写入持久数据之前，使用只读 recall 请求验证连接性。此检查不会修改记忆状态：

- 检查：启动一个测试 Hermes 会话，并对现有项目上下文发起只读的主动召回查询。
- 成功信号：Hermes 返回带有来自已授权工作区的有效 Reference 和 Location 字段的结构化记忆结果。

## 首个实用任务：合成记忆生命周期

验证记忆持久性、无状态会话过渡、带溯源归属的召回及修正：

- 1. 保存合成事实：将项目规范 ("Hermes demo conventions: UTC logging with ISO 8601 timestamps.") 存储到 "projects/demo-hermes/conventions"。
- 2. 无状态过渡：结束当前的 Hermes 对话并启动新会话。
- 3. 带溯源归属的召回：查询 "demo conventions timestamp format"。确认返回的 Reference 和 Location。
- 4. 修正记忆：使用 update_memory 配合更新后的格式规则来更新所记住的规范。
- 5. 可选清理：在入职验证完成后，软删除 (forget) 该演示规范。

## 自动捕获与去重机制

Hermes Agent 提供跨执行边界的自动上下文捕获：

- 会话检查点：在 ~/.hermes/config.yaml 中启用时，Hermes 会在会话边界里程碑处捕获会话摘要和关键决策。
- 去重机制：内置的内容哈希去重可确保在迭代执行循环期间不会重复写入相同的事实和决策。
- 范围边界：捕获的每条记忆都严格隔离在已认证用户的工作区和活跃项目范围内。

## 提供方冲突与存储边界

理解运行时隔离与存储所有权：

- 提供方冲突：请勿在 ~/.hermes/config.yaml 中同时启用多个记忆提供方。运行重叠的提供方会导致脑裂召回。
- 存储所有权：所有持久记忆都保留在用户拥有的 XMemo 云端后端。Hermes 仅维护短暂的本地缓存以保证会话响应能力。
- 离线与重放限制：短暂的网络中断由受限的本地写入缓冲区处理；一旦达到缓冲区上限或令牌过期，离线写入将失败，且未提交的操作在重新连接前不会复制到其他智能体。

## 恢复、更新与卸载

Hermes 的故障排查、更新与卸载流程：

- 恢复 (401 invalid_token)：验证当前 shell 环境或 Hermes 配置中已设置 XMEMO_KEY。
- 更新：hermes-xmemo 插件 README (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md) 中未记载插件更新命令；请运行 pip install --upgrade hermes-xmemo 或查阅 Hermes 宿主文档。
- 卸载（README 第 292 行）：要在 Hermes 中禁用记忆提供方，请运行记载的卸载命令：hermes config set memory.provider ""。
- 卸载与远程删除：禁用本地提供方并不会删除已存储的远程记忆或撤销 API 凭据；请在 https://xmemo.dev/me 删除记忆或撤销密钥。

```bash
hermes config set memory.provider ""
```