diff --git a/integrations/hermes_agent/README.md b/integrations/hermes_agent/README.md index 619e8896..0e95a1ea 100644 --- a/integrations/hermes_agent/README.md +++ b/integrations/hermes_agent/README.md @@ -48,8 +48,9 @@ hermes plugins install agentscope-ai/ReMe/integrations/hermes_agent hermes memory setup ``` -For development from a local checkout, copy the integration into the active -Hermes profile and enable it: +For development from local ReMe and Hermes checkouts, either copy the integration +into the active profile or link it as a project-local plugin. The link keeps +Hermes on the exact ReMe source being edited: ```bash mkdir -p "$HERMES_HOME/plugins/reme" @@ -58,6 +59,17 @@ hermes plugins enable reme hermes config set memory.provider reme ``` +```bash +cd /path/to/hermes-agent +mkdir -p .hermes/plugins +ln -s /path/to/ReMe/integrations/hermes_agent .hermes/plugins/reme +export HERMES_ENABLE_PROJECT_PLUGINS=1 +hermes config set memory.provider reme +``` + +`.hermes/` is Hermes runtime state and is ignored by the Hermes repository. Do +not commit the link, profile configuration, conversations, or generated memory. + Verify discovery before starting a conversation: ```bash @@ -70,7 +82,7 @@ recall, health, write, and shutdown controls. Select **Plugins → Runtime provi plugins → Memory provider → reme**. The active mode controls whether the HTTP endpoint or embedded workspace settings are shown. -![ReMe selected as the active Hermes memory provider](figures/hermes-provider-settings.jpg) +![ReMe selected as the active Hermes memory provider](figures/hermes-provider-settings.png) Configuration is profile-local at: @@ -92,7 +104,7 @@ reme start \ workspace_dir="$HOME/.reme-hermes-default" \ service.backend=http \ service.host=127.0.0.1 \ - service.port=2333 + service.port=3456 ``` Use this configuration in Hermes: @@ -100,10 +112,13 @@ Use this configuration in Hermes: ```json { "mode": "http", - "endpoint": "http://127.0.0.1:2333" + "endpoint": "http://127.0.0.1:3456" } ``` +Port `3456` is used in this guide so the verification service does not collide +with another ReMe instance on the default `2333` port. It is not a new default. + The setup wizard checks `health_check` before replacing a valid configuration. The generic desktop settings endpoint validates field types and choices; a new Hermes session validates the URL and performs the live health check. ReMe's action HTTP service has no @@ -193,16 +208,71 @@ Run `hermes memory status` after installation, then start a new Hermes session. ## Verified end-to-end behavior -The screenshots below come from real Hermes 0.21.1 conversations using an -OpenAI-compatible model endpoint and ReMe 0.4.1.11. Each mode used an isolated -temporary Hermes profile and ReMe workspace. The first session recorded a -synthetic fact through `auto_memory`; a fresh session then recovered it through -automatic `prefetch`. No API keys or personal memories appear in the images. +The screenshots below were captured with Computer Use from real English Hermes +0.21.1 and ReMe Studio 0.4.1.11 interfaces. The conversations used an +OpenAI-compatible model endpoint. Each mode used an isolated temporary Hermes +profile and ReMe workspace. The first session recorded a synthetic fact through +`auto_memory`; a fresh session then recovered it through automatic `prefetch`. +No API keys, `.env` contents, browser chrome, or personal memories appear in the +images. + +### Reproduce the verification + +Run the focused compatibility suite against the Hermes checkout, then validate +the plugin through Hermes' real loader: + +```bash +cd /path/to/ReMe +PYTHONPATH=/path/to/hermes-agent \ + pytest tests/unit/test_hermes_agent_integration.py -v + +cd /path/to/hermes-agent +hermes plugins doctor /path/to/ReMe/integrations/hermes_agent --ci +hermes memory status +``` + +For a live model test, start ReMe on `3456`, select that endpoint in the ReMe +provider settings, and use two new Hermes sessions: the first asks Hermes to +remember a synthetic fact and the second asks for it back. When an existing +ReMe `.env` uses `LLM_*` names, map them only in the process environment used +for verification: + +```bash +set -a +source /path/to/ReMe/.env +set +a +export OPENAI_API_KEY="$LLM_API_KEY" +export OPENAI_BASE_URL="$LLM_BASE_URL" + +hermes --provider openai-api -m "$LLM_MODEL_NAME" -z \ + "Remember this synthetic fact for a later session: Project Juniper's weekly review is Thursday at 14:30 UTC." +hermes --provider openai-api -m "$LLM_MODEL_NAME" -z \ + "From long-term memory, when is Project Juniper's weekly review?" + +unset OPENAI_API_KEY OPENAI_BASE_URL +``` + +The second command must run without `--resume`. Confirm that a new Markdown +note exists under the selected ReMe workspace's `daily/` directory; do not use +the ReMe repository's `.reme/` directory for this check. Never print the loaded +variables or save the mapped credentials in Hermes configuration. + +### Provider configuration + +![ReMe selected as the active HTTP memory provider on port 3456](figures/hermes-provider-settings.png) + +### Two independent Hermes sessions + +![The write session and fresh recall session in the Hermes session overview](figures/hermes-http-sessions.png) ### HTTP mode recall ![A fresh Hermes session recalls the HTTP-mode verification fact from ReMe](figures/hermes-http-recall.png) +### File-native durable result + +![The generated Project Juniper Markdown in the English ReMe Studio interface](figures/hermes-reme-daily-note.png) + ### Embedded mode recall ![A fresh Hermes session recalls the embedded-mode verification fact from ReMe](figures/hermes-embedded-recall.png) @@ -222,7 +292,7 @@ hermes memory status ### HTTP mode is unavailable - Confirm `reme start` is still running and its port matches `endpoint`. -- Call the local `health_check` action and inspect ReMe service logs. +- Call `POST http://127.0.0.1:3456/health_check` and inspect ReMe service logs. - In containers or on another host, remember that `127.0.0.1` refers to the Hermes machine; use a trusted tunnel or authenticated proxy. diff --git a/integrations/hermes_agent/README_ZH.md b/integrations/hermes_agent/README_ZH.md index bfd91755..7a8c5303 100644 --- a/integrations/hermes_agent/README_ZH.md +++ b/integrations/hermes_agent/README_ZH.md @@ -39,7 +39,8 @@ hermes plugins install agentscope-ai/ReMe/integrations/hermes_agent hermes memory setup ``` -本地开发时可以直接复制当前 checkout: +本地同时开发 ReMe 和 Hermes 时,可以复制当前 checkout,也可以把它链接为 project-local plugin。软链接会让 Hermes 始终 +运行当前正在编辑的 ReMe 源码: ```bash mkdir -p "$HERMES_HOME/plugins/reme" @@ -48,6 +49,16 @@ hermes plugins enable reme hermes config set memory.provider reme ``` +```bash +cd /path/to/hermes-agent +mkdir -p .hermes/plugins +ln -s /path/to/ReMe/integrations/hermes_agent .hermes/plugins/reme +export HERMES_ENABLE_PROJECT_PLUGINS=1 +hermes config set memory.provider reme +``` + +Hermes 仓库会忽略 `.hermes/` 运行状态。不要提交这个链接、profile 配置、对话记录或生成的记忆文件。 + 启动对话前检查真实发现路径: ```bash @@ -58,7 +69,7 @@ hermes memory status Hermes Dashboard 的 **Plugins → Runtime provider plugins → Memory provider → reme** 会展示模式相关字段以及召回、健康、 写入和关闭的高级设置。选择不同模式时,只显示 HTTP endpoint 或 Embedded workspace 对应字段。 -![Hermes 中处于 ready 和 active 状态的 ReMe provider](figures/hermes-provider-settings.jpg) +![Hermes 中处于 ready 和 active 状态的 ReMe provider](figures/hermes-provider-settings.png) 配置主路径为 `$HERMES_HOME/reme/config.json`。新文件未包含的字段仍会从旧 `$HERMES_HOME/reme.json` 继承,新文件中的 值优先;后续 CLI 保存会写入完整的新配置,但不会删除旧文件。 @@ -72,7 +83,7 @@ reme start \ workspace_dir="/absolute/path/to/reme-hermes-default" \ service.backend=http \ service.host=127.0.0.1 \ - service.port=2333 + service.port=3456 ``` 配置示例: @@ -80,10 +91,12 @@ reme start \ ```json { "mode": "http", - "endpoint": "http://127.0.0.1:2333" + "endpoint": "http://127.0.0.1:3456" } ``` +本文使用 `3456` 做联调端口,以免与默认 `2333` 上的其他 ReMe 实例冲突;这不是修改 ReMe 默认端口。 + 终端 setup 会在保存前调用 `health_check`。HTTP action 接口没有本集成专用的认证头,不要直接暴露到公网;跨主机使用时 应放在可信网络、SSH tunnel 或带认证的反向代理后。 @@ -159,14 +172,62 @@ ReMe 搜索覆盖整个 workspace。多个 Hermes profile 指向同一个 worksp ## 真实端到端验证 -以下截图来自 Hermes 0.21.1、ReMe 0.4.1.11 和 OpenAI-compatible 模型接口的真实联调。HTTP 与 Embedded 分别使用隔离的 -临时 Hermes profile 和 ReMe workspace:第一个会话通过 `auto_memory` 写入合成事实,第二个全新会话通过自动 -`prefetch` 召回。图片不包含 API Key 或真实个人记忆。 +以下截图使用 Computer Use 从真实英文 Hermes 0.21.1 与 ReMe Studio 0.4.1.11 界面取得,模型通过 +OpenAI-compatible 接口调用。HTTP 与 Embedded 分别使用隔离的临时 Hermes profile 和 ReMe workspace:第一个会话通过 +`auto_memory` 写入合成事实,第二个全新会话通过自动 `prefetch` 召回。图片不包含 API Key、`.env` 内容、浏览器外框或 +真实个人记忆。 + +### 复现验证 + +先让聚焦单测使用真实 Hermes 源码,再通过 Hermes 自身的 loader 验证插件发现和注册: + +```bash +cd /path/to/ReMe +PYTHONPATH=/path/to/hermes-agent \ + pytest tests/unit/test_hermes_agent_integration.py -v + +cd /path/to/hermes-agent +hermes plugins doctor /path/to/ReMe/integrations/hermes_agent --ci +hermes memory status +``` + +真实模型验证时,在 `3456` 启动 ReMe,把 provider endpoint 指向该服务,并使用两个全新的 Hermes 会话:第一个会话要求 +记住一条虚构事实,第二个会话要求重新回答。如果现有 ReMe `.env` 使用 `LLM_*` 变量,只在验证进程环境中映射它们: + +```bash +set -a +source /path/to/ReMe/.env +set +a +export OPENAI_API_KEY="$LLM_API_KEY" +export OPENAI_BASE_URL="$LLM_BASE_URL" + +hermes --provider openai-api -m "$LLM_MODEL_NAME" -z \ + "Remember this synthetic fact for a later session: Project Juniper's weekly review is Thursday at 14:30 UTC." +hermes --provider openai-api -m "$LLM_MODEL_NAME" -z \ + "From long-term memory, when is Project Juniper's weekly review?" + +unset OPENAI_API_KEY OPENAI_BASE_URL +``` + +第二条命令不要使用 `--resume`。随后确认所选 ReMe workspace 的 `daily/` 下出现新的 Markdown;不要把 ReMe 仓库自身的 +`.reme/` 用作测试 workspace。不要打印这些变量,也不要把映射后的凭据保存到 Hermes 配置。 + +### Provider 配置 + +![Hermes 中使用 3456 端口的 ReMe HTTP provider](figures/hermes-provider-settings.png) + +### 两个相互独立的 Hermes 会话 + +![Hermes 会话总览中的写入会话和全新召回会话](figures/hermes-http-sessions.png) ### HTTP 模式召回 ![Hermes 新会话从 ReMe 召回 HTTP 模式验证事实](figures/hermes-http-recall.png) +### 文件原生的持久化结果 + +![英文 ReMe Studio 中生成的 Project Juniper Markdown](figures/hermes-reme-daily-note.png) + ### Embedded 模式召回 ![Hermes 新会话从 ReMe 召回 Embedded 模式验证事实](figures/hermes-embedded-recall.png) @@ -185,7 +246,7 @@ hermes config set memory.provider reme ### HTTP 模式显示 backend unavailable - 确认 `reme start` 仍在运行,端口与 `endpoint` 一致; -- 直接执行 `curl -s http://127.0.0.1:2333/health_check -X POST -H 'Content-Type: application/json' -d '{}'`; +- 直接执行 `curl -s http://127.0.0.1:3456/health_check -X POST -H 'Content-Type: application/json' -d '{}'`; - 容器或跨机器部署时,`127.0.0.1` 指向各自本机; - 不要把无认证的 ReMe HTTP action 服务直接暴露到公网。 diff --git a/integrations/hermes_agent/figures/hermes-http-recall.png b/integrations/hermes_agent/figures/hermes-http-recall.png index 2a86a2d4..69b29ef1 100644 Binary files a/integrations/hermes_agent/figures/hermes-http-recall.png and b/integrations/hermes_agent/figures/hermes-http-recall.png differ diff --git a/integrations/hermes_agent/figures/hermes-http-sessions.png b/integrations/hermes_agent/figures/hermes-http-sessions.png new file mode 100644 index 00000000..ce79c592 Binary files /dev/null and b/integrations/hermes_agent/figures/hermes-http-sessions.png differ diff --git a/integrations/hermes_agent/figures/hermes-provider-settings.jpg b/integrations/hermes_agent/figures/hermes-provider-settings.jpg deleted file mode 100644 index f6163f7a..00000000 Binary files a/integrations/hermes_agent/figures/hermes-provider-settings.jpg and /dev/null differ diff --git a/integrations/hermes_agent/figures/hermes-provider-settings.png b/integrations/hermes_agent/figures/hermes-provider-settings.png new file mode 100644 index 00000000..8c0ab24f Binary files /dev/null and b/integrations/hermes_agent/figures/hermes-provider-settings.png differ diff --git a/integrations/hermes_agent/figures/hermes-reme-daily-note.png b/integrations/hermes_agent/figures/hermes-reme-daily-note.png new file mode 100644 index 00000000..67736409 Binary files /dev/null and b/integrations/hermes_agent/figures/hermes-reme-daily-note.png differ