实测记录

Hermes 接入 TencentDB-Agent-Memory：本地 Gateway 安装与验收记录

✍️ lvy · 📅 2026-08-27 · ⏱ 12 分钟 · 📂 实测记录

Hermes 接入 TencentDB-Agent-Memory：本地 Gateway 安装与验收记录

本文记录本站在 2026 年 8 月 27 日完成的一次实际安装验收。它不是性能评测，也不代表腾讯云官方推荐配置；重点是说明如何把 TencentDB-Agent-Memory 的 Hermes Provider 接入本地 Hermes，并用健康检查和 Provider 调用确认链路可用。

适用场景

如果希望 Hermes 具备 L0 对话记录、L1 原子记忆、L2 场景记忆和 L3 用户画像，可以让 Hermes 使用 TencentDB-Agent-Memory 提供的 Python Provider，再由本地 Node.js Gateway 负责存储和记忆处理。

本文采用单机方案：Gateway 只监听 127.0.0.1，数据保存在本地 SQLite，不使用腾讯云向量数据库。这样适合个人服务器或开发环境，不需要额外部署 Redis、向量数据库或公网服务。

验证环境

本站验收时使用了以下环境：

版本会随项目更新变化。正式部署前，应重新执行 node --version、npm --version，并阅读项目仓库的最新安装说明。

安装 Gateway

将项目放到独立目录后，进入 MemoryCore 安装依赖：

mkdir -p ~/.memory-tencentdb
git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git \
  ~/.memory-tencentdb/TencentDB-Agent-Memory
cd ~/.memory-tencentdb/TencentDB-Agent-Memory/MemoryCore
npm install --omit=dev

Gateway 启动需要 tsx。项目依赖安装完成后，可以用 pnpm 执行 TypeScript 入口：

pnpm exec tsx src/gateway/server.ts

不要把 API Key 写进 Git 仓库、文章、截图或 systemd unit 文件。建议通过 Hermes 的环境文件或 Secret Manager 注入。

Hermes Provider 配置

Provider 源码位于项目的：

MemoryCore/hermes-plugin/memory/memory_tencentdb/

Hermes 发现 Provider 时要求目录名为 memory_tencentdb，不能改成带连字符的目录名。源码安装时可以建立链接：

ln -sfn \
  ~/.memory-tencentdb/TencentDB-Agent-Memory/MemoryCore/hermes-plugin/memory/memory_tencentdb \
  ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb

然后在 ~/.hermes/config.yaml 中启用：

memory:
  provider: memory_tencentdb

配置 Gateway 的基本环境变量示例：

MEMORY_TENCENTDB_GATEWAY_HOST=127.0.0.1
MEMORY_TENCENTDB_GATEWAY_PORT=8420
MEMORY_TENCENTDB_LLM_BASE_URL=https://openrouter.ai/api/v1
MEMORY_TENCENTDB_LLM_MODEL=你的模型名
TDAI_LLM_BASE_URL=https://openrouter.ai/api/v1
TDAI_LLM_MODEL=你的模型名
TDAI_GATEWAY_CONFIG=/绝对路径/tdai-gateway.standalone.yaml
TDAI_DATA_DIR=~/.memory-tencentdb/memory-tdai

MEMORY_TENCENTDB_LLM_API_KEY 和 TDAI_LLM_API_KEY 只应在运行环境中设置，示例中的“你的模型名”也不应替换成包含凭据的字符串。

验收步骤

1. 检查 Provider 是否被发现

cd ~/.hermes/hermes-agent
python3 - <<'PY'
from plugins.memory import discover_memory_providers
for name, _, available in discover_memory_providers():
    if name == "memory_tencentdb":
        print(name, available)
PY

应看到 memory_tencentdb。如果没有，优先检查链接目标、__init__.py 和 plugin.yaml 是否直接位于 memory_tencentdb/ 内。

2. 检查 Hermes 状态

hermes memory status

本站实际验收时显示：

Provider:  memory_tencentdb
Plugin:    installed ✓
Status:    available ✓

3. 检查 Gateway 健康状态

curl -fsS http://127.0.0.1:8420/health

本站实际收到 HTTP 200，核心结果包括：

{
  "status": "ok",
  "stores": {
    "vectorStore": true,
    "embeddingService": false
  },
  "services": {
    "stateBackend": "connected"
  }
}

这里的 embeddingService: false 并不表示 Gateway 不可用；本次配置明确关闭了远程 Embedding，使用本地 SQLite 和 BM25 召回。若启用向量搜索，需要另行配置 Embedding Provider。

4. 验证 Provider 调用

在 Hermes Python 环境中初始化 Provider，并执行一次召回：

from plugins.memory.memory_tencentdb import MemoryTencentdbProvider

provider = MemoryTencentdbProvider()
provider.initialize("verification-session")
print(provider.prefetch("安装验证"))
provider.shutdown()

本站验收确认 Provider 可以完成初始化、连接 Gateway 并发起召回请求。首次自动拉起 Gateway 时可能需要等待 TypeScript 运行时初始化，不能只在启动后立即用一次失败的 curl 判断安装失败；应在日志出现 Gateway listening 后再次检查健康接口。

常见问题

Status: not available

如果 hermes memory status 显示缺少 Gateway 地址，检查是否在 Hermes 实际继承的环境中设置了：

MEMORY_TENCENTDB_GATEWAY_HOST=127.0.0.1
MEMORY_TENCENTDB_GATEWAY_PORT=8420

仅设置 Gateway 的 TDAI_* 变量，不一定能让 Hermes Provider 的状态检查识别到地址。

Gateway 启动但端口暂时不可用

检查：

ps aux | grep '[t]sx src/gateway/server.ts'
tail -100 ~/.hermes/logs/memory_tencentdb/gateway.stderr.log

首次 pnpm exec tsx 可能需要几秒钟。重点观察最终是否出现 Gateway listening on http://127.0.0.1:8420，以及是否存在真正的异常堆栈。

是否必须使用腾讯云 VectorDB

不必须。Standalone 配置默认使用本地 SQLite，适合单机验证。只有在需要更大规模数据、远程存储或特定向量检索能力时，才应评估 TCVDB 配置和成本。

能否把 Gateway 暴露到公网

不建议直接暴露。若确实需要跨机器访问，应同时设置明确的监听地址、强随机 API Key、防火墙白名单和 HTTPS 反向代理。个人单机方案应继续使用 127.0.0.1，避免记忆数据接口被未授权访问。

结论与边界

本次验证证明了 Hermes Provider、Node Gateway、SQLite 存储和健康检查之间的集成链路可用，但不等于完成了性能压测、长时间稳定性测试或多租户隔离评测。生产使用前还应补充：定期备份数据目录、限制 Gateway 权限、监控 Gateway 日志、验证 LLM 额度和超时策略，并在升级项目版本前执行数据备份和回滚演练。

#Hermes#TencentDB-Agent-Memory#Memory#Gateway#SQLite#实测

相关阅读