奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

TencentDB Agent Memory 有几种装法：单机、Docker 与合并镜像

2026-08-16

想给 TencentDB Agent Memory 找一条「怎么装」的路径，第一件让人卡住的事不是命令太难，而是仓库里的装法不止一种。我们在 2026-08-16 按快照 97f9465 把这个仓库通读了一遍——注意它的默认分支是 feat/server_team，不是 main 也不是 master，本文下面提到的所有文件路径都在这个分支上——数下来一共有七条互不相同的安装/部署路径。它们产出的进程数、依赖的外部组件、端口，都不一样。

先说明本文的边界：以下内容全部来自对仓库静态文件的阅读，我们没有构建过镜像、没有启动过任何容器、没有调用过任何接口。凡是写「启动后会怎样」的地方，都是文档原文的转述。另外该项目主模块 MemoryCore 的 package.json 里 version 是 2.0.0-beta.1，另外三个模块 MemoryKnowledge / MemoryPanel / MemoryProxy 的 package.json 版本都还是 0.1.0，接口与参数随版本变动。

动手之前先过一关：目录名、包名、镜像名是三套东西

这一步不过，后面每一步都会踩。仓库根下的四个模块目录是 MemoryCore / MemoryKnowledge / MemoryPanel / MemoryProxy，但它们 package.json 里的 name 分别是 @tencentdb-agent-memory/memory-tencentdb-v2、@tencentdb-agent-memory/knowledge-service、team-memory-control、context-proxy。也就是说，MemoryPanel 这个目录对应的包叫 team-memory-control，MemoryProxy 对应的包叫 context-proxy——别把目录名写进安装命令。

镜像名又是第三套：deploy/dockerhub/README.md:11-15 里三个构建目标是 memory-core、memory-proxy、memory-hub，其中 memory-hub 是由 MemoryPanel/ 加 MemoryKnowledge/ 两个目录合并出来的，仓库里并没有 MemoryHub/ 这个目录（CONTRIBUTING_CN.md:20 的结构图里列了一个，实际 git ls-files 的顶层分布中没有；只陈述这处差异，不做延伸）。

路径 A：三件套一键脚本，起三个容器

这是 README 首页给的方式。README_CN.md:36-42 的四行命令是 clone 仓库、进 deploy/global-images、cp .env.example .env 填参数、跑 ./start-all.sh。INSTALL_CN.md:17-33 是同一条流程，但多一步 ./verify.sh。

start-all.sh:29-38 的启动顺序是 memory-core → memory-hub → proxy。三个容器的名字、镜像和宿主机端口写在 deploy/global-images/README.md:9-11：

组件容器名镜像宿主机端口
memory-coretdai-memory-coreagentmemory/memory-core8420
memory-hubtdai-memory-hubagentmemory/memory-hub8125 / 8424
proxytdai-proxyagentmemory/memory-proxy8096

docker 网络固定叫 tdai-memory-stack，数据卷两个：tdai-memory-core-data 存 core 的 SQLite 与记忆，tdai-panel-data 存 hub 里 knowledge 的 SQLite、git clone 与 wiki 文件（.env.example:70-71）。首次启动时 start-memory-core.sh:150-229 会做 init-admin 生成一个 admin 用户，user_key 是 sk-mem- 加 32 位随机串，落盘到 deploy/global-images/.admin-key 并 umask 077。清理方式分两档：./stop-all.sh 只删容器，加 --purge 才会连两个 volume、网络、.admin-key 一起删（stop-all.sh:25-58）。

必填项是硬校验的。start-all.sh:21-27 的 require_vars 一共要 15 项：三个镜像名、四个端口、两个卷名、三个 MEMORY_LLM_*、KNOWLEDGE_PUBLIC_BASE_URL、三个 PROXY_UPSTREAM_*；判定规则在 _lib.sh:34-49——空值或等于字面量 REPLACE_ME 都算缺失。.env.example 里这六个 LLM 相关变量的默认值就是 REPLACE_ME，所以不填必然过不去。

这条路径的环境前提写在 deploy/global-images/README.md:20-24：macOS / Linux、Docker（Docker Desktop / colima / OrbStack 任一）、bash 4+（并注明 macOS 自带的 3.2 也能跑）。文档没有提 Windows；_lib.sh:54-76 的 find_docker() 依次找 PATH 里的 docker、/opt/homebrew/Cellar/docker、/usr/local/Cellar/docker、/opt/homebrew/bin/docker、/usr/local/bin/docker，都找不到就直接 die。这几条是脚本里能读到的事实，Windows 侧能不能跑、怎么跑，仓库没给说法，我们也不替它推断。

路径 B / C：只装 Hub，或者自己把 Hub 建出来

如果 Memory Core 已经在本机 8420 上跑着了，INSTALL_CN.md:213-234 给的是单独 docker pull docker.io/agentmemory/memory-hub:latest 再 docker run 的方式，映射 8125 与 8424，挂 tdai-panel-data:/data/knowledge，另外带 REMOTE_INSTANCE_URL、LLM_MODE=custom、LLM_BASE_URL 等几个 -e。这条路径的前提就是「Core 已经在跑」，它自己不负责把 Core 拉起来。

想自己构建这个合并镜像，看 deploy/panel-knowledge-combined/。它的 Dockerfile 共 90 行、node:22-slim 基底、五个 stage（base / panel-ui-builder / panel-builder / knowledge-builder / runtime），EXPOSE 8125 8424，HEALTHCHECK 同时 curl 两个 /health（--interval=20s --timeout=8s --retries=15 --start-period=45s）。镜像内置了一批 ENV 默认值（Dockerfile:47-67），例如 PANEL_PORT=8125、KNOWLEDGE_PORT=8424、LLM_MODE=proxy、LLM_MAX_TOKENS=32768、LLM_TIMEOUT_MS=1200000、KNOWLEDGE_DB_PATH=/data/knowledge/knowledge.db。该目录 README 自述真正必填的只有三项：挂载 metadata-instances.json、KNOWLEDGE_PUBLIC_BASE_URL（必须含 /v3 前缀）、KNOWLEDGE_LLM_PROXY_BASE_URL。

路径 D：MemoryCore 单模块，两种形态共用一个 Gateway

不想上容器编排，可以只跑 MemoryCore。源码方式是 npm install && npm run build，再 node --import tsx src/gateway/server.ts（MemoryCore/README_CN.md:60-77；README.deployment.md:26-38 给的写法是 npx tsx src/gateway/server.ts）。默认监听 127.0.0.1:8420，数据默认写到 ~/.memory-tencentdb/memory-tdai，默认关闭远程 Embedding、用 BM25 召回。要跨机访问，必须同时设 TDAI_GATEWAY_HOST=0.0.0.0 与 TDAI_GATEWAY_API_KEY；开了鉴权之后，除 /health 与 CORS 预检外的所有接口都要带 Authorization: Bearer <TDAI_GATEWAY_API_KEY> 和 x-tdai-service-id。

README.deployment.md:8-20 把它分成两种部署形态：Standalone 用 SQLite 加本地文件，状态放进程内 Map/Timer，单空间；Service 用 TCVDB、COS、Redis，多空间按 service_id 分。原文说两种形态「共享同一份 Gateway 二进制和同一套 v1/v2 HTTP API」，切换只调 TDAI_DEPLOY_MODE。这里有个必须提前知道的边界：Service 形态所需的配置模板 MemoryCore/tdai-gateway.service.yaml 在我们读的这份快照里不存在，README.docker.md 有四处引用了它；同样引用了但快照里找不到的还有 MemoryCore/tdai-gateway.real.yaml、MemoryCore/docker-compose.local.yaml、MemoryCore/deploy/k8s/tdai-memory.yaml。存在的是 MemoryCore/tdai-gateway.standalone.yaml 与 MemoryCore/tdai-gateway.yaml。只陈述这个差异，至于 Service 形态的代码路径是否完整，我们没有逐个去核，也不做判断。

路径 E / F / G：独立镜像与插件，注意端口不是同一套

MemoryKnowledge 可以独立跑，它自己的 Dockerfile（89 行）EXPOSE 8421、ENV PORT=8421，docker-compose.yml 里 service 名叫 knowledge、默认镜像 team-knowledge:latest，--public-url 是必填参数、缺了直接报错。MemoryPanel 的本地镜像用 MemoryPanel/docker/local/Dockerfile.local（80 行），EXPOSE 8123。

这里最容易踩的是端口对不上：独立形态下 Knowledge 是 8421、Panel 是 8123；到了合并镜像和三件套脚本里，Knowledge 变成 8424、Panel 变成 8125（panel-knowledge-combined/Dockerfile:49,85、.env.example:50）。同一个服务在两套形态下用两个端口，照抄另一套形态的文档就会接不上。改端口时还要记得 KNOWLEDGE_PUBLIC_BASE_URL 得跟着改，且必须保留 /v3 前缀。

路径 G 是插件与 SDK。MemoryCore/scripts/install-openclaw-plugin.sh（398 行）开头自述得很克制：它装的是「OpenClaw 适配层」记忆插件，「不是 Gateway 内核安装；也不是 OpenClaw 内置流程，OpenClaw 本身不会调用本脚本」，插件 ID 写作 memory-tencentdb-client，且明确不含 Offload 与 E2E harness。另有 install-hermes-plugin.sh（172 行）。SDK 分别在 sdk/memory-core/typescript/ 与 sdk/memory-core/python/。

装之前值得先看的几处口径差异

这些不是「坑」的清单，只是仓库里同一件事在不同位置写法不同的地方，动手前知道会省事：

  • Proxy 的三个开关。deploy/global-images/README.md:192 写 proxy 默认关闭 auth / sessionInit / costGuard、只做纯转发；而 start-all.sh:36-38 把 PROXY_FULL_STACK 默认设成 1，start-proxy.sh:59-63 据此会把 auth / tdai / sessionInit 一起打开（costGuard 在生成的 YAML 里仍是 enabled: false）。INSTALL_CN.md:188-190 的说法与 start-all.sh 一致。单独跑 start-proxy.sh 时这三个开关确实默认 0。
  • MEMORY_CORE_GATEWAY_API_KEY 的默认值三处不同。README 表格写默认 local；start-memory-core.sh:25 用 ${VAR-}（默认空）；start-memory-hub.sh:26 与 start-proxy.sh:25 用 ${VAR:-local}。.env.example:80 落盘的是空值。而 start-memory-core.sh:22-24 的注释写明了「当前 memory-core 的 Bearer gate 与 proxy auth 存在已知不兼容」，所以 proxy 启用 auth 时要求这个变量留空——这与 MemoryCore/README_CN.md:85-90 那句「跨机访问要设强随机 token」的方向正好相反。两处口径就摆在这里，别混着抄。
  • 运行用户。README.docker.md:13 的镜像信息表写运行用户是 tdai（uid 10001），而 MemoryCore/Dockerfile 的 164 行里没有 USER 指令、也没有 useradd。仓库里 7 个 Dockerfile / compose 文件中唯一有 USER 指令的是 MemoryProxy/Dockerfile:78,87（用户名 app，uid 10001）。
  • 协议表述。LICENSE:5 原文写 TencentDB Agent Memory is licensed under the MIT.，README 徽章也是 MIT；GitHub 侧未能自动识别、显示 NOASSERTION；而 README.docker.md:264-266 的 License 小节写的是 Proprietary — Tencent Cloud。四处口径并存，以官方 LICENSE 原文为准。

该选哪条

按你手上已有的东西倒推就行：什么都没有、想一次把链路跑通，走路径 A，代价是三个容器加两组 LLM 参数；已经有 Core 在跑、只想补面板和知识侧，走路径 B；要改 Panel 或 Knowledge 的构建、或者要自己控 tag，走路径 C 自建合并镜像；只要记忆网关这一个进程、不想碰 Panel 和 Proxy，走路径 D 的 Standalone；只想给现成的 agent 挂个记忆插件，走路径 G。

有几件事仓库没给答案，就别指望装完能有：ROADMAP 里列的五项（Agent 模版、mem: 指令扩展到 Task 维度、L1–L3 记忆可编辑、L0/L1 记忆搜索、Cursor 支持）都还没实现，且 ROADMAP_CN.md:7 开篇就写明路线图「不是承诺」。已发布的 mem: 指令只有 mem:sync / mem:create-skill [提示词] / mem:help 三个。README_CN.md:281-283 的注意事项也写着 Wiki 与 CodeGraph 是异步构建、CodeGraph 当前首先支持公开 HTTPS 仓库而私有仓库与 SSH 凭证仍在完善、全自动记忆路由仍在迭代。

最后一句关于凭据的，直接引 deploy/global-images/README.md:112-113 的原文：三个默认凭据「只适合个人本地跑通流程，生产/联调/公网暴露前必须替换成随机长串，否则任何拿到端口的人都能拿到 system_admin 权限」。考虑到这套系统采集并存储的是团队的对话、文档与代码，这条提醒的分量和别处不一样。要不要加防火墙、密钥怎么托管、数据放哪，属于通用运维范畴、不是该项目文档的内容，得按你自己的环境定。

延伸阅读

本文依据 TencentDB Agent Memory 官方仓库（github.com/TencentCloud/TencentDB-Agent-Memory） feat/server_team 分支上的 README、INSTALL、CHANGELOG、ROADMAP 与四个模块的源码整理， 核对日 2026-08-16，对应仓库快照 97f9465。该仓库的默认分支即为 feat/server_team。 本文内容为仓库源码与文档口径，我们没有部署、也没有运行过该项目的任何一个模块， 因此不涉及运行效果、检索质量与性能的任何描述。 该项目主模块处于 beta 阶段、其余模块版本号仍为 0.1.0，参数与接口随版本变动，请以仓库最新内容为准。 该项目会采集并存储团队的对话、文档与代码，属于敏感数据，是否使用请结合自身合规要求评估。 许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。 安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员