TencentDB-Agent-Memory Docker 部署实战镜像构建、配置注入与 K8s 落地【免费下载链接】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导读本文以 README.docker.md 为骨架系统讲解 TencentDB-Agent-MemoryAI Agent 长期记忆服务的容器化部署全流程如何构建tencentdb-agent-memory镜像、如何通过 YAML 配置与环境变量注入 LLM/Redis/Shark 凭证、如何以 standalone / service 两种模式启动容器以及如何在 K8s/TKE 中用 ConfigMap Secret 完成生产级落地。读完本文你将掌握从本地一键测试到云端多副本部署的完整链路并理解镜像内部的分层构建原理与配置解析优先级。1. 项目与镜像概览TencentDB-Agent-Memory 是一个团队级的 AI Agent 长期记忆服务为任意 Agent 框架提供四层渐进式记忆能力L0 对话原始会话记录L1 原子记忆从对话中抽取的最小记忆单元L2 场景归纳对记忆进行场景化聚合L3 用户画像基于长期记忆沉淀的用户画像。官方提供 Docker 镜像tencentdb-agent-memory关键镜像信息如下项目值镜像名tencentdb-agent-memory基础镜像node:22-slim大小约 920MB端口8420运行用户tdai (uid 10001)PID 1tini其中PID 1 为 tini这一点值得注意tini 作为 init 进程能够正确转发 SIGTERM/SIGKILL 信号给 Node 主进程及其 pipeline worker并回收孤儿zombie进程保证优雅退出与资源清理。这一点在 MemoryCore/Dockerfile 的ENTRYPOINT [/usr/bin/tini, --]中直接体现。1.1 镜像构建的源码级实现镜像采用多阶段构建Multi-stage Build需DOCKER_BUILDKIT1这是镜像体积与构建速度的关键设计见 MemoryCore/Dockerfile阶段一deps-builder依赖安装基础镜像node:22-slim通过 apt 安装python3、make、g、ca-certificates等原生编译工具链用于编译sqlite-vec、node-rs/jieba等含原生绑定的依赖使用 BuildKit cache mount--mounttypecache,target/var/cache/apt缓存 apt 包加速重复构建升级 npm 到 11node:22-slim 自带 npm10.9.8 存在 arboristedgesOutcrash会稳定报Cannot read properties of null (reading edgesOut)对package.json做补丁删除peerDependenciesopenclaw、node-llama-cpp会拉入带坏workspace:*引用的传递依赖并添加overrides将jimp/config-typescript指向npm:dotenvlatest短路规避执行npm install --omitdev --omitoptional --ignore-scripts --legacy-peer-deps安装生产依赖单独安装esbuildtsx 的 optionalDependency--omitoptional后会丢失但 esbuild 仅约 10MB远小于被省略的 mongodb 等可选依赖。阶段二runtime运行镜像仅安装运行时必需品curl供 HEALTHCHECK 使用、tini、ca-certificates从 builder 阶段复制/build到/app创建数据目录/data/tdai-memory与配置目录/data/configK8s 中可挂载 PVC通过ENV预设运行参数NODE_ENVproductionTDAI_GATEWAY_CONFIG/data/config/tdai-gateway.yamlTDAI_GATEWAY_HOST0.0.0.0TDAI_DATA_DIR/data/tdai-memoryNODE_OPTIONS--max-old-space-size1536EXPOSE 8420HEALTHCHECK --interval30s --timeout5s --retries3 --start-period15s使用 curl 探测/health启动命令node --import tsx src/gateway/server.tstsx 为运行时依赖可直接运行 TypeScript。细节提示Dockerfile 注释特别说明TDAI_GATEWAY_PORT没有写入 ENV因为一旦成为镜像环境变量就会盖掉挂载配置中的server.port环境变量优先级高于 YAML而 8420 与 gateway 的代码默认值一致。1.2 .dockerignore 的安全设计MemoryCore/.dockerignore 除排除node_modules、.git、docs、*.md等常规内容外还主动排除所有根目录 yaml 配置tdai-gateway.yaml、tdai-gateway.*.yaml、.env等敏感文件注释明确指出生产走 env 注入或 volume 挂载——这是防止 Langfuse / VDB / API_KEY 等真值混入镜像的关键安全实践。2. 快速开始从构建到启动以下命令默认在MemoryCore/目录内执行如果你位于仓库根目录请先cd MemoryCore。2.1 构建镜像docker build -t tencentdb-agent-memory:latest .若在内网构建需要加速 apt 源可通过构建参数切换镜像源docker build --build-arg APT_MIRRORmirrors.tencent.com -t tencentdb-agent-memory:latest .Dockerfile 中ARG APT_MIRRORdeb.debian.org默认走 Debian 官方源公网可直接构建。2.2 准备配置文件项目提供两个配置模板详见 README.docker.md模板适用场景tdai-gateway.standalone.yaml本地开发、单机部署零外部依赖tdai-gateway.service.yamlK8s 多副本、多租户云服务复制模板并修改# 单机模式 cp tdai-gateway.standalone.yaml tdai-gateway.yaml # 服务模式 cp tdai-gateway.service.yaml tdai-gateway.yaml说明当前开源仓库中实际提供的是 MemoryCore/tdai-gateway.standalone.yamlstandalone 零依赖模板与 MemoryCore/tdai-gateway.yamlstandalone Skill 模块的默认配置。tdai-gateway.service.yaml为 README 文档描述的 service 模式模板按文档说明使用即可。.dockerignore中tdai-gateway.*.yaml规则也印证了这类模板文件的存在与命名习惯。模板间的核心差异tdai-gateway.standalone.yamldeployMode: standalone、stateBackend: local进程内状态管理不需要 Redis/Sharktdai-gateway.yaml同样 standalone 模式但额外启用了 Skill 模块skill.enabled: true且llm.baseUrl指向腾讯云https://api.lkeap.cloud.tencent.com/v1model 为deepseek-v3.2。Memory 引擎与 Skill 模块共享同一个baseDir互不干扰Memory 数据{baseDir}/conversations/、records/、scene_blocks/、persona.md…Skill 数据{baseDir}/skills/name/SKILL.mdfiles/共享 DB{baseDir}/vectors.db2.3 启动容器Standalone 模式最简docker run -d --name agent-memory \ -v $(pwd)/tdai-gateway.yaml:/data/config/tdai-gateway.yaml:ro \ -e TDAI_LLM_API_KEYsk-your-key \ -p 8420:8420 \ tencentdb-agent-memory:latest配置以只读:ro方式挂载到/data/config/tdai-gateway.yamlLLM API Key 通过环境变量TDAI_LLM_API_KEY注入避免写入配置或镜像端口映射 8420 对外提供服务。Service 模式需要 Redis# 启动 Redis如果没有远端 Redis docker run -d --name redis -p 6379:6379 redis:7-alpine # 启动 mock-shark本地提供 VDB/COS 凭证 VDB_ENDPOINThttp://your-vdb:8100 \ VDB_API_KEYxxx \ VDB_DATABASEyour-db \ COS_BUCKETyour-bucket \ COS_REGIONap-guangzhou \ COS_SECRET_IDxxx \ COS_SECRET_KEYxxx \ npx tsx scripts/mock-shark-server.ts # 启动 Memory Service docker run -d --name agent-memory \ -v $(pwd)/tdai-gateway.real.yaml:/data/config/tdai-gateway.yaml:ro \ -e TDAI_LLM_API_KEYsk-your-key \ -p 8420:8420 \ tencentdb-agent-memory:latestDocker Compose 一键启动含 RedisTDAI_LLM_API_KEYsk-your-key docker compose -f docker-compose.local.yaml up --build2.4 验证服务curl http://localhost:8420/health正常返回{ status: ok, version: 0.1.0, services: { timerScanner: { isLeader: true }, pipelineWorker: { workerId: worker-xxx }, stateBackend: connected } }该健康检查在容器内由 Dockerfile 的HEALTHCHECK指令以curl -fsS http://127.0.0.1:${TDAI_GATEWAY_PORT:-8420}/health自动执行也可手动 curl 验证。timerScanner定时扫描器、pipelineWorker流水线 worker、stateBackend状态后端连接状态三个字段分别对应 MemoryCore/src/services/timer-scanner.ts 与 MemoryCore/src/services/pipeline-worker.ts 两类后台任务。3. 配置方式YAML 环境变量双层体系3.1 配置文件 环境变量推荐所有配置项同时支持YAML 配置文件和环境变量环境变量优先级更高┌─────────────────────────────┐ │ 环境变量 (最高优先级) │ ← Secret 敏感凭证 ├─────────────────────────────┤ │ tdai-gateway.yaml 配置文件 │ ← ConfigMap 挂载 ├─────────────────────────────┤ │ 代码默认值 │ ← 兜底 └─────────────────────────────┘容器内配置文件路径由TDAI_GATEWAY_CONFIG环境变量指定默认/data/config/tdai-gateway.yaml。源码级佐证配置解析逻辑位于 MemoryCore/src/gateway/config.ts 的resolveConfigPath()函数其解析顺序为TDAI_GATEWAY_CONFIG环境变量显式指定的路径当前工作目录CWD下的./tdai-gateway.yaml或./tdai-gateway.jsondataDir/tdai-gateway.yaml或dataDir/tdai-gateway.json纯环境变量配置无文件。这意味着即使不挂载任何配置文件服务也能仅凭环境变量启动代码默认值兜底。3.2 配置文件结构详解以 standalone 模式为例结合 tdai-gateway.standalone.yaml 与 tdai-gateway.yaml 两个真实模板deployMode: standalone # standalone | service server: port: 8420 host: 0.0.0.0 llm: # LLM API (OpenAI 兼容) baseUrl: https://api.lkeap.cloud.tencent.com/v1 apiKey: ${TDAI_LLM_API_KEY} # 通过环境变量注入 model: deepseek-v3.2 maxTokens: 32000 # 最大 token 数 timeoutMs: 300000 # 请求超时毫秒 memory: promptMode: code # prompt 模式 capture: enabled: true # 对话捕获开关 extraction: enabled: true # L1 抽取开关 enableDedup: true # 去重 maxMemoriesPerSession: 20 # 每会话最大记忆数 persona: # L3 用户画像 triggerEveryN: 50 # 每 N 轮触发 maxScenes: 15 # 最大场景数 pipeline: # 记忆流水线 everyNConversations: 5 # 每 N 轮对话触发一次 enableWarmup: true # 预热 l1IdleTimeoutSeconds: 600 # L1 空闲超时 l2DelayAfterL1Seconds: 90 # L2 在 L1 后的延迟 l2MinIntervalSeconds: 900 # L2 最小间隔 l2MaxIntervalSeconds: 3600 # L2 最大间隔 recall: # 记忆召回 enabled: true maxResults: 5 # 最大召回条数 scoreThreshold: 0.3 # 分数阈值 strategy: hybrid # bm25 | embedding | hybrid timeoutMs: 5000 storeBackend: sqlite # sqlite零配置| tcvdb腾讯云向量数据库 embedding: # 向量搜索 provider: none # 默认关闭仅用 BM25 # provider: openai # model: text-embedding-3-small # dimensions: 1536 bm25: enabled: true language: zh skill: # Skill 模块standalone.yaml 中默认关闭 enabled: true routing: mode: bm25 # bm25 | embedding | hybrid searchTopK: 20 extraction: enabled: true maxIterations: 16 # Review Agent 最大迭代轮数 resources: maxResourceSizeBytes: 5000000 # 单个资源文件上限 5MB redis: # Redis (service 模式必需) host: redis:6379 keyPrefix: tdai_memory shark: # Shark 配置中心 (下发 VDB/COS 凭证) baseUrl: http://shark:8000 scanner: # Timer Scanner intervalMs: 500 worker: # Pipeline Worker pollMs: 200其中deployMode、server、llm、redis、shark、scanner、worker、memory等为 README 文档给出的 service 模式骨架maxTokens、timeoutMs、capture/extraction/persona/pipeline/recall调参项、storeBackend、embedding、bm25、skill等则来自仓库实际提供的两个配置模板可直接复制使用。Skill 模块提示在 tdai-gateway.yaml 中skill.enabled: true且skill.extraction.enabled: true需要顶层llm配置有效skill.routing.mode若为embedding/hybrid需要启用memory.embedding否则自动降级为bm25。3.3 环境变量与配置文件对照表环境变量YAML 路径默认值说明TDAI_DEPLOY_MODEdeployModestandalone部署模式TDAI_GATEWAY_CONFIG—/data/config/tdai-gateway.yaml配置文件路径TDAI_LLM_API_KEYllm.apiKey—LLM API KeyTDAI_LLM_BASE_URLllm.baseUrlhttps://api.openai.com/v1LLM 地址TDAI_LLM_MODELllm.modelgpt-4o模型名REDIS_HOSTredis.host127.0.0.1Redis 地址REDIS_PORTredis.port6379Redis 端口REDIS_PASSWORDredis.password—Redis 密码REDIS_KEY_PREFIXredis.keyPrefixtdai_memoryKey 前缀SHARK_BASE_URLshark.baseUrl—Shark 地址STATE_BACKENDstateBackend自动redis/localSCANNER_INTERVAL_MSscanner.intervalMs500扫描间隔WORKER_POLL_MSworker.pollMs200Worker 轮询COS_DOMAINcos.domain—COS 内网域名使用原则敏感凭证API Key、Redis 密码等一律走环境变量注入非敏感配置端口、扫描间隔、调参项等写入 YAML 并通过 ConfigMap 挂载。环境变量优先级更高因此也常用于在不动配置文件的前提下临时覆盖。4. K8s / TKE 部署README 文档给出 K8s/TKE 部署的核心做法参考清单MemoryCore/deploy/k8s/tdai-memory.yaml该文件位于文档描述的部署目录中ConfigMap挂载tdai-gateway.yaml到/app/config/Secret通过环境变量注入TDAI_LLM_API_KEYREDIS_PASSWORDDeployment设置TDAI_GATEWAY_CONFIG/data/config/tdai-gateway.yaml。Deployment 中的关键配置片段env: - name: TDAI_GATEWAY_CONFIG value: /data/config/tdai-gateway.yaml - name: TDAI_LLM_API_KEY valueFrom: secretKeyRef: name: tdai-memory-secrets key: TDAI_LLM_API_KEY volumeMounts: - name: config-volume mountPath: /app/config readOnly: true volumes: - name: config-volume configMap: name: tdai-memory-config与镜像设计的呼应镜像内TDAI_GATEWAY_CONFIG默认值为/data/config/tdai-gateway.yaml而示例中 ConfigMap 挂载到/app/config、环境变量又显式指定/data/config/tdai-gateway.yaml——这正是 3.1 节环境变量优先级最高的实际应用显式指定挂载路径避免默认值路径下找不到配置配置文件只读挂载readOnly: trueSecret 走secretKeyRef引用符合.dockerignore中生产走 K8s Secret env template的注释约定镜像中已预设HEALTHCHECKcurl 探测/healthK8s 的 liveness/readiness probe 可在 Deployment 清单中单独定义数据目录/data/tdai-memory可作为 PVC 挂载保证多副本/重启后记忆数据持久化Dockerfile 注释明确TDAI_GATEWAY_PORT不写入 ENV因此 service 模式下挂载配置中的server.port不会被镜像级环境变量覆盖。5. API 概览容器启动后暴露以下核心接口详见 README.docker.md方法路径说明GET/health健康检查POST/recall记忆召回POST/capture写入对话POST/search/memoriesL1 记忆搜索POST/search/conversationsL0 对话搜索POST/session/end结束会话POST/v2/*v2 多租户 API需 Bearer Token这些接口对应 MemoryCore/src/gateway/server.ts 服务入口/health返回进程与依赖状态供 K8s probe 与curl验证/capture与/recall对应 L0→L1 的记忆写入与召回/search/memories、/search/conversations分别检索 L1 原子记忆与 L0 对话/v2/*为多租户 API需 Bearer Token 鉴权。6. 架构总览README 文档给出容器内架构图┌─────────────────────────────────────────────────────┐ │ TencentDB Agent Memory │ │ │ │ ┌──────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │ Gateway │ │ TimerScanner │ │ PipelineWorker│ │ │ │ HTTP API │ │ 500ms 扫描 │ │ 竞争消费 │ │ │ └────┬─────┘ └──────┬───────┘ └──────┬────────┘ │ │ │ │ │ │ │ ┌────▼─────────────────────────────────▼────────┐ │ │ │ IStateBackend (Redis / Local) │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ ┌────▼───────────┐ ┌────────────┐ ┌───────────┐ │ │ │ TdaiCore │ │ StorePool │ │ COS │ │ │ │ L0→L1→L2→L3 │ │ VDB 连接池 │ │ 对象存储 │ │ │ └────────────────┘ └────────────┘ └───────────┘ │ └─────────────────────────────────────────────────────┘ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ │ LLM │ │ TCVDB │ │ COS │ │ API │ │ 向量库 │ │ 对象存储│ └─────────┘ └─────────┘ └─────────┘关键组件解析GatewayHTTP API对外提供第 5 节所列接口是请求入口TimerScanner以scanner.intervalMs默认 500ms间隔扫描负责定时触发流水线任务PipelineWorker以worker.pollMs默认 200ms轮询消费任务多实例时竞争消费配合 Redis 实现任务互斥IStateBackendRedis / Local状态后端抽象standalone 用 local进程内service 用 Redis多副本共享状态TdaiCoreL0→L1→L2→L3核心记忆引擎完成对话→原子记忆→场景归纳→用户画像的渐进式加工StorePoolVDB 连接池管理腾讯云向量数据库TCVDB连接对应配置中的storeBackend: tcvdb与memory.tcvdb段COS对象存储存放对话原文、记忆内容等大对象对应cos.domain、COS_BUCKET等配置外部依赖 LLM API、TCVDB、COS 通过配置注入standalone 模式下仅 LLM 为必需外部依赖。7. 文件结构速览与容器化部署直接相关的文件以 README.docker.md 文件结构说明为准. ├── MemoryCore/ │ ├── Dockerfile # 镜像构建 │ ├── docker-compose.local.yaml # 本地一键测试 (含 Redis) │ ├── tdai-gateway.standalone.yaml # Standalone 配置模板 │ ├── tdai-gateway.service.yaml # Service 配置模板 │ ├── tdai-gateway.real.yaml # 本地测试配置 (连真实服务) │ ├── deploy/k8s/tdai-memory.yaml # K8s/TKE 部署清单 │ ├── scripts/mock-shark-server.ts # Mock Shark (本地开发) │ └── src/gateway/server.ts # 服务入口部署提示docker-compose.local.yaml、tdai-gateway.real.yaml、deploy/k8s/与scripts/mock-shark-server.ts按文档描述属于部署配套资源注意 MemoryCore/.dockerignore 将deploy目录与scripts/mock-shark-*脚本排除在镜像构建之外即 mock-shark 等仅用于宿主机本地开发调试不会进入生产镜像。镜像内的核心代码包括 MemoryCore/src/gateway/server.ts服务入口与 MemoryCore/src/gateway/config.ts配置解析。8. 部署模式选型建议维度StandaloneService适用场景本地开发 / Hermes sidecar / 单 Agent 单机部署K8s 多副本、多租户云服务外部依赖仅 LLM APIRedis状态共享 Shark凭证下发 VDB/COS状态后端local进程内redis跨副本共享配置模板tdai-gateway.standalone.yamltdai-gateway.service.yaml启动方式docker run一条命令docker compose 或 K8s Deployment敏感凭证TDAI_LLM_API_KEYenvenv K8s Secret生产落地的推荐路径本地先用 standalone SQLite 验证记忆链路capture → recall需要团队共享、多副本时切换到 service 模式部署 Redis通过 Shark 下发 TCVDB/COS 凭证启用storeBackend: tcvdb与向量搜索K8s/TKE 上以 ConfigMap 管理非敏感配置、Secret 管理凭证PVC 持久化/data/tdai-memory用 liveness/readiness probe 保障健康巡检。结语从 README.docker.md 出发结合 MemoryCore/Dockerfile、MemoryCore/.dockerignore、MemoryCore/tdai-gateway.standalone.yaml、MemoryCore/tdai-gateway.yaml 与 MemoryCore/src/gateway/config.ts 的实现细节你可以看到这套容器化体系的设计逻辑多阶段构建控制体积与安全、双层配置体系分离敏感与非敏感信息、tini HEALTHCHECK 保证容器级健康、standalone/service 双模式适配从本地到云端的不同形态。按本文步骤操作即可在几分钟内跑通一条构建镜像 → 本地验证 → K8s 落地的完整部署链路。【免费下载链接】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），仅供参考