[good first issue] docs(hermes): document plugging memory-tencentdb into an existing Hermes (#139)

* 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
    `<hermes-agent-checkout>/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: 李冠辰 <liguanchen@xiaomi.com>

* 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: 李冠辰 <liguanchen@xiaomi.com>
Co-authored-by: 十五便士 <95488710+Maxwell-Code07@users.noreply.github.com>

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.
+
+
 ---
 
 

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 默认值之前请先读它。
+
 
 ---