TencentDB Agent Memory命令行工具全解析：memory-tencentdb-ctl使用指南

TencentDB Agent Memory命令行工具全解析：memory-tencentdb-ctl使用指南

【免费下载链接】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是AI Agent的团队级记忆中枢，能将对话、文档和代码转化为四种可重用的记忆资产（Chat Memory、Skill、LLM-Wiki、Code-Graph），并在智能体和框架之间进行治理、共享和配备。而memory-tencentdb-ctl作为其命令行工具，是日常运维和配置的核心入口，掌握它能让你轻松管理TencentDB Agent Memory的各项功能。

快速了解memory-tencentdb-ctl

memory-tencentdb-ctl.sh是配合install_hermes_memory_tencentdb.sh使用的运维脚本。先通过安装脚本部署好插件和Node依赖，之后日常的启停、配置等操作就全部通过memory-tencentdb-ctl.sh来完成啦~ 🚀

两种运行模式

脚本有两种模式，默认是独立模式，完全不触碰~/.hermes：

为什么hermes模式要多写env文件？因为hermes进程会托管式地把Gateway以子进程拉起来（supervisor用os.environ.copy()传环境），此时Gateway读不到tdai-gateway.json所在的shell环境，必须通过$HERMES_HOME/env.d/*.sh让hermes自身source才能把凭据传进去。独立模式下Gateway自己读JSON，无此需要。

核心路径说明

路径变量约定：以下会用$HERMES_HOME指代hermes的家目录，默认~/.hermes，但你可以通过环境变量覆盖（例如export HERMES_HOME=/srv/hermes），脚本和hermes自身都遵守这个变量。

自0.4.x起，所有tdai相关数据/代码默认收纳到统一根目录$MEMORY_TENCENTDB_ROOT（默认~/.memory-tencentdb）之下：

• $TDAI_INSTALL_DIR默认$MEMORY_TENCENTDB_ROOT/tdai-memory-openclaw-plugin（即~/.memory-tencentdb/tdai-memory-openclaw-plugin）
• $TDAI_DATA_DIR默认$MEMORY_TENCENTDB_ROOT/memory-tdai（即~/.memory-tencentdb/memory-tdai）

下文出现这些变量时先export一份覆盖，再跑命令即可全局生效。旧版本使用~/tdai-memory-openclaw-plugin与~/memory-tdai；install_hermes_memory_tencentdb.sh在升级时会自动迁移这两个旧目录到新位置。

所有路径都能用同名环境变量覆盖（再次列出便于对照）：MEMORY_TENCENTDB_ROOT（默认~/.memory-tencentdb）、TDAI_INSTALL_DIR（默认$MEMORY_TENCENTDB_ROOT/tdai-memory-openclaw-plugin）、TDAI_DATA_DIR（默认$MEMORY_TENCENTDB_ROOT/memory-tdai）、HERMES_HOME（默认~/.hermes）、MEMORY_TENCENTDB_LOG_DIR、MEMORY_TENCENTDB_GATEWAY_HOST/PORT。

依赖：bash、python3、node >= 22、npx、lsof或ss。

安装与调用方式

脚本随npm包发布到node_modules/.../scripts/下，但没有注册为bin命令。要用全局命令名调用，必须自己做一次软链。

从npm包里直接运行（无需任何配置）

npm install @tencentdb-agent-memory/memory-tencentdb # 项目内安装，路径可由npm root动态算出 "$(npm root)/@tencentdb-agent-memory/memory-tencentdb/scripts/memory-tencentdb-ctl.sh" --help # 全局安装则用npm root -g "$(npm root -g)/@tencentdb-agent-memory/memory-tencentdb/scripts/memory-tencentdb-ctl.sh" --help

npm root/npm root -g会在所有包管理器（npm / pnpm / yarn）和不同的prefix配置下返回正确目录，避免硬编码node_modules/路径。适合一次性、临时使用的场景。

软链到PATH（推荐给运维/长期使用）

不论脚本来源（git clone出来的仓库 /npm install装的包 / 自定义部署目录），先把脚本路径算出来存到一个变量里，再统一做软链。这样无需关心你把仓库放在~/code/、/opt/、还是别的什么地方。

# 第一步：定位memory-tencentdb-ctl.sh的真实路径（任选一种来源） # (a) 从git仓库（在仓库根目录或任意子目录里执行） SCRIPT="$(git -C "$(git rev-parse --show-toplevel)" ls-files | \ grep -E 'scripts/memory-tencentdb-ctl\.sh$' | head -1)" SCRIPT="$(git rev-parse --show-toplevel)/$SCRIPT" # (b) 从已npm全局安装的包 SCRIPT="$(npm root -g)/@tencentdb-agent-memory/memory-tencentdb/scripts/memory-tencentdb-ctl.sh" # (c) 从项目本地的node_modules SCRIPT="$(npm root)/@tencentdb-agent-memory/memory-tencentdb/scripts/memory-tencentdb-ctl.sh" # (d) 完全手写绝对路径（如部署到非标准位置） SCRIPT="/opt/tdai/scripts/memory-tencentdb-ctl.sh" # 第二步：验证路径正确，然后软链 test -f "$SCRIPT" && echo "ok: $SCRIPT" || { echo "not found"; exit 1; } chmod +x "$SCRIPT" sudo ln -sf "$SCRIPT" /usr/local/bin/memory-tencentdb-ctl # 同样的办法把install_hermes_memory_tencentdb.sh链接成install-memory-tencentdb（可选） INSTALL_SCRIPT="$(dirname "$SCRIPT")/install_hermes_memory_tencentdb.sh" test -f "$INSTALL_SCRIPT" && { chmod +x "$INSTALL_SCRIPT" sudo ln -sf "$INSTALL_SCRIPT" /usr/local/bin/install-memory-tencentdb }

之后直接memory-tencentdb-ctl …/install-memory-tencentdb …。

为什么不直接用npm bin注册？这两个脚本是运维工具而不是包的核心API，主仓库希望用户显式完成PATH注册（避免无意中污染全局命令空间，并避免npm卸载时静默移除运维入口）。

生命周期管理（两种模式通用）

memory-tencentdb-ctl start # 若:8420已占用会直接返回；否则后台spawn，等待/health通过 memory-tencentdb-ctl stop # 先SIGTERM，5s内未退则SIGKILL memory-tencentdb-ctl restart memory-tencentdb-ctl status # 打印模式、端口、data/log路径、进程状态 memory-tencentdb-ctl health # GET /health，纯python3实现，不要求curl memory-tencentdb-ctl logs # tail -f stdout + stderr memory-tencentdb-ctl logs err 500 # 只看stderr最近500行

启动命令解析顺序：

1. 环境变量MEMORY_TENCENTDB_GATEWAY_CMD（install_hermes_memory_tencentdb.sh写入/etc/profile.d/memory-tencentdb-env.sh的那条）。
2. 回退到sh -c 'cd $TDAI_INSTALL_DIR && exec npx tsx src/gateway/server.ts'。

启动时会自动source的环境文件：

• 两种模式：/etc/profile.d/memory-tencentdb-env.sh
• 仅hermes模式：/etc/profile.d/hermes-env.sh以及$HERMES_HOME/env.d/*.sh

配置LLM / Embedding / VDB

三类凭据统一落到$TDAI_DATA_DIR/tdai-gateway.json（0600，原子写）。config llm在--hermes模式下会额外写一份env文件；Embedding / VDB从不写env。

LLM配置

# standalone模式：只写tdai-gateway.json memory-tencentdb-ctl config llm \ --api-key "sk-xxxxxxxxxxxx" \ --base-url "https://api.openai.com/v1" \ --model "gpt-4o" \ --restart # hermes模式：tdai-gateway.json + $HERMES_HOME/env.d/memory-tencentdb-llm.sh memory-tencentdb-ctl --hermes config llm \ --api-key "sk-xxxxxxxxxxxx" \ --base-url "https://api.openai.com/v1" \ --model "gpt-4o" \ --restart

• JSON写入点：$.llm.{baseUrl, apiKey, model}。
• env文件写入（仅--hermes）：TDAI_LLM_*及MEMORY_TENCENTDB_LLM_*别名（Python provider的get_config_schema()会读后者）。

Embedding配置

默认关闭（provider=none）。启用远端OpenAI兼容服务：

memory-tencentdb-ctl config embedding \ --provider openai \ --api-key "sk-xxxx" \ --base-url "https://api.openai.com/v1" \ --model "text-embedding-3-small" \ --dimensions 1536 \ --restart # 关闭embedding（退化为BM25/关键词召回） memory-tencentdb-ctl config embedding --provider none --restart

• JSON写入点：$.memory.embedding.{provider, baseUrl, apiKey, model, dimensions, enabled, proxyUrl?}。
• qclawprovider额外要求--proxy-url。
• 校验规则与src/config.ts的parseConfig()对齐：dimensions为正整数，非none必须带apiKey/baseUrl/model/dimensions；缺项直接报错不写半残JSON。

VectorDB（Tencent Cloud VDB / tcvdb）配置

memory-tencentdb-ctl config vdb \ --url "http://xxx-vdb.tencentclb.com:8100" \ --username root \ --api-key "YOUR-VDB-API-KEY" \ --database "openclaw_memory" \ --alias "primary" \ --embedding-model "bge-large-zh" \ --ca-pem "/etc/ssl/vdb-ca.pem" \ --restart

• JSON写入点：$.memory.tcvdb.{url, username, apiKey, database, alias?, caPemPath?, embeddingModel?}。
• 默认同时把$.memory.storeBackend切到"tcvdb"；只想预埋配置先不切，加--no-set-backend。
• --ca-pem只写路径不复制文件；脚本会校验可读性。

退回本地SQLite（关闭VDB后端）

# 默认：保留memory.tcvdb凭据（方便随时再切回去），仅把storeBackend改回sqlite memory-tencentdb-ctl config vdb-off --restart # 同时把腾讯云VDB的url / apiKey / database等凭据从JSON中清掉 memory-tencentdb-ctl config vdb-off --purge-creds --restart

• JSON写入点：把$.memory.storeBackend设为"sqlite"；--purge-creds时额外删除整段$.memory.tcvdb。
• $.llm/$.memory.embedding等其它顶级段完全保留，hermes侧memory.provider不动（仍是memory_tencentdb，只是它内部存储退回sqlite）。
• 配置文件不存在时给出warn并写入仅含{"memory":{"storeBackend":"sqlite"}}的最小配置。
• 与config vdb完全镜像：可与--dry-run/--restart组合使用。

查看当前配置

memory-tencentdb-ctl config show

• 打印tdai-gateway.json，apiKey/password/token字段自动脱敏为<redacted:NN chars>。
• hermes模式下额外打印$HERMES_HOME/env.d/memory-tencentdb-*.sh（API key也会脱敏），可直接贴工单。

打通hermes（仅--hermes模式）

memory-tencentdb-ctl --hermes enable-hermes-memory

幂等：把$HERMES_HOME/config.yaml的memory:段的provider:改成memory_tencentdb（不存在则新增整段）。改完后重启hermes：

source "$HERMES_HOME/env.d/memory-tencentdb-llm.sh" pkill -f hermes-agent || true hermes

关于写入策略：脚本采用"格式保真"双路径，永不重写整个YAML：

1. 首选：检测到ruamel.yaml时走round-trip，完整保留注释、键序、引号、缩进风格（推荐pip install --user ruamel.yaml享受最佳保真度，非必装）；
2. 降级：未安装ruamel时走最小化原位行编辑——只重写provider:那一行，缩进直接从同段已有兄弟键的前缀逐字符拷贝（零猜测、零格式破坏）；
3. 若memory:段不存在，则在文件末尾追加最小段，缩进从文档其它顶级段的子键拓印。 实测对真实~/.hermes/config.yaml做byte-for-byte diff，除provider值本身外其余字节完全一致。

非hermes模式下调用该命令会直接报错退出。

想反过来"保留hermes provider不变，仅让TDAI内部存储退回sqlite"，用§5.4的config vdb-off即可（不需要也不要改hermes的memory.provider）。

典型使用流程

场景A：Gateway独立部署（不使用hermes）

# 1) 安装 # INSTALL_SCRIPT的取值方式见上文3.2节（git rev-parse / npm root / 手填均可） # 例如从git仓库根：INSTALL_SCRIPT="$(git rev-parse --show-toplevel)/scripts/install_hermes_memory_tencentdb.sh" # 从npm全局： INSTALL_SCRIPT="$(npm root -g)/@tencentdb-agent-memory/memory-tencentdb/scripts/install_hermes_memory_tencentdb.sh" bash "$INSTALL_SCRIPT" # 2) 只配Gateway所需凭据 memory-tencentdb-ctl config llm --api-key "sk-..." --base-url "https://api.openai.com/v1" --model gpt-4o memory-tencentdb-ctl config embedding --provider openai --api-key "sk-..." --base-url "https://api.openai.com/v1" \ --model text-embedding-3-small --dimensions 1536 memory-tencentdb-ctl config vdb --url "http://xxx:8100" --api-key "..." --database openclaw_memory # 3) 启动 + 自检 memory-tencentdb-ctl start memory-tencentdb-ctl status memory-tencentdb-ctl health # 预期: {"status":"ok",...}

场景B：集成hermes

# 1) 安装（与场景A相同；INSTALL_SCRIPT由上文3.2节算出） bash "$INSTALL_SCRIPT" # 2) 全程加--hermes（或export MEMORY_TENCENTDB_MODE=hermes一次） memory-tencentdb-ctl --hermes config llm --api-key "sk-..." --base-url "https://api.openai.com/v1" --model gpt-4o memory-tencentdb-ctl --hermes config embedding --provider openai --api-key "sk-..." \ --base-url "https://api.openai.com/v1" \ --model text-embedding-3-small --dimensions 1536 memory-tencentdb-ctl --hermes config vdb --url "http://xxx:8100" --api-key "..." --database openclaw_memory # 3) 启动Gateway（通常由hermes supervisor托管，这里是手动兜底） memory-tencentdb-ctl --hermes start memory-tencentdb-ctl --hermes status # 4) 在hermes config里启用provider，并重启hermes memory-tencentdb-ctl --hermes enable-hermes-memory source "$HERMES_HOME/env.d/memory-tencentdb-llm.sh" pkill -f hermes-agent ; hermes

如果嫌--hermes每次都要带，可以：

export MEMORY_TENCENTDB_MODE=hermes

之后所有调用自动切到hermes模式，命令行无需再加--hermes。

场景C：临时把TDAI的存储退回sqlite（保留hermes集成）

适用于VDB不可达/排障/离线开发等场景：希望hermes端memory.provider仍是memory_tencentdb，但让Gateway改用本地SQLite落盘。

# (A) 默认：保留memory.tcvdb凭据，仅把storeBackend切回sqlite memory-tencentdb-ctl config vdb-off --restart # (B) 排障结束想切回vdb：当前需要重新跑一次config vdb（必填项需重新提供， # 即使JSON里凭据还在；脚本是基于必填校验的"重新声明"语义，不是toggle） memory-tencentdb-ctl config vdb \ --url "http://xxx-vdb.tencentclb.com:8100" \ --api-key "<你的KEY>" \ --database "openclaw_memory" \ --restart # (C) 彻底放弃vdb：清掉凭据 memory-tencentdb-ctl config vdb-off --purge-creds --restart

之所以(B)不提供"零参数vdb-on"，是因为原config vdb子命令把--url/--api-key/--database设为强校验，避免用户拼装出半残配置；如果你希望把"已存的凭据重新激活"也做成单命令，告诉维护者补一个config vdb-on即可（实现方式与vdb-off完全镜像）。

不要为了"切回sqlite"去改~/.hermes/config.yaml的memory.provider！hermes看到的依然是memory_tencentdbprovider，存储后端切换是Gateway内部的事，对hermes完全透明。

全局选项 & 调试技巧

• 所有写操作支持--dry-run（放在命令最前），会打印将要写入的内容但不落盘：

  memory-tencentdb-ctl --dry-run config llm --api-key k --base-url https://x --model m

• 敏感文件权限一律0600；env.d/memory-tencentdb-llm.sh含明文API key，不要commit。
• 启动失败：memory-tencentdb-ctl logs err 200查看stderr；手动前台跑一遍更容易看到报错：

  cd "$TDAI_INSTALL_DIR" && npx tsx src/gateway/server.ts

• 端口冲突：MEMORY_TENCENTDB_GATEWAY_PORT=18420 memory-tencentdb-ctl restart。
• 验证hermes有没有吃到新env（hermes模式）：

  tr '\0' '\n' < /proc/$(pgrep -n hermes-agent)/environ | grep -E 'TDAI_|MEMORY_TENCENTDB_'

退出码

要封装成systemd unit，基于memory-tencentdb-ctl start/memory-tencentdb-ctl stop写Type=forking的service即可（Gateway是无状态HTTP sidecar，不依赖systemd readiness协议）。

TencentDB Agent Memory记忆金字塔

TencentDB Agent Memory的记忆管理采用金字塔结构，从下到上分为L0 Raw Log、L1 Atomic Memory、L2 Scene Block和L3 Persona四个层级，通过memory-tencentdb-ctl工具可以更好地对这些记忆资产进行管理和配置。

通过这篇指南，相信你已经对memory-tencentdb-ctl命令行工具有了全面的了解。无论是独立部署Gateway还是集成hermes，都能轻松应对。赶紧动手试试，让TencentDB Agent Memory为你的AI Agent团队提供强大的记忆支持吧！

【免费下载链接】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