From 28be408fb8bad89f69fa7af4bc31ecb846f9f38b Mon Sep 17 00:00:00 2001 From: chrishuan Date: Wed, 13 May 2026 02:14:54 +0800 Subject: [PATCH] docs: add Hermes quick start to README and Docker support --- README.md | 26 ++++++ README_CN.md | 26 ++++++ docker/opensource/Dockerfile.hermes | 106 ++++++++++++++++++++++ docker/opensource/README-hermes.md | 134 ++++++++++++++++++++++++++++ 4 files changed, 292 insertions(+) create mode 100644 docker/opensource/Dockerfile.hermes create mode 100644 docker/opensource/README-hermes.md diff --git a/README.md b/README.md index fc65fd0..1335b51 100644 --- a/README.md +++ b/README.md @@ -159,6 +159,32 @@ Once enabled, TencentDB Agent Memory automatically handles conversation capture, } ``` +### 5. Hermes Gateway Quick Start (Docker, requires version ≥ 0.3.0) + +In addition to OpenClaw, this plugin also supports the [Hermes](https://github.com/hermes-ai/hermes) Agent. Start a memory-enabled Hermes with a single command: + +```bash +docker run -d \ + --name hermes-memory \ + --restart unless-stopped \ + -p 8420:8420 \ + -e MODEL_API_KEY="your-api-key" \ + -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \ + -e MODEL_NAME="deepseek-v3.2" \ + -e MODEL_PROVIDER="custom" \ + -v hermes_data:/opt/data \ + agentmemory/hermes-memory:latest +``` + +The image supports `linux/amd64` and `linux/arm64`. It ships with Tencent Cloud DeepSeek-V3.2 defaults — to use a different model, pass `MODEL_BASE_URL`, `MODEL_NAME`, and `MODEL_PROVIDER` accordingly. + +Verify: + +```bash +curl http://localhost:8420/health # Check Gateway health +docker exec -it hermes-memory hermes # Enter Hermes conversation +``` + --- ## 🔧 Configurable Parameters diff --git a/README_CN.md b/README_CN.md index 917c80c..921c4d6 100644 --- a/README_CN.md +++ b/README_CN.md @@ -160,6 +160,32 @@ openclaw gateway restart } ``` +### 5. Hermes Gateway 快速启动（Docker，需版本号 ≥ 0.3.0） + +除 OpenClaw 外，本插件也支持 [Hermes](https://github.com/hermes-ai/hermes) Agent。一行命令即可启动带记忆能力的 Hermes： + +```bash +docker run -d \ + --name hermes-memory \ + --restart unless-stopped \ + -p 8420:8420 \ + -e MODEL_API_KEY="your-api-key" \ + -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \ + -e MODEL_NAME="deepseek-v3.2" \ + -e MODEL_PROVIDER="custom" \ + -v hermes_data:/opt/data \ + agentmemory/hermes-memory:latest +``` + +镜像支持 `linux/amd64` 和 `linux/arm64`。内置腾讯云 DeepSeek-V3.2 默认配置，如需自定义模型可额外传入 `MODEL_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`。 + +验证： + +```bash +curl http://localhost:8420/health # 检查 Gateway 状态 +docker exec -it hermes-memory hermes # 进入 Hermes 对话 +``` + --- ## 🔧 可调参数 diff --git a/docker/opensource/Dockerfile.hermes b/docker/opensource/Dockerfile.hermes new file mode 100644 index 0000000..c7e92e6 --- /dev/null +++ b/docker/opensource/Dockerfile.hermes @@ -0,0 +1,106 @@ +# TDAI Memory + Hermes Agent — All-in-One Open Source Image +# +# Based on install_hermes_ubuntu24.04_hongkong.sh installation logic. +# Pre-installs Hermes Agent + memory_tencentdb plugin + TDAI Memory Gateway. +# +# Build: docker build -f Dockerfile.hermes -t hermes-memory . +# Run: docker run -it -p 8420:8420 \ +# -e MODEL_API_KEY=xxx \ +# hermes-memory +# +# Hermes and TDAI share a single set of model config via MODEL_* env vars. + +FROM ubuntu:24.04 + +ENV DEBIAN_FRONTEND=noninteractive +ENV PYTHONUNBUFFERED=1 + +# ============================================================ +# System dependencies (mirrors install script) +# ============================================================ +RUN apt-get update && \ + apt-get install -y git curl ripgrep ffmpeg python3-pip python3-venv \ + build-essential python3-dev make g++ && \ + # Node.js 22 + curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \ + apt-get install -y nodejs && \ + rm -rf /var/lib/apt/lists/* + +# ============================================================ +# Install TDAI Memory Gateway (npm) +# ============================================================ +WORKDIR /opt/tdai-gateway + +RUN echo '{"name":"tdai-memory-standalone","version":"1.0.0","type":"module","private":true}' > package.json && \ + npm install @tencentdb-agent-memory/memory-tencentdb@latest tsx && \ + npm cache clean --force + +# ============================================================ +# Install Hermes Agent (official installer, skip browser) +# ============================================================ +ENV HERMES_SKIP_BROWSER_SETUP=1 + +RUN curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o /tmp/install-hermes.sh && \ + # Patch: skip browser setup + sed -i '/^install_node_deps() {/a\ if [ "${HERMES_SKIP_BROWSER_SETUP:-0}" = "1" ]; then echo "Skipping browser deps"; return 0; fi' /tmp/install-hermes.sh && \ + # Patch: shallow clone + sed -i 's/git clone --branch/git clone --depth 1 --branch/' /tmp/install-hermes.sh && \ + HOME=/root bash /tmp/install-hermes.sh --skip-setup && \ + rm -f /tmp/install-hermes.sh + +# Hermes data dir (user-independent) +ENV HERMES_HOME=/opt/data + +# Remove installer-generated config so HERMES_HOME takes sole precedence +RUN rm -f /root/.hermes/config.yaml /root/.hermes/.env + +# Link memory_tencentdb plugin into Hermes bundled plugin discovery path +# (plugins/memory/__init__.py scans /plugins/memory//) +RUN ln -sf /opt/tdai-gateway/node_modules/@tencentdb-agent-memory/memory-tencentdb/hermes-plugin/memory/memory_tencentdb \ + /usr/local/lib/hermes-agent/plugins/memory/memory_tencentdb + +# ============================================================ +# Configuration — Unified model config (shared by Hermes + TDAI) +# ============================================================ +RUN mkdir -p /opt/data/tdai-memory + +# -- Unified model config (users only need to set these) -- +# MODEL_API_KEY must be passed at runtime via -e (not baked into image) +ENV MODEL_NAME=deepseek-v3.2 +ENV MODEL_BASE_URL=https://api.lkeap.cloud.tencent.com/v1 +ENV MODEL_PROVIDER=custom + +# -- Gateway port -- +ENV TDAI_GATEWAY_PORT=8420 +ENV TDAI_GATEWAY_HOST=0.0.0.0 +ENV TDAI_DATA_DIR=/opt/data/tdai-memory + +# -- Plugin connection (Hermes -> Gateway) -- +ENV MEMORY_TENCENTDB_GATEWAY_HOST=127.0.0.1 +ENV MEMORY_TENCENTDB_GATEWAY_PORT=8420 + +HEALTHCHECK --interval=30s --timeout=5s --retries=3 \ + CMD curl -sf http://localhost:8420/health || exit 1 + +EXPOSE 8420 +VOLUME ["/opt/data"] + +# ============================================================ +# CMD: Sync MODEL_* -> generate configs -> start Gateway (foreground) +# Use: docker exec hermes-memory hermes (on-demand) +# ============================================================ +CMD ["bash", "-c", "\ + mkdir -p /opt/data/tdai-memory && \ + CFG=/opt/data/config.yaml && \ + ENVFILE=/opt/data/.env && \ + export TDAI_LLM_MODEL=\"${MODEL_NAME}\" && \ + export TDAI_LLM_BASE_URL=\"${MODEL_BASE_URL}\" && \ + export TDAI_LLM_API_KEY=\"${MODEL_API_KEY}\" && \ + printf \"model:\\n default: \\\"${MODEL_NAME}\\\"\\n provider: \\\"${MODEL_PROVIDER}\\\"\\n base_url: \\\"${MODEL_BASE_URL}\\\"\\n\\nmemory:\\n provider: memory_tencentdb\\n\" > \"$CFG\" && \ + printf \"OPENAI_API_KEY=${MODEL_API_KEY}\\n\" > \"$ENVFILE\" && \ + echo \"=== Config: model=${MODEL_NAME}, provider=${MODEL_PROVIDER}, url=${MODEL_BASE_URL} ===\" && \ + echo \"=== Gateway starting... ===\" && \ + echo \"=== Use: docker exec -it hermes to start a conversation ===\" && \ + exec node --import tsx/esm \ + /opt/tdai-gateway/node_modules/@tencentdb-agent-memory/memory-tencentdb/src/gateway/server.ts \ +"] diff --git a/docker/opensource/README-hermes.md b/docker/opensource/README-hermes.md new file mode 100644 index 0000000..e4686c2 --- /dev/null +++ b/docker/opensource/README-hermes.md @@ -0,0 +1,134 @@ +# Hermes + TDAI Memory — 一体化开源镜像 + +预装 Hermes Agent + TDAI Memory 插件，单容器同时运行两个服务。 +只需配置一个 API Key 即可启用 Hermes 对话 + 四层记忆系统。 + +## 架构 + +``` +┌──────────────────────────────────────────────────────┐ +│ 容器内部 │ +│ │ +│ ┌──────────────────────┐ ┌─────────────────────┐ │ +│ │ Hermes Agent │ │ TDAI Memory │ │ +│ │ (Python) │───▶│ Gateway (Node.js) │ │ +│ │ │HTTP│ :8420 │ │ +│ │ memory_tencentdb │ │ │ │ +│ │ plugin (内置) │ │ SQLite 本地存储 │ │ +│ └──────────────────────┘ └─────────────────────┘ │ +│ │ +│ 统一模型配置（Hermes + TDAI 共用一套 MODEL_* 变量） │ +└──────────────────────────────────────────────────────┘ +``` + +## 快速开始 + +```bash +# 构建（不依赖项目源码，任意目录均可） +docker build -f Dockerfile.hermes -t hermes-memory . + +# 运行（后台常驻，Gateway 自动启动） +docker run -d \ + --name hermes-memory \ + --restart unless-stopped \ + -p 8420:8420 \ + -e MODEL_API_KEY="your-api-key" \ + -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \ + -e MODEL_NAME="deepseek-v3.2" \ + -e MODEL_PROVIDER="custom" \ + -v hermes_data:/opt/data \ + hermes-memory + +# 验证 Gateway +curl http://localhost:8420/health + +# 进入 Hermes 对话 +docker exec -it hermes-memory hermes +``` + +> 镜像内置了腾讯云 DeepSeek-V3.2 的默认值，如果你使用该模型，`MODEL_BASE_URL`/`MODEL_NAME`/`MODEL_PROVIDER` 可以省略，只传 `MODEL_API_KEY` 即可。 + +## 工作原理 + +容器启动时（`CMD`）自动执行以下步骤： + +1. 将 `MODEL_*` 环境变量同步到 Gateway（`export TDAI_LLM_*`） +2. 生成 `/opt/data/config.yaml`（Hermes 配置，含模型参数和 `memory.provider: memory_tencentdb`） +3. 生成 `/opt/data/.env`（写入 `OPENAI_API_KEY`，供 Hermes 读取） +4. 前台启动 TDAI Memory Gateway（Node.js，监听 :8420，保持容器常驻） + +通过 `docker exec -it hermes-memory hermes` 进入对话时，Hermes 从 `$HERMES_HOME`（`/opt/data`）读取上述配置文件，自动连接已运行的 Gateway。memory_tencentdb 插件通过 HTTP 与本地 Gateway 通信，完成对话采集、记忆提取、场景构建和用户画像生成（L0→L1→L2→L3 四层 pipeline）。 + +## 环境变量 + +### 统一模型配置（Hermes + TDAI 共用） + +| 变量 | 默认值 | 说明 | +|------|--------|------| +| `MODEL_API_KEY` | - | LLM API Key（**必填，运行时通过 `-e` 传入**） | +| `MODEL_BASE_URL` | `https://api.lkeap.cloud.tencent.com/v1` | LLM API 地址 | +| `MODEL_NAME` | `deepseek-v3.2` | 模型名称 | +| `MODEL_PROVIDER` | `custom` | 模型 provider: custom/openrouter/anthropic/openai/gemini | + +用户只需配置上述 `MODEL_*` 变量，容器启动时自动同步到 Hermes（`config.yaml` + `.env`）和 Gateway（`TDAI_LLM_*` 环境变量）。 + +### 服务配置 + +| 变量 | 默认值 | 说明 | +|------|--------|------| +| `TDAI_GATEWAY_PORT` | `8420` | Gateway 端口 | +| `TDAI_GATEWAY_HOST` | `0.0.0.0` | Gateway 绑定地址 | +| `TDAI_DATA_DIR` | `/opt/data/tdai-memory` | 记忆数据目录 | +| `HERMES_HOME` | `/opt/data` | Hermes 数据目录 | + +## 数据持久化 + +所有数据存储在 `/opt/data` volume 中： + +``` +/opt/data/ +├── tdai-memory/ # TDAI 记忆数据 (SQLite + 场景文件) +│ ├── memories.sqlite # L0/L1 数据 +│ ├── scene_blocks/ # L2 场景文件 +│ ├── persona.md # L3 用户画像 +│ └── checkpoint.json # Pipeline 状态 +├── sessions/ # Hermes 会话记录 +├── skills/ # Hermes 技能 +├── config.yaml # Hermes 配置（启动时自动生成） +├── .env # 环境变量（启动时自动生成） +└── gateway.log # Gateway 日志 +``` + +## 故障排查 + +```bash +# 查看 Gateway 日志 +docker exec hermes-memory cat /opt/data/tdai-memory/gateway.log + +# 查看 Gateway 健康状态 +docker exec hermes-memory curl -s http://localhost:8420/health | python3 -m json.tool + +# 手动测试记忆召回 +docker exec hermes-memory curl -s -X POST http://localhost:8420/recall \ + -H "Content-Type: application/json" \ + -d '{"query":"test","session_key":"debug"}' + +# 查看生成的 Hermes 配置 +docker exec hermes-memory cat /opt/data/config.yaml + +# 查看环境变量同步结果 +docker exec hermes-memory env | grep -E '(MODEL_|TDAI_LLM_)' + +# 进入容器调试 +docker exec -it hermes-memory bash +``` + +## 构建说明 + +Dockerfile 不依赖本地源码 COPY，也不依赖 root 用户： + +- **TDAI Memory Gateway**：通过 `npm install @tencentdb-agent-memory/memory-tencentdb@latest` 从 npm registry 获取 +- **Hermes Agent**：通过官方安装脚本从 GitHub 获取，安装到 `/usr/local/lib/hermes-agent/` +- **memory_tencentdb 插件**：npm 包内已包含 `hermes-plugin/` 目录，构建时自动 symlink 到 Hermes 内置插件路径（`/usr/local/lib/hermes-agent/plugins/memory/`） + +容器内所有运行时路径均为绝对路径，不依赖 `$HOME` 或特定用户，可以非 root 用户运行。