TencentDB Agent Memory 文档引用的部署文件：六处在快照里对不上

2026-08-16

按文档一步步敲命令，敲到某一行时它让你去改一个配置文件，而那个文件在仓库里根本没有——这大概是自建部署里最让人卡壳的一类问题。因为报错不会告诉你「文档写错了路径」，只会告诉你 No such file or directory，而你的第一反应通常是怀疑自己 clone 错了、切错了分支、或者少跑了某个生成脚本。

TencentDB Agent Memory 的仓库里就有这么一组引用。我们在 2026-08-16 取了 feat/server_team 分支的快照 97f9465（这个仓库的默认分支就是 feat/server_team，不是 main 也不是 master，后文所有路径都以这个分支为准），用 shell 的 [ -e ] 对文档里出现过的路径逐个判定了一遍。下面这些是判定结果，不是我们跑部署跑出来的结论——我们没有部署、没有构建镜像、没有启动过任何一个容器。

一、六条对不上的引用

先说清楚我们的计数口径：把「文档把它当作一个可以直接打开/挂载/apply 的部署相关文件来引用，但按该路径在快照里找不到」的算作一条。按这个口径数出来是六条。

#	文档里写的路径	引用出处	快照 `97f9465` 实况
1	`MemoryCore/tdai-gateway.service.yaml`	`README.docker.md:33,42,161,257`（多次引用）	不存在
2	`MemoryCore/tdai-gateway.real.yaml`	`README.docker.md:75,258`	不存在
3	`MemoryCore/docker-compose.local.yaml`	`README.docker.md:84,255`	不存在
4	`MemoryCore/deploy/k8s/tdai-memory.yaml`	`README.docker.md:184,259`	不存在
5	`MemoryCore/scripts/mock-shark-server.ts`	`README.docker.md:71,260`	不存在
6	`context_proxy/config.example.yaml`	`deploy/global-images/README.md:192`	该路径不存在；`MemoryProxy/config.example.yaml`（648 行）存在

前五条与第六条的性质不一样：前五条我们在仓库里没有找到对应文件；第六条是路径写法与仓库里的目录名对不上，文件本身能在另一个位置找到。context_proxy 这个名字在 MemoryKnowledge/docker-compose.yml 与 MemoryKnowledge/docker/env.example 的注释里也出现过多次，而 context-proxy 是 MemoryProxy/package.json 里的包名。这里只陈述差异，不推断原因。

另外还有两个 Python E2E 测试文件被 README.deployment.md:548,570 引用（__tests__/e2e/test_hermes_standalone_e2e.py 与 MemoryCore/__tests__/e2e/test_hermes_service_e2e.py），同样不在快照里。它们不是部署文件，所以没算进上面六条，但自查时顺手一起判定即可。

还有两个路径也不在快照里，但文档自己就说了它们不在：MemoryProxy/packages/cost-guard 与 MemoryCore/src/integrations。deploy/dockerhub/README.md:73-79 明确称这两者是私有可选模块，发布脚本会在临时构建上下文里生成 stub 包，运行时动态 import 失败就降级为直通转发。这属于文档与仓库口径一致的情况，别把它误当成缺文件。

二、照文档做会卡在哪一步

第 1、2、5 条集中在同一条路径上：MemoryCore 的 Service 模式。README.deployment.md:8-11 把部署形态分成 Standalone（SQLite + 本地文件）与 Service（TCVDB 向量库 + COS 对象存储 + Redis 分布式锁与任务队列），并写道两种形态「共享同一份 Gateway 二进制和同一套 v1/v2 HTTP API……切换形态只需调整 TDAI_DEPLOY_MODE 环境变量」。但 Service 形态要挂的那份配置模板 tdai-gateway.service.yaml 不在快照里。快照里存在的是 MemoryCore/tdai-gateway.standalone.yaml 与 MemoryCore/tdai-gateway.yaml。所以你会卡在「环境变量已经切到 service，但没有一份现成的 service 配置可抄」这一步。mock-shark-server.ts 同理——Shark 配置服务是 README.deployment.md 描述的 Service 模式外部依赖之一，那个 mock 脚本也不在。

第 3 条卡在本地起容器编排：docker-compose.local.yaml 不在 MemoryCore/ 下。快照里唯一存在的 compose 文件是 MemoryKnowledge/docker-compose.yml（service 名 knowledge，默认镜像 team-knowledge:latest，宿主端口默认 8421）。第 4 条卡在上 K8s：MemoryCore/deploy/k8s/ 这条路径下没有那份清单。

第 6 条卡的地方最轻：deploy/global-images/README.md:192 让你「参见 context_proxy/config.example.yaml」去看 proxy 的配置项，按这个路径打不开，换成 MemoryProxy/config.example.yaml 就能看到。

一个值得先确认的前提是：README 首推的三件套一键路径并不经过这六个文件。README_CN.md:36-42 给的四行命令是 clone 之后进 deploy/global-images、cp .env.example .env、填 LLM 参数、跑 ./start-all.sh，它依赖的是 deploy/global-images/ 下那一组脚本（start-all.sh 60 行、start-memory-core.sh 229 行、verify.sh 283 行等；整个 deploy/ 目录我们在这个快照上数出 17 个文件、2618 行）。也就是说，如果你走的是首推路径而卡住了，多半不是这六个文件的问题。

三、怎么确认是这个问题（可执行的判定动作）

第一步先确认分支和快照，因为路径判定的结论只对特定快照成立：

git rev-parse --short HEAD
git branch -a

第二步逐个判定文件是否存在。Linux / macOS 下：

for f in MemoryCore/tdai-gateway.service.yaml \
         MemoryCore/tdai-gateway.real.yaml \
         MemoryCore/docker-compose.local.yaml \
         MemoryCore/deploy/k8s/tdai-memory.yaml \
         MemoryCore/scripts/mock-shark-server.ts \
         context_proxy/config.example.yaml; do
  [ -e "$f" ] && echo "EXIST $f" || echo "MISS  $f"
done

Windows 的 PowerShell 里没有 [ -e ]，用 Test-Path 等价：

@(
 'MemoryCore/tdai-gateway.service.yaml',
 'MemoryCore/tdai-gateway.real.yaml',
 'MemoryCore/docker-compose.local.yaml',
 'MemoryCore/deploy/k8s/tdai-memory.yaml',
 'MemoryCore/scripts/mock-shark-server.ts',
 'context_proxy/config.example.yaml'
) | ForEach-Object { "{0} {1}" -f (Test-Path $_), $_ }

以上两段是按仓库里出现过的路径组合出来的自查片段，未经实测，以你本地 shell 的实际输出为准。另外要记得这个项目主模块还在 beta 阶段、默认分支是 feat/server_team 这样一个功能分支，路径与文档随版本变动，判定结论只对你手上那个快照成立。

第三步，如果你怀疑是自己 clone 不完整（比如 --depth 1、稀疏检出、或者中途断了），用 git ls-files 看仓库登记的文件而不是看工作区：

git ls-files | grep -i "gateway.*yaml\|docker-compose\|deploy/k8s"

git ls-files 列的是版本库里 tracked 的路径，工作区被误删也会暴露出来。作为对照，我们在这个快照上统计的 tracked 文件总数是 930（MemoryCore 347、MemoryPanel 220、MemoryProxy 176、MemoryKnowledge 74、sdk 44、assets 34、deploy 17、仓库根 13、.github 5）；数量级差很远就说明是你本地检出的问题，而不是文档引用的问题。

四、能接着往下走的落点

对第 6 条，直接改看 MemoryProxy/config.example.yaml 即可。对前五条，仓库里能找到的、性质相近的落点有这些（都是我们在快照里确认存在的文件）：

MemoryCore/tdai-gateway.standalone.yaml：Standalone 形态的网关配置，里面 memory.storeBackend: sqlite、memory.embedding.provider: none（:59,71-82），即默认不开向量、走 BM25 召回
MemoryCore/tdai-gateway.yaml
MemoryCore/src/gateway/server.ts：源码启动路径的入口，MemoryCore/README_CN.md:60-77 用 node --import tsx src/gateway/server.ts，README.deployment.md:26-38 用 npx tsx src/gateway/server.ts
MemoryProxy/config.example.yaml、MemoryKnowledge/openapi.yaml、MemoryPanel/scripts/secret-scan.sh、MemoryCore/scripts/ci/check-skill-queue-isolation.sh

需要明说的是：Standalone 的配置不是 Service 配置的替代品，两者依赖的外部组件不同（Service 侧文档写的是 Redis、TCVDB、COS、Shark）。我们没有去逐个验证 MemoryCore/src 里 deployMode: service 的代码路径是否完整，所以这里只能停在「文档描述了这套依赖，模板文件不在快照里」，不替你判断 Service 模式现在能不能跑通。项目也没有给出这份模板的替代来源，我们不编一份出来。

处置之后怎么验证？只验证到「路径能打开」为止：把上面那段判定脚本再跑一遍，确认你实际引用的那条路径返回 EXIST；再用 git ls-files 确认它是 tracked 的而不是你自己临时造的。是否真的能启动、健康检查是否通过，我们没有跑过，给不出结论。

五、什么情况说明不是这个原因

下面这些现象在仓库里另有出处，别往「文件缺失」上归因：

启动脚本报必填项缺失：start-all.sh:21-27 的 require_vars 校验 15 个必填项（三个镜像名、四个端口、两个卷名、三个 MEMORY_LLM_*、KNOWLEDGE_PUBLIC_BASE_URL、三个 PROXY_UPSTREAM_*），判定规则是「空或等于 REPLACE_ME」即算缺失（_lib.sh:34-49），而 .env.example 里这些值的默认字面量正是 REPLACE_ME。
端口对不上：Knowledge 在独立镜像里是 8421（MemoryKnowledge/Dockerfile:78,83），在合并镜像与三件套脚本里是 8424；Panel 独立镜像是 8123（Dockerfile.local:72），合并镜像是 8125。这是两套口径，不是缺文件。
改了 KNOWLEDGE_PORT 之后不通：deploy/global-images/README.md:162-171 要求 KNOWLEDGE_PUBLIC_BASE_URL 跟着改，且 .env.example:54-56 注释强调该 URL 必须含 /v3 前缀。
鉴权相关的怪现象：MEMORY_CORE_GATEWAY_API_KEY 在三处默认值不同（README 表格写 local、start-memory-core.sh:25 默认空、start-memory-hub.sh:26 与 start-proxy.sh:25 默认 local）；start-memory-core.sh:22-24 原文还写了 Bearer gate 与 proxy auth 存在「已知不兼容」。
YAML 字段名不认：README.deployment.md:112-114 的示例写 l1IdleTimeoutMs / l2IntervalMs / l3IntervalMs，而 MemoryCore/src/config.ts:67-82 的接口字段是 l1IdleTimeoutSeconds / l2DelayAfterL1Seconds / l2MinIntervalSeconds / l2MaxIntervalSeconds 等；全 MemoryCore/src grep，l2IntervalMs 与 l3IntervalMs 零命中。
找不到 README.docker.md:13 说的运行用户 tdai (uid 10001)：MemoryCore/Dockerfile（164 行）里没有 USER 指令，仓库里唯一有 USER 的是 MemoryProxy/Dockerfile:78,87（用户名 app，uid 10001）。这也是文档与 Dockerfile 的口径差异，同样只陈述、不延伸。

最后提醒两句版本口径。这个仓库的版本号本身在四处写法不同：CHANGELOG.md:12 最新条目是 2.0.1-beta.1，ROADMAP_CN.md:5 写当前版本 v2.0.1-beta.1，README_CN.md:299 写当前版本 v2.0.0，而 MemoryCore/package.json 是 2.0.0-beta.1；另外三个模块（MemoryKnowledge / MemoryPanel / MemoryProxy）的 package.json 版本都还是 0.1.0。主模块处于 beta 阶段、ROADMAP_CN.md:7 也声明路线图「不是承诺，范围与时间可能调整」。所以上面这份缺失清单只对 feat/server_team 分支的 97f9465 这一个快照成立——你自己拉下来第一件事，还是把那段判定脚本跑一遍。

延伸阅读

从头读起：TencentDB Agent Memory 是什么：团队级 Agent 记忆中枢怎么读
本专题共 40 篇，完整分组目录见专题页
TencentDB Agent Memory 的镜像用户：Dockerfile 里没有 USER 指令
TencentDB Agent Memory 是什么协议：三处口径各写一套

本文依据 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，参数与接口随版本变动，请以仓库最新内容为准。该项目会采集并存储团队的对话、文档与代码，属于敏感数据，是否使用请结合自身合规要求评估。安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。