From 46e9977ba8b8bda4667ad06e22a6aa89e5674535 Mon Sep 17 00:00:00 2001 From: YOMXXX Date: Thu, 11 Jun 2026 17:34:31 +0800 Subject: [PATCH] [good first issue] docs(hermes): document plugging memory-tencentdb into an existing Hermes (#139) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(hermes): document plugging memory-tencentdb into an existing Hermes The Hermes section in README.md / README_CN.md only documented the all-in-one Docker image, which is the wrong starting point when the user already has hermes-agent installed. They don't want to throw away their setup just to get memory; they want to drop the provider in next to the other built-in providers. The full reference already exists at `hermes-plugin/memory/memory_tencentdb/README.md` (auto-discovery paths, env vars, supervisor behaviour, troubleshooting). What's missing is the discoverable entry point at the top-level README. Restructure section 2 into two parallel paths: - 2.A Docker — the existing one-command flow, unchanged. - 2.B Plug into an existing Hermes (no Docker) — new. Covers: - installing the npm package so the Gateway source is on disk - symlink vs copy of the Python provider into `/plugins/memory/memory_tencentdb/` (with the "underscore not hyphen" trap called out) - the `memory.provider: memory_tencentdb` line in `~/.hermes/config.yaml` - the three `MEMORY_TENCENTDB_LLM_*` env vars - the three Gateway-start options (auto-discovery / explicit GATEWAY_CMD / run-yourself), with auto-discovery as default - a `curl /health` verification step - a link to the in-repo provider README for the full reference Docs-only — no code change. Existing Docker users see no difference. Fixes #69 Signed-off-by: 李冠辰 * docs(hermes): document tdai gateway config file * update README_CN.md file * Fix formatting in README_CN.md for clarity * Clarify Hermes plugin installation instructions Updated the README to clarify installation instructions for the Hermes plugin, including Docker usage and configuration steps. --------- Signed-off-by: 李冠辰 Co-authored-by: 十五便士 <95488710+Maxwell-Code07@users.noreply.github.com> --- README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++- README_CN.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 203 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5b412cd..df7f46d 100644 --- a/README.md +++ b/README.md @@ -193,9 +193,18 @@ bash scripts/openclaw-after-tool-call-messages.patch.sh > 💡 The patch only needs to be applied once per OpenClaw installation. After upgrading OpenClaw, re-run the script to re-apply. -### 2. Hermes (Docker, requires version ≥ 0.3.4) +### 2. Hermes -In addition to OpenClaw, this plugin also supports [Hermes](https://github.com/NousResearch/hermes-agent) Agent. You can launch a memory-enabled Hermes with a single command: +In addition to OpenClaw, this plugin also supports [Hermes](https://github.com/NousResearch/hermes-agent) Agent. Choose the installation path based on your deployment scenario: + +| You want to … | Use | +|---|---| +| Spin up a memory-enabled Hermes from scratch in one command | 2.A Docker (below) | +| Add memory to an existing Hermes install | 2.B Plug into an existing Hermes (next section) | + +#### 2.A Docker (greenfield, requires version ≥ 0.3.4) + +The Docker image bundles `hermes-agent` and the `memory_tencentdb` provider together. The Gateway listens on `:8420`: ```bash # ============ Configuration Parameters ============ @@ -244,6 +253,97 @@ docker exec -it hermes-memory hermes > The image ships with Tencent Cloud DeepSeek-V3.2 as the default. If you use this model, omit `MODEL_BASE_URL` / `MODEL_NAME` / `MODEL_PROVIDER` and pass only `MODEL_API_KEY`. +#### 2.B Attach to Existing Hermes (No Docker) + +If you already have `hermes-agent` installed on your host and just want to add memory capabilities, **no Docker image is needed**. + +**1. Download the plugin package to a unified directory**: + +```bash +mkdir -p ~/.memory-tencentdb +TEMP_DIR=$(mktemp -d) +cd "$TEMP_DIR" +npm init -y --silent +npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev +cp -r node_modules/@tencentdb-agent-memory/memory-tencentdb \ + ~/.memory-tencentdb/tdai-memory-openclaw-plugin +rm -rf "$TEMP_DIR" +``` + +**2. Install Gateway dependencies**: + +```bash +cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin +npm install --omit=dev +npm install tsx +``` + +**3. Link to the Hermes plugin directory**: + +```bash +rm -rf ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb +ln -sf ~/.memory-tencentdb/tdai-memory-openclaw-plugin/hermes-plugin/memory/memory_tencentdb \ + ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb +``` + +> The directory **must** be named `memory_tencentdb` (with an underscore) — Hermes uses this as the provider key. `memory-tencentdb` (with a hyphen) is only an alias at the config level and **cannot** be used as the directory name. + +**4. Declare the provider in `~/.hermes/config.yaml`**: + +```yaml +memory: + provider: memory_tencentdb +``` + +**5. Configure Gateway environment variables** + +Edit `~/.hermes/.env` and add: + +```bash +MEMORY_TENCENTDB_GATEWAY_CMD="sh -c 'cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin && exec npx tsx src/gateway/server.ts'" +MEMORY_TENCENTDB_GATEWAY_HOST="127.0.0.1" +MEMORY_TENCENTDB_GATEWAY_PORT="8420" +``` + +Add LLM credentials as needed (the Gateway actually reads the `TDAI_LLM_*` variables): + +```bash +TDAI_LLM_API_KEY="sk-your-api-key-here" +TDAI_LLM_BASE_URL="https://api.openai.com/v1" +TDAI_LLM_MODEL="gpt-4o" +``` + +Alternatively, use a Gateway config file at `~/.memory-tencentdb/memory-tdai/tdai-gateway.json`: + +```json +{ + "llm": { + "baseUrl": "https://your-api-endpoint/v1", + "apiKey": "your-api-key", + "model": "your-model-name" + } +} +``` + +**6. Start the Gateway** (choose one of two methods): + +- **Auto-discovery on conversation (recommended, zero-config)**: Don't start the Gateway manually — just start talking to Hermes. The provider will auto-detect `~/.memory-tencentdb/tdai-memory-openclaw-plugin/src/gateway/server.ts` and launch it via `Popen()` on the first conversation. The initial conversation may have a slight delay. +- **Manual run**: Start a standalone Gateway process in advance: + ```bash + cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin + npx tsx src/gateway/server.ts + ``` + +**7. Verify**: + +```bash +curl http://127.0.0.1:8420/health +# Should return {"status":"ok"} or {"status":"degraded"} +``` + +> For the complete provider reference (environment variables, troubleshooting, LLM tool schemas, supervisor behavior), see [`hermes-plugin/memory/memory_tencentdb/README.md`](./hermes-plugin/memory/memory_tencentdb/README.md). Please read it before adjusting the supervisor / circuit-breaker defaults. + + --- diff --git a/README_CN.md b/README_CN.md index 46cf341..130e203 100644 --- a/README_CN.md +++ b/README_CN.md @@ -198,9 +198,18 @@ bash scripts/openclaw-after-tool-call-messages.patch.sh > 💡 patch 每次 OpenClaw 安装只需执行一次。升级 OpenClaw 后建议重新执行以确保钩子生效。 -### 2. Hermes（Docker，需版本号 ≥ 0.3.4） +### 2. Hermes -除 OpenClaw 外，本插件同样支持 [Hermes](https://github.com/NousResearch/hermes-agent) Agent。通过一条命令即可启动一个带记忆能力的 Hermes： +除 OpenClaw 外，本插件同样支持 [Hermes](https://github.com/NousResearch/hermes-agent) Agent。根据部署场景选择安装路径： + +| 你的场景 | 走哪条路 | +|---|---| +| 想从零启动一个带记忆能力的 Hermes（一条命令搞定） | 2.A Docker（下文） | +| 已经装好了Hermes，只想加上记忆能力 | 2.B 挂到已有 Hermes 上（再下文） | + +#### 2.A Docker（全新部署，需版本号 ≥ 0.3.4） + +Docker 镜像把 `hermes-agent` 和 `memory_tencentdb` provider 聚合在一起，Gateway 监听 `:8420`： ```bash # ============ 配置参数说明 ============ @@ -249,6 +258,96 @@ docker exec -it hermes-memory hermes > 镜像内置了腾讯云 DeepSeek-V3.2 的默认值，如果你使用该模型，`MODEL_BASE_URL`/`MODEL_NAME`/`MODEL_PROVIDER` 可以省略，只传 `MODEL_API_KEY` 即可。 +#### 2.B 挂到已有 Hermes 上（无 Docker） + +如果宿主机上已经装好了 `hermes-agent`，只想加上记忆能力，**不需要** Docker 镜像。 + +**1. 下载插件包到统一目录**： + +```bash +mkdir -p ~/.memory-tencentdb +TEMP_DIR=$(mktemp -d) +cd "$TEMP_DIR" +npm init -y --silent +npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev +cp -r node_modules/@tencentdb-agent-memory/memory-tencentdb \ + ~/.memory-tencentdb/tdai-memory-openclaw-plugin +rm -rf "$TEMP_DIR" +``` + +**2. 安装 Gateway 依赖**： + +```bash +cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin +npm install --omit=dev +npm install tsx +``` + +**3. 链接到 Hermes 插件目录**： + +```bash +rm -rf ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb +ln -sf ~/.memory-tencentdb/tdai-memory-openclaw-plugin/hermes-plugin/memory/memory_tencentdb \ + ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb +``` + +> 此处目录名必须是 **`memory_tencentdb`**（下划线）—— Hermes 用它作为 provider key。`memory-tencentdb`（连字符）只是配置层面的别名，**不**能作为目录名。 + +**4. 在 `~/.hermes/config.yaml` 中声明 provider**： + +```yaml +memory: + provider: memory_tencentdb +``` + +**5. 配置 Gateway 环境变量** + +编辑 `~/.hermes/.env`，添加： + +```bash +MEMORY_TENCENTDB_GATEWAY_CMD="sh -c 'cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin && exec npx tsx src/gateway/server.ts'" +MEMORY_TENCENTDB_GATEWAY_HOST="127.0.0.1" +MEMORY_TENCENTDB_GATEWAY_PORT="8420" +``` + +LLM 凭证请按需添加（Gateway 实际读取的是 `TDAI_LLM_*` 系列变量）： + +```bash +TDAI_LLM_API_KEY="sk-your-api-key-here" +TDAI_LLM_BASE_URL="https://api.openai.com/v1" +TDAI_LLM_MODEL="gpt-4o" +``` + +也可改用 Gateway 配置文件 `~/.memory-tencentdb/memory-tdai/tdai-gateway.json`： + +```json +{ + "llm": { + "baseUrl": "https://your-api-endpoint/v1", + "apiKey": "your-api-key", + "model": "your-model-name" + } +} +``` + +**6. 启动 Gateway**（两种方式任选其一）： + +- **对话时自动发现（推荐，零配置）**：不启动 Gateway，直接开始和 Hermes 对话。provider 会在第一条对话时自动检测到 `~/.memory-tencentdb/tdai-memory-openclaw-plugin/src/gateway/server.ts` 并以 `Popen()` 拉起。首次对话会略有延迟。 +- **手动运行**：提前启动一个独立的 Gateway 进程： + ```bash + cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin + npx tsx src/gateway/server.ts + ``` + +**7. 验证**： + +```bash +curl http://127.0.0.1:8420/health +# 应返回 {"status":"ok"} 或 {"status":"degraded"} +``` + +> Provider 的完整参考（环境变量、故障排查、LLM 工具 schema、supervisor 行为）见 [`hermes-plugin/memory/memory_tencentdb/README.md`](./hermes-plugin/memory/memory_tencentdb/README.md)，调整 supervisor / circuit-breaker 默认值之前请先读它。 + ---