企业官网建设流程全解析

Hermes 接入 memory-tencentdb 四层记忆系统：MemoryProvider 适配器与 Node.js Gateway Sidecar 全解析

【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory

导读

本文以 TencentDB-Agent-Memory 仓库中 Hermes 侧记忆插件（MemoryCore/hermes-plugin/memory/memory_tencentdb/）的官方 README 为骨架，完整讲解如何将开源 Hermes Agent 的生命周期事件（prefetch、sync_turn、session 结束）接入 memory-tencentdb 四层记忆系统（L0 对话捕获 → L1 情节抽取 → L2 场景块 → L3 人格合成）。读完本文，你将掌握：该 Provider 与 Gateway sidecar 的架构分工、三种 Gateway 启动方式、全部MEMORY_TENCENTDB_*环境变量语义、两个 LLM 搜索工具的调用契约，以及基于源码级证据的排障方法论。

一、定位：一个"薄 HTTP 客户端 + 进程管家"的 MemoryProvider

memory-tencentdb 是一个面向 AI Agent 的团队级记忆中枢，其记忆流水线分为四层：L0 原始对话、L1 结构化情节记忆、L2 Markdown 场景块、L3 用户人格画像。而本目录中的 Python 模块（hermes-plugin/memory/memory_tencentdb/）不是记忆引擎本身——真正承担捕获、抽取、存储、召回与流水线调度的，是与 OpenClaw 插件同包发布的 Node.js Gateway sidecar。这个 Python Provider 只做两件事：

1. 作为 Hermes 侧MemoryProvider的 HTTP 客户端（对应 client.py 中的MemoryTencentdbSdkClient）；
2. 作为 Gateway 子进程的监督者（对应 supervisor.py 中的GatewaySupervisor），负责启动、健康检查、崩溃诊断与关停。

两层职责的边界在init.py 的模块 docstring 中被明确强调：磁盘上的 L0~L3 数据目录归 Gateway 所有，而非本 Provider。数据目录的唯一事实来源是 Gateway 侧的TDAI_DATA_DIR（在 src/gateway/config.ts 中解析），这样 Provider 与 Gateway 永远不会对"记忆存在哪里"产生分歧。

1.1 架构总览

官方 README 给出了如下架构图（本仓库未附带与本文主题强相关的架构图片，故以文字复现）：

Hermes Agent (Python) └─ MemoryManager └─ MemoryTencentdbProvider (本目录) ├─ GatewaySupervisor — 启动 / 健康检查 sidecar └─ MemoryTencentdbSdkClient — POST /recall, /capture, /search/*, /session/end │ ▼ HTTP (默认 127.0.0.1:8420) memory-tencentdb Gateway (Node.js) └─ memory-tencentdb Core ├─ L0 Conversation store (SQLite / TCVDB + JSONL) ├─ L1 Episodic extraction (LLM + vector dedup) ├─ L2 Scene blocks (Markdown under data dir) ├─ L3 Persona synthesis (persona.md) └─ Storage backends: SQLite + sqlite-vec OR Tencent VectorDB

从init.py 的源码看，该 Provider 已经完成 v3 迁移：数据面调用统一走/v3/*端点，并携带team_id / agent_id / user_id三组租户隔离标识（默认值均为"default"，见_DEFAULT_TEAM_ID/_DEFAULT_AGENT_ID/_DEFAULT_USER_ID）。这与 Gateway 侧 v2-router.ts 中/v3白名单V3_ALLOWED_SUBPATHS（含/conversation/add、/atomic/search、/scenario/ls、/scenario/read、/core/read等）一一对应。

1.2 Hermes 生命周期 → Gateway 端点映射

README 给出的映射表是理解本 Provider 的关键：

需要补充的是，v3 迁移后部分映射已发生语义变化：prefetch()实际并发执行三条/v3数据面调用（L1atomic/search+ L3core/read+ L2scenario/ls），sync_turn()改为POST /v3/conversation/add（消息带 ISO 8601 时间戳），而on_session_end()与end_session()已成为显式 no-op——v3 流水线通过定时扫描（Timer Scanner）自动处理会话收尾。源码中保留了 v1 的/recall、/capture、/search/memories、/search/conversations方法并标注[DEPRECATED]，仅作向后兼容。

二、可靠性设计：三道内置防线

README 明确列出了 Provider 内置的三项可靠性机制，以下结合源码逐一深化：

2.1 熔断器（Circuit Breaker）

连续 5 次 Gateway 失败后暂停所有调用 60 秒。实现位于init.py 的_BREAKER_THRESHOLD = 5与_BREAKER_COOLDOWN_SECS = 60：_record_failure()累计失败次数，达到阈值即设置_breaker_open_until；_is_breaker_open()在熔断窗口内直接短路请求，超时后自动清零重试。

2.2 捕获背压（Back-pressure on capture）

sync_turn最多允许 4 个在途线程（_MAX_INFLIGHT_SYNCS = 4）；第 5 个到来时，会先 join 最老线程最多 5 秒（_SYNC_JOIN_TIMEOUT_SECS = 5.0）再启动新线程，避免 Gateway 挂起导致线程无限增长。若最老线程 5 秒后仍存活，会输出sync backlog警告并继续推进。

2.3 受监督启动（Supervised startup）

• 若设置了MEMORY_TENCENTDB_GATEWAY_CMD，或自动发现到src/gateway/server.ts，Provider 会以Popen()拉起 sidecar；
• 以 0.5 秒间隔轮询GET /health，最长等待 30 秒（HEALTH_CHECK_MAX_WAIT = 30，见 supervisor.py）；
• 崩溃时自动 tail 最近 2048 字节的gateway.stderr.log（LOG_TAIL_BYTES_ON_CRASH）用于诊断。

源码还展示了 README 之外的细节：

• 进程组回收：子进程以start_new_session=True启动，关停时os.killpg(SIGTERM)终止整个进程组，避免pnpm → tsx → node server.ts链路中顶层包装进程退出后真实监听进程变成孤儿；10 秒未退出再升级为 SIGKILL；
• 日志重定向而非 PIPE：子进程 stdout/stderr 直接写入日志文件（追加模式），避免 pipe 缓冲（约 64KB）填满后 Gateway 事件循环阻塞；
• 单飞锁（single-flight）：_startup_singleflight用进程内threading.Lock+ 可选的fcntl跨进程文件锁（锁文件位于系统临时目录memory-tencentdb-gateway-<host>-<port>.lock），保证同一 host:port 不会并发拉起两个 Gateway；
• 僵尸句柄回收：_reap_dead_process()在崩溃后重拉前清理陈旧Popen句柄，避免 watchdog 被死进程误导。

2.4 自愈闭环：watchdog + 复活冷却

init.py 中还有 README 未展开的第三道防线：一个每 10 秒运行一次的守护 watchdog 线程（_WATCHDOG_INTERVAL_SECS = 10.0），当 Gateway 不可达时调用_try_recover_gateway()重新探测并拉起；恢复尝试有 15 秒冷却（_RECOVER_COOLDOWN_SECS），该值刻意小于熔断冷却（60 秒）、大于健康检查最长等待（30 秒）——既能"在熔断窗口内尝试复活 Gateway"，又保证两次复活尝试不重叠。is_process_alive()（检查 Popen 句柄）与is_running()（网络健康检查）组合判断，让 watchdog 无需每次 tick 都付出 HTTP 往返成本。

三、安装位置：Hermes 的 Provider 发现机制

本目录不是Hermes 实际加载 Provider 的地方，它只是源码事实来源（source of truth）。Hermes 启动时按优先级扫描两个位置（见 README 引用的hermes-agent/plugins/memory/__init__.py）：

1. Bundled（内置）：<hermes-agent-checkout>/plugins/memory/<name>/——memory_tencentdb随 hermes-agent 发行于此，与byterover/、honcho/、mem0/、hindsight/等内置 Provider 并列；同名冲突时内置优先。
2. User-installed（用户安装）：$HERMES_HOME/plugins/<name>/，其中$HERMES_HOME默认为~/.hermes（见hermes_constants.get_hermes_home()）。第三方 Provider 走此路径，memory_tencentdb 不使用。

关键约束：目录名必须是memory_tencentdb（下划线）。Hermes 用目录名作为 Provider key，必须与 plugin.yaml 的name及config.yaml中memory.provider的值保持一致；连字符形式memory-tencentdb仅是配置侧别名，不是合法的目录名。

README 提供两种安装风格，并给出验证命令：

Install A —— 符号链接（推荐给同时开发两个仓库的开发者）：保持本仓库为唯一事实来源，git pull后 Hermes 立即可见。

# 在 tdai-memory-openclaw-plugin checkout 下执行： ln -s "$(pwd)/hermes-plugin/memory/memory_tencentdb" \ <hermes-agent-checkout>/plugins/memory/memory_tencentdb

Install B —— 拷贝（随 hermes-agent 一起分发）：冻结特定版本到 hermes-agent 树内；当前仓库对中两份拷贝（hermes-plugin/memory/memory_tencentdb/与hermes-agent/plugins/memory/memory_tencentdb/）需手动保持同步。

cp -r tdai-memory-openclaw-plugin/hermes-plugin/memory/memory_tencentdb \ hermes-agent/plugins/memory/memory_tencentdb

验证 Hermes 能发现 Provider：

$ cd <hermes-agent-checkout> $ python -c 'from plugins.memory import discover_memory_providers; \ [print(n, a) for n, _, a in discover_memory_providers()]' memory_tencentdb True ...

若未出现，依次排查：目标路径是否为hermes-agent/plugins/memory/memory_tencentdb/（下划线）；__init__.py与plugin.yaml是否直接位于该目录内；发现扫描要求__init__.py内含字面量MemoryProvider或register_memory_provider（本 Provider 两者皆备，init.py 末尾的register()即注册入口）。

注意：Gateway 源码（src/gateway/下的 Node.js sidecar）保留在 tdai-memory-openclaw-plugin checkout 中，不需要拷入 hermes-agent——Python Provider 会通过下述 Option A 的路径列表或MEMORY_TENCENTDB_GATEWAY_CMD自动发现它。

四、Setup：三步接入

4.1 在 Hermes 中激活（~/.hermes/config.yaml）

memory: provider: memory_tencentdb # canonical name # 向后兼容的别名：`memory-tencentdb`、`tdai`

4.2 提供 Gateway 运行时与 LLM 凭据

Gateway 至少需要一个 OpenAI 兼容端点来驱动 L1/L2/L3 抽取。在 Hermes 进程环境中设置：

export MEMORY_TENCENTDB_LLM_API_KEY="sk-..." export MEMORY_TENCENTDB_LLM_BASE_URL="https://api.openai.com/v1" # optional export MEMORY_TENCENTDB_LLM_MODEL="gpt-4o" # optional

4.3 启动 Gateway：三种方式

Option A —— 自动发现（零配置）。插件 checkout 位于已知路径时，Provider 自行找到src/gateway/server.ts并以sh -c 'cd <plugin-root> && exec pnpm exec tsx src/gateway/server.ts'方式Popen()。搜索顺序：

1. 树内：<plugin-root>/src/gateway/server.ts（Hermes 从本仓库 checkout 加载时命中）；
2. ~/.memory-tencentdb/tdai-memory-openclaw-plugin/src/gateway/server.ts（首选安装位置）；
3. ~/tdai-memory-openclaw-plugin/src/gateway/server.ts（legacy）；
4. ~/.hermes/plugins/tdai-memory-openclaw-plugin/src/gateway/server.ts。

该搜索顺序与init.py 中_GATEWAY_DISCOVERY_HOME_PATHS元组完全一致。除 LLM 凭据外无需任何环境变量；启动成功后~/.hermes/logs/agent.log会出现类似日志：

INFO plugins.memory.memory_tencentdb: memory-tencentdb Gateway command auto-discovered: /…/src/gateway/server.ts

Option B —— 显式自启。设置命令以覆盖/禁用自动发现：

export MEMORY_TENCENTDB_GATEWAY_CMD="node --import tsx /abs/path/to/tdai-memory-openclaw-plugin/src/gateway/server.ts"

Provider 会在initialize()时Popen()该命令，等待GET /health返回ok/degraded，崩溃时 tail stderr。

Option C —— 自行启动。在启动 Hermes 前于默认端口（127.0.0.1:8420）单独运行 Gateway；Provider 通过/health探测到已存在即跳过子进程拉起路径：

cd MemoryCore node --import tsx src/gateway/server.ts

存储后端（SQLite vs Tencent VectorDB）、embedding 配置、流水线节奏、召回策略等均为Gateway 侧设置：OpenClaw 安装在~/.openclaw/openclaw.json；独立 Hermes 部署则通过 Gateway 自身配置文件（tdai-gateway.yaml/JSON，见 src/gateway/config.ts）或环境变量配置。完整配置 schema 参见插件顶层 README（MemoryCore/README.md）。

4.4 一键安装脚本

仓库还提供了自动化安装脚本 MemoryCore/scripts/install_hermes_memory_tencentdb.sh，其流程与 README 章节相互印证：

1. 通过 npm 下载@tencentdb-agent-memory/memory-tencentdb@latest到$MEMORY_TENCENTDB_ROOT/tdai-memory-openclaw-plugin（默认~/.memory-tencentdb/tdai-memory-openclaw-plugin）；
2. 安装 Gateway 的 Node.js 依赖（npm install --omit=dev，并确保tsx可用）；
3. 将hermes-plugin/memory/memory_tencentdb符号链接到$HERMES_AGENT_DIR/plugins/memory/memory_tencentdb；
4. 生成 Gateway 启动命令（用command -v node解析绝对路径，以sh -c 'cd <dir> && exec "<node>" --import tsx/esm src/gateway/server.ts'形式写入，规避 systemd 场景下 PATH 缺失问题）——这与 README Option B 的GATEWAY_CMD语义一致；
5. 将环境变量同步写入/etc/profile.d/memory-tencentdb-env.sh（SSH 交互登录）与~/.hermes/.env（systemd user service 场景，hermes 启动时load_dotenv读取）；
6. 自动迁移 legacy 目录（~/tdai-memory-openclaw-plugin、~/memory-tdai迁移到~/.memory-tencentdb/下）。

脚本不会自动修改config.yaml启用 Provider，仅提示用户手动添加memory.provider: memory_tencentdb。

五、环境变量全景

5.1 Gateway 位置（Provider 侧）

端口解析在init.py 的_resolve_gateway_port()中实现：非整数或超出 1..65535 均告警并回退到 8420。日志目录解析在 supervisor.py 的_resolve_log_dir()：优先级为MEMORY_TENCENTDB_LOG_DIR→~/.hermes/logs/memory_tencentdb→<cwd>/.memory-tencentdb-logs（$HOME 缺失时的兜底）。

另外，README 未在表格中列出但源码支持的鉴权变量：MEMORY_TENCENTDB_GATEWAY_API_KEY（兼容TDAI_GATEWAY_API_KEY）作为出站请求的 Bearer token。值得注意的是 supervisor.py 明确：supervisor 不会把该 token 注入子进程环境——Gateway 端是否启用鉴权由运维在 Gateway 侧配置（TDAI_GATEWAY_API_KEY/server.apiKey），双方必须看到同一密钥，Provider 只负责客户端一半。

5.2 Gateway 数据目录（归 Gateway 所有，非本 Provider）

L0~L3 数据目录在 Gateway 内部（src/gateway/config.ts）解析，优先级：

1. TDAI_DATA_DIR环境变量；
2. tdai-gateway.yaml/tdai-gateway.json配置文件中的data.baseDir；
3. 默认~/.memory-tencentdb/memory-tdai（必要时可用MEMORY_TENCENTDB_ROOT覆盖父目录）；
4. Legacy 回退：若默认目录不存在但 pre-0.4 位置~/memory-tdai存在，Gateway 继续使用旧目录并向 stderr 打印一行弃用警告；运行 install_hermes_memory_tencentdb.sh 可自动迁移。

Hermes 会把继承的环境变量转发给 Gateway 子进程，因此启动 Hermes 前设置TDAI_DATA_DIR即可完成覆盖。旧变量MEMORY_TENCENTDB_DATA_DIR已不再读取——它从未被 Gateway 消费过（命名不匹配），移除只是消除一个静默 no-op。

5.3 Gateway LLM（由 Node sidecar 消费，非本 Provider）

⚠️ 本 Provider 只认MEMORY_TENCENTDB_*前缀变量用于 Gateway 位置与 LLM 凭据；数据目录解析刻意委托给 Gateway（TDAI_DATA_DIR），确保 Provider 与 Gateway 对 L0~L3 存储位置永不产生分歧。

六、LLM 工具：注册契约与参数规约

Provider 通过get_tool_schemas()向模型暴露两个搜索工具（README 表格）：

工具调用的参数会被防御性强制转换：limit接受整数、数字字符串与浮点数，拒绝布尔值，垃圾输入时告警并钳制到[1, 20]。实现位于init.py 的_coerce_limit()（默认_DEFAULT_SEARCH_LIMIT = 5，上限_MAX_SEARCH_LIMIT = 20）；type参数最终透传给atomic_search的type_filter，对应/v3/atomic/search请求体中的type字段。

这两个是注册给 LLM 的唯一工具名。旧的tdai_memory_search/tdai_conversation_search名称不再被本 Provider 服务——若旧 transcript 引用它们，handle_tool_call会返回 "Unknown tool" 错误。

源码中还存在第三个 schemamemory_tencentdb_read_scene（参数scene_id，如'travel-plan.md'或'travel-plan'），用于读取 L2 场景块全文（对应/v3/scenario/read，内部自动补全.md后缀）。README 表格未列出它，但从源码结构看，get_tool_schemas()实际返回三个 schema；system_prompt_block()生成的系统提示块中也会同时提及三个工具。工具调用的返回均解包 v3 信封（{code, message, data}），以- [type] content或[role] content行格式供 LLM 消费。

七、plugin.yaml 元数据

plugin.yaml 完整内容如下：

name: memory_tencentdb # canonical provider name display_name: memory-tencentdb version: 1.0.0 description: "memory-tencentdb four-layer memory — L0 conversation recording, L1 episodic extraction, L2 scene blocks, L3 persona synthesis via local Node.js Gateway." hooks: - on_memory_write # reserved; not yet mirrored to the Gateway - on_session_end # triggers POST /session/end aliases: - tdai # legacy config value still resolves here - memory-tencentdb # hyphenated form resolves here too

注意：README 中on_session_end标注为"triggers POST /session/end"，但 v3 迁移后init.py 中的on_session_end()与客户端end_session()均已变为显式 no-op（v3 流水线自动处理会话收尾），注释中保留了对旧调用的说明。aliases 保证老配置memory.provider: tdai或memory-tencentdb仍能解析到本 Provider。

八、Troubleshooting：五个高频问题的源码级诊断

README 给出五类故障现象，结合源码可得到更精确的排查路径：

1. 启动报 "memory-tencentdb Gateway not available"：要么MEMORY_TENCENTDB_GATEWAY_CMD未设置且自动发现未命中src/gateway/server.ts且8420 端口无人监听，要么 sidecar 崩溃。检查~/.hermes/logs/memory_tencentdb/gateway.stderr.log（可用MEMORY_TENCENTDB_LOG_DIR覆盖）；开启DEBUG日志后寻找memory-tencentdb Gateway auto-discovery found no server.ts under: …，该日志行会枚举所有被搜索的路径（对应init.py 的_discover_gateway_cmd()）。

2. Gateway 从错误的 checkout 启动：自动发现走固定偏好列表（树内优先，再到$HOME）。若想钉死特定路径，显式设置MEMORY_TENCENTDB_GATEWAY_CMD——它永远优先于发现结果（supervisor 中gateway_cmd or os.environ.get(...)的解析顺序与此一致）。

3. LLM 中搜索工具静默缺失：get_tool_schemas()返回[]，直到 Gateway 可达或环境中设置了MEMORY_TENCENTDB_GATEWAY_CMD/MEMORY_TENCENTDB_GATEWAY_PORT。设置环境变量可让工具在注册期就被乐观地广播（源码中get_tool_schemas()在_gateway_available or _initialized或两个环境变量之一存在时返回三件套，否则返回空列表）。

4. "circuit breaker tripped" 警告：连续 5 次 Gateway 错误，调用暂停 60 秒。检查 Gateway 健康与日志；熔断窗口内请求会立即返回{"error": "... (circuit breaker open)."}。

5. Capture backlog 警告：Gateway 慢或挂起，sync_turn追踪到 ≥4 个在途线程。检查 Gateway 日志中卡住的 L1 抽取或 LLM 超时；此时 watchdog 与 15 秒复活冷却会尝试自动恢复。

此外，README 未提及但源码揭示的两点值得注意：initialize()采用后台线程启动 Gateway（tdai-gateway-init守护线程），失败时仅记 warning 不致命，记忆功能会在 Gateway 可达后恢复；is_available()则通过 2 秒超时的/health探测判断 Provider 是否可用（ok/degraded均视为可用）。

九、从 Provider 到 Gateway：一次完整的 v3 数据面调用

以sync_turn为例串联完整调用链（源码路径init.py → client.py → v2-router.ts）：

1. sync_turn(user_content, assistant_content)构造带 UTC ISO 8601 时间戳的 messages 数组（user 消息时间戳比 assistant 早 1ms，保证轮次顺序），生成{role, content, timestamp}列表；
2. 提交到后台线程执行client.conversation_add(messages, session_id, team_id, agent_id, user_id)，即POST /v3/conversation/add；
3. 客户端_post()统一附加Content-Type: application/json、Authorization: Bearer <key|'local'>（Gateway 未开启鉴权时忽略 token 值）、x-tdai-service-id头，并解包{code, message, data}信封——code 非 0 时记录 warning 并原样返回供调用方检查；
4. Gateway 侧 v2-router.ts 的/v3白名单V3_ALLOWED_SUBPATHS校验子路径后分发给对应 handler（/conversation/add→handleConversationAdd，standalone 模式还会镜像写入<dataDir>/conversations/<date>.jsonl）。

prefetch(query)则并发执行三条/v3调用（L1atomic_search+ L3core_read+ L2scenario_ls），任一失败只记录 partial failure，最终按<relevant-memories>（L1）、<user-core>（L3）、<scene-navigation>（L2）三段拼接成memory-context注入文本返回。

结语

memory-tencentdb 的 Hermes Provider 是"薄客户端 + 进程管家"架构的典型范本：把繁重的四层记忆流水线完全下沉到 Node.js Gateway，Python 侧只负责生命周期桥接、HTTP 转发与进程治理。理解 client.py 的端点契约、supervisor.py 的进程管理细节，以及init.py 的熔断/背压/watchdog 三道防线，即可在生产环境中稳定接入，并在故障时快速定位问题。

【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory