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 客户端 进程管家的 MemoryProvidermemory-tencentdb 是一个面向 AI Agent 的团队级记忆中枢其记忆流水线分为四层L0 原始对话、L1 结构化情节记忆、L2 Markdown 场景块、L3 用户人格画像。而本目录中的 Python 模块hermes-plugin/memory/memory_tencentdb/不是记忆引擎本身——真正承担捕获、抽取、存储、召回与流水线调度的是与 OpenClaw 插件同包发布的 Node.js Gateway sidecar。这个 Python Provider 只做两件事作为 Hermes 侧MemoryProvider的 HTTP 客户端对应 client.py 中的MemoryTencentdbSdkClient作为 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 的关键Hermes hook / callGateway 端点行为prefetch(query)POST /recall同步。返回memory-context文本供注入提示词sync_turn(user, assistant)POST /capture后台守护线程中 fire-and-forget最多 4 个并发在途shutdown()/on_session_endPOST /session/end冲刷待处理流水线工作get_tool_schemas()—向 LLM 注册两个搜索工具详见第五节需要补充的是v3 迁移后部分映射已发生语义变化prefetch()实际并发执行三条/v3数据面调用L1atomic/search L3core/read L2scenario/lssync_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 capturesync_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.tsProvider 会以Popen()拉起 sidecar以 0.5 秒间隔轮询GET /health最长等待 30 秒HEALTH_CHECK_MAX_WAIT 30见 supervisor.py崩溃时自动 tail 最近 2048 字节的gateway.stderr.logLOG_TAIL_BYTES_ON_CRASH用于诊断。源码还展示了 README 之外的细节进程组回收子进程以start_new_sessionTrue启动关停时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__.pyBundled内置hermes-agent-checkout/plugins/memory/name/——memory_tencentdb随 hermes-agent 发行于此与byterover/、honcho/、mem0/、hindsight/等内置 Provider 并列同名冲突时内置优先。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_tencentdbInstall 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.yamlmemory: provider: memory_tencentdb # canonical name # 向后兼容的别名memory-tencentdb、tdai4.2 提供 Gateway 运行时与 LLM 凭据Gateway 至少需要一个 OpenAI 兼容端点来驱动 L1/L2/L3 抽取。在 Hermes 进程环境中设置export MEMORY_TENCENTDB_LLM_API_KEYsk-... export MEMORY_TENCENTDB_LLM_BASE_URLhttps://api.openai.com/v1 # optional export MEMORY_TENCENTDB_LLM_MODELgpt-4o # optional4.3 启动 Gateway三种方式Option A —— 自动发现零配置。插件 checkout 位于已知路径时Provider 自行找到src/gateway/server.ts并以sh -c cd plugin-root exec pnpm exec tsx src/gateway/server.ts方式Popen()。搜索顺序树内plugin-root/src/gateway/server.tsHermes 从本仓库 checkout 加载时命中~/.memory-tencentdb/tdai-memory-openclaw-plugin/src/gateway/server.ts首选安装位置~/tdai-memory-openclaw-plugin/src/gateway/server.tslegacy~/.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.tsOption B —— 显式自启。设置命令以覆盖/禁用自动发现export MEMORY_TENCENTDB_GATEWAY_CMDnode --import tsx /abs/path/to/tdai-memory-openclaw-plugin/src/gateway/server.tsProvider 会在initialize()时Popen()该命令等待GET /health返回ok/degraded崩溃时 tail stderr。Option C —— 自行启动。在启动 Hermes 前于默认端口127.0.0.1:8420单独运行 GatewayProvider 通过/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 参见插件顶层 READMEMemoryCore/README.md。4.4 一键安装脚本仓库还提供了自动化安装脚本 MemoryCore/scripts/install_hermes_memory_tencentdb.sh其流程与 README 章节相互印证通过 npm 下载tencentdb-agent-memory/memory-tencentdblatest到$MEMORY_TENCENTDB_ROOT/tdai-memory-openclaw-plugin默认~/.memory-tencentdb/tdai-memory-openclaw-plugin安装 Gateway 的 Node.js 依赖npm install --omitdev并确保tsx可用将hermes-plugin/memory/memory_tencentdb符号链接到$HERMES_AGENT_DIR/plugins/memory/memory_tencentdb生成 Gateway 启动命令用command -v node解析绝对路径以sh -c cd dir exec node --import tsx/esm src/gateway/server.ts形式写入规避 systemd 场景下 PATH 缺失问题——这与 README Option B 的GATEWAY_CMD语义一致将环境变量同步写入/etc/profile.d/memory-tencentdb-env.shSSH 交互登录与~/.hermes/.envsystemd user service 场景hermes 启动时load_dotenv读取自动迁移 legacy 目录~/tdai-memory-openclaw-plugin、~/memory-tdai迁移到~/.memory-tencentdb/下。脚本不会自动修改config.yaml启用 Provider仅提示用户手动添加memory.provider: memory_tencentdb。五、环境变量全景5.1 Gateway 位置Provider 侧变量默认值说明MEMORY_TENCENTDB_GATEWAY_HOST127.0.0.1Gateway 主机MEMORY_TENCENTDB_GATEWAY_PORT8420Gateway 端口必须 1..65535非法值回退默认MEMORY_TENCENTDB_GATEWAY_CMD—设置后 Provider 以此命令自动启动 Gateway未设置则自动发现src/gateway/server.ts见 Option AMEMORY_TENCENTDB_LOG_DIR~/.hermes/logs/memory_tencentdbSupervisor 写入gateway.stdout.log/gateway.stderr.log的位置端口解析在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 所有非本 ProviderL0~L3 数据目录在 Gateway 内部src/gateway/config.ts解析优先级TDAI_DATA_DIR环境变量tdai-gateway.yaml/tdai-gateway.json配置文件中的data.baseDir默认~/.memory-tencentdb/memory-tdai必要时可用MEMORY_TENCENTDB_ROOT覆盖父目录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变量默认值说明MEMORY_TENCENTDB_LLM_API_KEY—LLM API keyL1/L2/L3 必需MEMORY_TENCENTDB_LLM_BASE_URLhttps://api.openai.com/v1OpenAI 兼容 API 基址MEMORY_TENCENTDB_LLM_MODELgpt-4o模型名⚠️ 本 Provider 只认MEMORY_TENCENTDB_*前缀变量用于 Gateway 位置与 LLM 凭据数据目录解析刻意委托给 GatewayTDAI_DATA_DIR确保 Provider 与 Gateway 对 L0~L3 存储位置永不产生分歧。六、LLM 工具注册契约与参数规约Provider 通过get_tool_schemas()向模型暴露两个搜索工具README 表格工具用途参数memory_tencentdb_memory_search搜索 L1 结构化长期记忆query必填、limit1..20默认 5、typepersona/episodic/instructionmemory_tencentdb_conversation_search搜索 L0 原始对话历史query必填、limit1..20默认 5工具调用的参数会被防御性强制转换limit接受整数、数字字符串与浮点数拒绝布尔值垃圾输入时告警并钳制到[1, 20]。实现位于init.py 的_coerce_limit()默认_DEFAULT_SEARCH_LIMIT 5上限_MAX_SEARCH_LIMIT 20type参数最终透传给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()实际返回三个 schemasystem_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-opv3 流水线自动处理会话收尾注释中保留了对旧调用的说明。aliases 保证老配置memory.provider: tdai或memory-tencentdb仍能解析到本 Provider。八、Troubleshooting五个高频问题的源码级诊断README 给出五类故障现象结合源码可得到更精确的排查路径启动报 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()。Gateway 从错误的 checkout 启动自动发现走固定偏好列表树内优先再到$HOME。若想钉死特定路径显式设置MEMORY_TENCENTDB_GATEWAY_CMD——它永远优先于发现结果supervisor 中gateway_cmd or os.environ.get(...)的解析顺序与此一致。LLM 中搜索工具静默缺失get_tool_schemas()返回[]直到 Gateway 可达或环境中设置了MEMORY_TENCENTDB_GATEWAY_CMD/MEMORY_TENCENTDB_GATEWAY_PORT。设置环境变量可让工具在注册期就被乐观地广播源码中get_tool_schemas()在_gateway_available or _initialized或两个环境变量之一存在时返回三件套否则返回空列表。circuit breaker tripped 警告连续 5 次 Gateway 错误调用暂停 60 秒。检查 Gateway 健康与日志熔断窗口内请求会立即返回{error: ... (circuit breaker open).}。Capture backlog 警告Gateway 慢或挂起sync_turn追踪到 ≥4 个在途线程。检查 Gateway 日志中卡住的 L1 抽取或 LLM 超时此时 watchdog 与 15 秒复活冷却会尝试自动恢复。此外README 未提及但源码揭示的两点值得注意initialize()采用后台线程启动 Gatewaytdai-gateway-init守护线程失败时仅记 warning 不致命记忆功能会在 Gateway 可达后恢复is_available()则通过 2 秒超时的/health探测判断 Provider 是否可用ok/degraded均视为可用。九、从 Provider 到 Gateway一次完整的 v3 数据面调用以sync_turn为例串联完整调用链源码路径init.py → client.py → v2-router.tssync_turn(user_content, assistant_content)构造带 UTC ISO 8601 时间戳的 messages 数组user 消息时间戳比 assistant 早 1ms保证轮次顺序生成{role, content, timestamp}列表提交到后台线程执行client.conversation_add(messages, session_id, team_id, agent_id, user_id)即POST /v3/conversation/add客户端_post()统一附加Content-Type: application/json、Authorization: Bearer key|localGateway 未开启鉴权时忽略 token 值、x-tdai-service-id头并解包{code, message, data}信封——code 非 0 时记录 warning 并原样返回供调用方检查Gateway 侧 v2-router.ts 的/v3白名单V3_ALLOWED_SUBPATHS校验子路径后分发给对应 handler/conversation/add→handleConversationAddstandalone 模式还会镜像写入dataDir/conversations/date.jsonl。prefetch(query)则并发执行三条/v3调用L1atomic_search L3core_read L2scenario_ls任一失败只记录 partial failure最终按relevant-memoriesL1、user-coreL3、scene-navigationL2三段拼接成memory-context注入文本返回。结语memory-tencentdb 的 Hermes Provider 是薄客户端 进程管家架构的典型范本把繁重的四层记忆流水线完全下沉到 Node.js GatewayPython 侧只负责生命周期桥接、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考