Docker 部署 TencentDB Agent Memory：给多个 AI Agent 搭一套共享记忆服务

同一个项目换到新会话，Agent 又要重新读文档、解释约束、踩一遍已经解决的坑。TencentDB Agent Memory 试图把这些重复成本变成可管理的资产：对话沉淀为 Chat Memory，工作方法整理成 Skill，文档编译成 Wiki，代码建立 CodeGraph，再按团队、用户和 Agent 分配访问权限。

TencentDB Agent Memory 已经不是早期的单容器实验。当前 v2.0.0 文档推荐同时运行 Memory Core、Memory Hub 和 Proxy；Hub 镜像内部还包含 Panel 与 Knowledge Service。部署能在一台机器上完成，但四个端口、两组 LLM 凭据、两个数据卷和一把 admin key 都需要照顾好。

资料核对时间：2026-08-28。仓库默认分支为 feat/server_team，本文锁定 commit 5299c00aaf65481703c180fd69df066d11254eb7。官方完整部署仍由 Shell 脚本组织三个容器；本文的正式 Compose 按该 commit 的 start-memory-core.sh、start-memory-hub.sh 和 start-proxy.sh 逐项派生，不冒充上游官方 Compose，也不声称已经完成运行验证。

配图占位：封面图（待生成）

标签：image-prompt gpt-image2 封面图 状态：待生成；生成图片后替换本区块，正文结构无需改动。

【gpt-image2 提示词 · 封面图】

为「用 Docker 部署 TencentDB Agent Memory：给多个 AI Agent 搭一套共享记忆服务」设计技术教程封面。

中心是一枚抽象化的分层记忆核心，分成 L0 对话、L1 原子、L2 场景、L3 画像四层；左侧是 Docker 鲸鱼和三个容器；右侧是多个不同形态的 AI Agent，共享 Chat Memory、Skill、Wiki、CodeGraph 四种资产；底部是服务器和两个加密数据卷。顶部预留标题区域，不生成文字，不使用真实 Logo。

16:9，现代克制的 2.5D 技术插画，主色 #2496ED 与 #0052D9，浅灰背景，清晰线条，避免赛博朋克、发光大脑、复杂粒子和人物照片。

项目速览

项目	当前信息
仓库	TencentCloud/TencentDB-Agent-Memory
GitHub 地址	TencentCloud/TencentDB-Agent-Memory
定位	面向 Agent 团队的共享记忆与知识资产中心
README 版本	v2.0.0
证据 commit	`5299c00aaf65481703c180fd69df066d11254eb7`（2026-08-27）
GitHub 数据	约 23.1k Stars / 2.1k Forks（2026-08-19）
License	MIT
官方镜像	Docker Hub 镜像组织 · `agentmemory/memory-core`、`agentmemory/memory-hub`、`agentmemory/memory-proxy`
正式部署	本文派生的完整三服务 Docker Compose；逐项对照固定 commit 的官方脚本
快速体验	不提供 `docker run` 单容器体验；Core、Hub、Proxy 和 admin 初始化缺一不可
支持架构	官方 `.env.example` 标注 `linux/amd64` 与 `linux/arm64`
默认端口	Core 8420、Panel 8125、Knowledge 8424、Proxy 8096
持久化	`tdai-memory-core-data`、`tdai-panel-data`、`.admin-key`
复杂度	L3，多服务 + 外部 LLM API

与普通向量库相比，TencentDB Agent Memory 多做了一层“资产治理”：记忆不只是检索结果，还带 Owner、Team、可见性、版本和 Agent 绑定。代价也很直接——组件更多、调用链更长，而且 Wiki、CodeGraph 和分层记忆会异步生成，不适合只想给单个脚本加一小段聊天历史的场景。

如果你只要一个简单的个人记忆库，SQLite 加轻量 API 会更省资源。TencentDB Agent Memory 更适合同时使用 Claude Code、Codex、CodeBuddy、OpenClaw 或其他 Agent，并希望这些客户端复用同一套团队知识的环境。

四个服务如何配合

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
    client["Claude Code / Codex / 其他 Agent"] -->|"8096"| proxy["Memory Proxy<br/>协议适配与记忆注入"]
    browser["管理员浏览器"] -->|"8125"| panel["Memory Panel<br/>团队与资产管理"]
    proxy --> core["Memory Core<br/>8420"]
    panel --> core
    panel --> knowledge["Knowledge Service<br/>8424"]
    knowledge --> core
    core --> coreData[("Core 数据卷<br/>SQLite 与记忆")]
    knowledge --> panelData[("Panel 数据卷<br/>Wiki 与 CodeGraph")]
    core -->|"Memory LLM"| memoryLlm["OpenAI / Anthropic 兼容端点"]
    proxy -->|"Proxy Upstream"| upstreamLlm["Agent 实际使用的上游模型"]

配图占位：完整部署架构图（待生成）

标签：image-prompt gpt-image2 完整部署架构图 状态：待生成；生成图片后替换本区块，正文结构无需改动。

【gpt-image2 提示词 · 架构部署图】

生成 TencentDB Agent Memory v2 Docker 部署架构信息图。左侧为 Claude Code、Codex、CodeBuddy 和浏览器；中间 Docker Host 内有三个容器：Memory Core、Memory Hub、Memory Proxy，Hub 容器内标出 Panel 与 Knowledge Service；标注端口 8420、8125、8424、8096。底部是 Core 数据卷和 Panel/Knowledge 数据卷；右侧分开画 Memory LLM 和 Proxy Upstream 两组外部模型端点。连接线区分客户端请求、记忆读写、知识加工和模型转发。

16:9，中文标签，PingFang SC，容器用圆角矩形，数据卷用圆柱体；Docker 蓝与腾讯蓝配色，背景 #F7F8FA，不添加 Redis，不使用真实 Logo。

两组 LLM 参数不要混为一谈：

MEMORY_LLM_* 供 Core 做记忆抽取，也供 Hub 生成 Wiki、总结知识。
PROXY_UPSTREAM_* 是 Agent 请求最终转发到的模型。两组可以使用同一家供应商，但用途不同。

官方当前的全局镜像部署是 standalone 状态后端，不需要额外 Redis。旧文档里的 Service 模式和 Redis 属于另一条部署路径，不要擅自加进 v2 本地三件套。

部署前先做三个决定

机器放在哪里

优先选一台长期在线的 Linux 主机。项目没有给出正式最低硬件表；三张 Node/Python 相关镜像再加知识索引任务，个人测试建议从 4 核 CPU、8 GB 内存、20 GB 空闲磁盘起步。这是运维余量估算，不是官方性能承诺。

bash

docker --version
git --version
curl --version
openssl version

官方脚本依赖 Bash、Docker、curl，并用 OpenSSL 生成随机 user key。verify.sh 还会检查四个端口和两组 LLM 通路。

哪些端口允许外部访问

单机使用时，只让本机访问最安全。局域网团队使用时，Panel 8125 和 Proxy 8096 可以放到 HTTPS 反向代理后；Core 8420 与 Knowledge 8424 应保留为内部管理和数据面端口。

官方脚本默认用 -p HOST:CONTAINER 绑定所有网卡。不要直接把 8420、8424、8096、8125 暴露到公网。仓库截至核对日仍有一条公开安全报告 #672，涉及 Proxy 管理端点鉴权和 Knowledge Git 抓取的 SSRF/参数注入风险；在修复版本得到确认前，应用层鉴权不能替代防火墙、VPN 和反向代理访问控制。

LLM 凭据怎么分组

准备两组 OpenAI 或 Anthropic 兼容参数：

text

Memory 组：BASE_URL + API_KEY + MODEL + PROTOCOL
Proxy 组：UPSTREAM_URL + API_KEY + MODEL

可以让两组都指向同一个端点。生产环境更适合用独立 Key，便于区分记忆加工费用和 Agent 正常对话费用。

Docker Compose 正式部署

上游没有完整三件套 Compose。下面配置保留官方脚本的容器名、网络别名、端口、卷、环境变量、Core/Proxy 配置和 admin 初始化顺序，同时把四个宿主机端口默认收紧到 127.0.0.1。这份 Compose 基于固定 commit 派生，已做静态解析，尚未拉取镜像或启动三容器栈。

准备目录和环境变量

bash

sudo mkdir -p /opt/tencentdb-agent-memory/config /opt/tencentdb-agent-memory/backups
sudo chown -R "$(id -u):$(id -g)" /opt/tencentdb-agent-memory
cd /opt/tencentdb-agent-memory
umask 077
touch .env

写入 /opt/tencentdb-agent-memory/.env，把两项 API key 换成受控凭据：

dotenv

MEMORY_CORE_IMAGE=agentmemory/memory-core:latest
MEMORY_HUB_IMAGE=agentmemory/memory-hub:latest
PROXY_IMAGE=agentmemory/memory-proxy:latest

MEMORY_LLM_BASE_URL=https://api.deepseek.com/v1
MEMORY_LLM_API_KEY=填入真实的Memory组密钥
MEMORY_LLM_MODEL=deepseek-chat
MEMORY_LLM_PROTOCOL=openai

PROXY_UPSTREAM_URL=https://api.deepseek.com/v1
PROXY_UPSTREAM_API_KEY=填入真实的Proxy组密钥
PROXY_UPSTREAM_MODEL=deepseek-chat

MEMORY_CORE_PORT=8420
PANEL_PORT=8125
KNOWLEDGE_PORT=8424
PROXY_PORT=8096
KNOWLEDGE_PUBLIC_BASE_URL=http://memory-hub:8424/v3
MEMORY_HUB_PROXY_PUBLIC_URL=http://127.0.0.1:8096
MEMORY_CORE_VOLUME=tdai-memory-core-data
PANEL_VOLUME=tdai-panel-data

MEMORY_CORE_GATEWAY_API_KEY 故意不放进文件：固定 commit 中 Proxy 的 auth/sessionInit 请求不会携带这层 Bearer。完整流水线必须保持 Core Bearer gate 关闭，并依靠本机端口绑定、防火墙和业务 user key 控制访问。执行 chmod 600 .env，不要提交或分享该文件。

生成 Core 与 Proxy 配置

保存为 /opt/tencentdb-agent-memory/render-config.sh。脚本使用与官方实现一致的主要配置项，并把两组 LLM 凭据写入权限收紧的 YAML：

bash

#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")"
set -a
source ./.env
set +a
umask 077
mkdir -p config

cat > config/core.yaml <<YAML
deployMode: standalone
stateBackend: local
server:
  port: 8420
  host: 0.0.0.0
data:
  baseDir: /data/tdai-memory
llm:
  baseUrl: "${MEMORY_LLM_BASE_URL}"
  apiKey: "${MEMORY_LLM_API_KEY}"
  model: "${MEMORY_LLM_MODEL}"
  maxTokens: 32000
  timeoutMs: 300000
memory:
  promptMode: chat
  capture: { enabled: true }
  extraction:
    enabled: true
    enableDedup: true
    maxMemoriesPerSession: 20
  persona:
    triggerEveryN: 50
    maxScenes: 15
  pipeline:
    everyNConversations: 5
    enableWarmup: true
    l1IdleTimeoutSeconds: 600
    l2DelayAfterL1Seconds: 90
    l2MinIntervalSeconds: 900
    l2MaxIntervalSeconds: 3600
  recall:
    enabled: true
    maxResults: 5
    scoreThreshold: 0.3
    strategy: hybrid
    timeoutMs: 5000
  storeBackend: sqlite
  embedding:
    provider: none
skill:
  enabled: true
  routing:
    mode: bm25
    searchTopK: 20
  extraction:
    enabled: true
    maxIterations: 16
    queue:
      backend: local
      keyPrefix: tdai
      resultTtlSeconds: 86400
      lockTtlMs: 600000
      maxRetries: 2
      retryBackoffsMs: [5000, 15000]
  resources:
    maxResourceSizeBytes: 5000000
YAML

cat > config/proxy.yaml <<YAML
server:
  host: 0.0.0.0
  port: 8096
  forwardTimeoutMs: 600000
upstream:
  url: "${PROXY_UPSTREAM_URL}"
  apiKey: "${PROXY_UPSTREAM_API_KEY}"
log:
  file: ""
  level: info
  backend: console
tdai:
  enabled: true
  endpoint: "http://memory-core:8420"
  apiKey: ""
  serviceId: default
  memory:
    enabled: true
    inject: true
    writeL0: true
    recallL1: true
    injectL2L3: true
skill:
  endpoint: "http://memory-core:8420"
  serviceToken: ""
auth:
  enabled: true
  url: "http://memory-core:8420"
  timeoutMs: 5000
sessionInit:
  enabled: true
  maxRetries: 3
  injectAgentContext: true
  injectTaskContext: true
  headerAutoSelect:
    enabled: true
    teamHeader: "x-team-id"
    agentHeader: "x-agent-id"
    taskHeader: "x-task-id"
    onMismatch: "form"
costGuard:
  enabled: false
injection:
  enabled: true
  injectors:
    - skill
    - knowledge
    - tdai-memory
redis:
  enabled: false
YAML

chmod 600 config/core.yaml config/proxy.yaml

bash

chmod 700 render-config.sh
./render-config.sh

每次修改 LLM 参数后都重新运行该脚本。官方脚本也是把变量插入双引号 YAML；若 URL、模型名或 key 含双引号、反斜杠或换行，先停止并改用能正确转义 YAML 的配置工具，不要直接运行本脚本。不要输出、提交或截图 config/core.yaml、config/proxy.yaml。

写入完整 Compose

保存为 /opt/tencentdb-agent-memory/compose.yaml：

yaml

services:
  memory-core:
    image: ${MEMORY_CORE_IMAGE:-agentmemory/memory-core:latest}
    container_name: tdai-memory-core
    restart: unless-stopped
    ports:
      - "127.0.0.1:${MEMORY_CORE_PORT:-8420}:8420"
    volumes:
      - memory-core-data:/data/tdai-memory
      - ./config/core.yaml:/data/config/tdai-gateway.yaml:ro
    environment:
      TDAI_GATEWAY_PORT: "8420"
      TDAI_GATEWAY_HOST: "0.0.0.0"
      TDAI_GATEWAY_API_KEY: ""
      TDAI_DATA_DIR: /data/tdai-memory
    networks:
      tdai-memory-stack:
        aliases:
          - memory-core

  memory-hub:
    image: ${MEMORY_HUB_IMAGE:-agentmemory/memory-hub:latest}
    container_name: tdai-memory-hub
    restart: unless-stopped
    depends_on:
      - memory-core
    ports:
      - "127.0.0.1:${PANEL_PORT:-8125}:8125"
      - "127.0.0.1:${KNOWLEDGE_PORT:-8424}:8424"
    volumes:
      - panel-data:/data/knowledge
    environment:
      PANEL_PORT: "8125"
      KNOWLEDGE_PORT: "8424"
      KNOWLEDGE_PUBLIC_BASE_URL: ${KNOWLEDGE_PUBLIC_BASE_URL}
      REMOTE_INSTANCE_ID: default
      REMOTE_INSTANCE_NAME: default
      REMOTE_INSTANCE_URL: http://memory-core:8420
      REMOTE_INSTANCE_KEY: local
      REMOTE_INSTANCE_PROXY_URL: ${MEMORY_HUB_PROXY_PUBLIC_URL}
      LLM_MODE: custom
      LLM_PROTOCOL: ${MEMORY_LLM_PROTOCOL:-openai}
      LLM_API_KEY: ${MEMORY_LLM_API_KEY}
      LLM_BASE_URL: ${MEMORY_LLM_BASE_URL}
      LLM_MODEL: ${MEMORY_LLM_MODEL}
      KNOWLEDGE_LLM_BINDING_SYNC: "0"
    networks:
      tdai-memory-stack:
        aliases:
          - memory-hub

  proxy:
    image: ${PROXY_IMAGE:-agentmemory/memory-proxy:latest}
    container_name: tdai-proxy
    restart: unless-stopped
    depends_on:
      - memory-core
      - memory-hub
    ports:
      - "127.0.0.1:${PROXY_PORT:-8096}:8096"
    volumes:
      - ./config/proxy.yaml:/data/config.yaml:ro
    networks:
      tdai-memory-stack:
        aliases:
          - proxy

volumes:
  memory-core-data:
    name: ${MEMORY_CORE_VOLUME:-tdai-memory-core-data}
  panel-data:
    name: ${PANEL_VOLUME:-tdai-panel-data}

networks:
  tdai-memory-stack:
    name: tdai-memory-stack

docker compose config 会展开环境变量，输出中可能包含 LLM key，不要把完整结果贴到 Issue 或聊天记录。

分阶段启动并初始化 admin

先只启动 Core，确认健康后生成随机 key。初始化接口返回 200 才继续；若返回 409，必须找回与当前 Core 数据卷匹配的旧 .admin-key，不能覆盖：

bash

cd /opt/tencentdb-agent-memory
docker compose config --quiet
docker compose pull
docker compose up -d memory-core
curl -fsS http://127.0.0.1:8420/health | jq .

umask 077
if [ -s .admin-key ]; then
  ADMIN_KEY="$(cat .admin-key)"
  HAD_ADMIN_KEY=1
else
  ADMIN_KEY="sk-mem-$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 32)"
  HAD_ADMIN_KEY=0
fi
HTTP_STATUS="$(curl -sS -o init-admin.json -w '%{http_code}' \
  -X POST http://127.0.0.1:8420/v3/internal/meta/user/init-admin \
  -H "Content-Type: application/json" \
  -H "x-tdai-service-id: default" \
  -d "$(jq -nc --arg username admin --arg user_key "$ADMIN_KEY" \
    '{username:$username,user_key:$user_key}')" )"
case "$HTTP_STATUS" in
  200)
    printf '%s' "$ADMIN_KEY" > .admin-key
    ;;
  409)
    if [ "$HAD_ADMIN_KEY" != "1" ]; then
      echo "admin 已存在，但缺少与当前 Core 卷匹配的 .admin-key" >&2
      exit 1
    fi
    ;;
  *)
    cat init-admin.json >&2
    exit 1
    ;;
esac

curl -fsS -X POST http://127.0.0.1:8420/v3/meta/auth/verify \
  -H "Content-Type: application/json" \
  -H "x-tdai-service-id: default" \
  -d "$(jq -nc --arg user_key "$(cat .admin-key)" '{user_key:$user_key}')" | jq .

docker compose up -d memory-hub
curl -fsS http://127.0.0.1:8424/health | jq .
docker compose up -d proxy
docker compose ps
rm -f init-admin.json

任一 HTTP 分支或 key 验证失败时都应停止后续步骤并检查 init-admin.json，不要删除卷重试。尤其是 409 分支，只有磁盘上的旧 .admin-key 能通过当前 Core 数据卷验证，才允许继续启动 Hub 和 Proxy。

官方 global-images 脚本对照

官方 README 当前仍推荐 deploy/global-images/start-all.sh。这份脚本依次执行三个 docker run，生成 Core/Proxy 配置、创建网络、初始化 admin，并保存随机 key。本文保留下面的脚本说明用于核对和问题定位；新部署的正式路径使用上一节 Compose，不要混用两套容器生命周期命令。

Mermaid 流程图

正在准备渲染...

查看源码

flowchart TD
    clone["克隆当前仓库"] --> env["复制并填写 .env"]
    env --> verify["运行 verify.sh"]
    verify --> check{"Docker、端口、LLM 通路正常"}
    check -->|"否"| fix["修复配置后重试"]
    fix --> verify
    check -->|"是"| core["启动 Memory Core"]
    core --> admin["初始化 admin 并保存 .admin-key"]
    admin --> hub["启动 Panel + Knowledge"]
    hub --> proxy["启动 Memory Proxy"]
    proxy --> health["检查四个服务与数据卷"]

配图占位：部署流程图（待生成）

标签：image-prompt gpt-image2 部署流程图 状态：待生成；生成图片后替换本区块，正文结构无需改动。

【gpt-image2 提示词 · 启动流程】

绘制 TencentDB Agent Memory 官方 global-images 部署流程：克隆仓库 → 复制 .env → 填写 Memory LLM 与 Proxy Upstream 两组配置 → verify.sh 检查 Docker、端口和 LLM → 启动 Core → init-admin 生成 .admin-key → 启动 Hub/Knowledge → 启动 Proxy → 四端口健康检查。异常分支返回日志和配置修复。

竖向 4:5 技术流程图，中文标签，正常节点蓝色，密钥与安全节点橙色，浅色背景，强调 .admin-key 与 Core 数据卷必须配套备份。

下载并锁定源码

bash

sudo mkdir -p /opt/tencentdb-agent-memory
sudo chown "$(id -u):$(id -g)" /opt/tencentdb-agent-memory
git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git /opt/tencentdb-agent-memory/repo
cd /opt/tencentdb-agent-memory/repo
git checkout 5299c00aaf65481703c180fd69df066d11254eb7
git rev-parse HEAD

把最后输出的 commit SHA 记进变更记录。仓库迭代很快，直接写“v2.0.0”不如保存实际 SHA 精确。

填写 `.env`

bash

cd /opt/tencentdb-agent-memory/repo/deploy/global-images
cp .env.example .env
chmod 600 .env

用编辑器替换所有 REPLACE_ME：

dotenv

MEMORY_CORE_IMAGE=agentmemory/memory-core:latest
MEMORY_HUB_IMAGE=agentmemory/memory-hub:latest
PROXY_IMAGE=agentmemory/memory-proxy:latest

MEMORY_LLM_BASE_URL=https://api.deepseek.com/v1
MEMORY_LLM_API_KEY=填入真实的Memory组密钥
MEMORY_LLM_MODEL=deepseek-chat
MEMORY_LLM_PROTOCOL=openai

PROXY_UPSTREAM_URL=https://api.deepseek.com/v1
PROXY_UPSTREAM_API_KEY=填入真实的Proxy组密钥
PROXY_UPSTREAM_MODEL=deepseek-chat

MEMORY_CORE_PORT=8420
PANEL_PORT=8125
KNOWLEDGE_PORT=8424
PROXY_PORT=8096

KNOWLEDGE_PUBLIC_BASE_URL=http://host.docker.internal:8424/v3
MEMORY_CORE_VOLUME=tdai-memory-core-data
PANEL_VOLUME=tdai-panel-data
MEMORY_CORE_GATEWAY_API_KEY=
MEMORY_CORE_ADMIN_USERNAME=admin

示例选择 DeepSeek 的 OpenAI 兼容端点，只是为了给出可落地的格式；换供应商时同时替换 URL、Key 和模型名。别把真实 .env 提交到 Git。

MEMORY_CORE_GATEWAY_API_KEY 当前要保持空值。官方模板说明 Proxy 的 auth/sessionInit 暂时不会向 Core 附带这层 Bearer，填入非空值会让完整流水线失效。这是已知兼容限制，不代表 Core 可以安全暴露公网。

预检再启动

bash

cd /opt/tencentdb-agent-memory/repo/deploy/global-images
./verify.sh
./start-all.sh

verify.sh 会真实请求两组 LLM 端点。如果你只想先检查 Docker、变量和端口，可用：

bash

./verify.sh --skip-llm

启动脚本会复用本地已有的 latest。想强制拉取远端最新镜像：

bash

PULL=1 ./start-all.sh

这里有个真实的坑：Issue #761 报告 v2.0.0 在 macOS + Podman/Docker Desktop 环境中可能卡在 init-admin，导致 Hub 与 Proxy 没启动。优先在 Linux Docker 上部署；若脚本只启动了 Core，先看 issue 对应修复是否已经合入你锁定的 commit，不要连续清卷重试。

检查服务是否真的起来

bash

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' \
  | grep -E 'tdai-memory-core|tdai-memory-hub|tdai-proxy'

curl -fsS http://127.0.0.1:8420/health | jq .
curl -fsS http://127.0.0.1:8424/health | jq .
curl -I http://127.0.0.1:8125/
curl -I http://127.0.0.1:8096/

日志按容器分开看，比盯着 start-all.sh 最后一行更可靠：

bash

docker logs --tail=200 tdai-memory-core
docker logs --tail=200 tdai-memory-hub
docker logs --tail=200 tdai-proxy

Panel 地址是 http://服务器IP:8125。首次登录所需的 admin key 在：

bash

cd /opt/tencentdb-agent-memory/repo/deploy/global-images
chmod 600 .admin-key
cat .admin-key

别把这把 key 发到群聊或写进截图。更合适的做法是用 admin 创建普通业务用户，再让 Agent 使用业务用户的 sk-mem-... key。

让 Claude Code 走 Proxy

start-all.sh 结束时会打印一组命令。手动配置时：

bash

cd /opt/tencentdb-agent-memory/repo/deploy/global-images
export ANTHROPIC_BASE_URL=http://127.0.0.1:8096/claude-code/default
export ANTHROPIC_AUTH_TOKEN="$(cat .admin-key)"
claude --model deepseek-chat

真正投入使用前，在 Panel 里至少创建一个 Team 和一个 Agent；Task 可以稍后补。生产使用不建议把 admin key 交给日常 Agent。

Codex、CodeBuddy 和其他客户端的 URL 前缀不同。以 Codex 为例，官方安装文档使用 http://127.0.0.1:8096/codex/default，并要求首次会话在 Plan 模式完成 Team → Agent → Task 选择。不要把 Claude Code 的 /claude-code/default 生搬到所有客户端。

Docker 快速体验（不提供）

完整服务依赖三个容器、两份动态配置和 admin 初始化，不适合压成单条 docker run。官方脚本的容器映射如下，只用于解释本文 Compose 的来源：

容器	镜像	端口	挂载
`tdai-memory-core`	`agentmemory/memory-core:latest`	`8420:8420`	`tdai-memory-core-data:/data/tdai-memory` + 只读 YAML
`tdai-memory-hub`	`agentmemory/memory-hub:latest`	`8125:8125`、`8424:8424`	`tdai-panel-data:/data/knowledge`
`tdai-proxy`	`agentmemory/memory-proxy:latest`	`8096:8096`	只读 `config.yaml`

三个容器加入 tdai-memory-stack 网络。Core 与 Proxy 的 YAML 是脚本按 .env 动态生成的，admin 初始化还包含随机 key 生成、409 处理和 /v3/meta/auth/verify 校验。手敲三条精简 docker run 会漏掉这些步骤，因此完整部署直接保留官方脚本更稳。

官方完整路径由 start-all.sh 生成并执行多条 docker run，包含动态配置、网络、admin 初始化和 key 校验；这套命令不适合直接复制粘贴，也不适合脱离官方脚本用于正式、长期或生产部署，更不能替代 Core-only Compose 开发路径。不要把 LLM key 放在命令行或 docker inspect 可见的位置，长期运行使用权限收紧的 .env、Docker secrets 或外部 Secret 管理。

官方 Core-only Compose 的适用边界

仓库的 MemoryCore/docker-compose.local.yaml 会构建本地 Core 并包含 Redis，官方命令是：

bash

cd /opt/tencentdb-agent-memory/repo/MemoryCore
export TDAI_LLM_API_KEY='在受控终端输入的密钥'
docker compose -f docker-compose.local.yaml config
docker compose -f docker-compose.local.yaml up --build -d
curl -fsS http://127.0.0.1:8420/health | jq .

这条 Compose 路径适合开发 Memory Core 或复现旧 Service 模式，不会自动得到 v2 的 Panel、Knowledge、Proxy、admin 初始化和 Agent 接入流程。

截至核对日，官方完整三件套仍由 deploy/global-images/start-all.sh 维护。本文正式 Compose 已同时保留动态 Core/Proxy YAML、admin key 生命周期和启动顺序；官方 Core-only Compose 仍只适合开发，不应与完整三件套混用。

国内镜像加速

三张镜像都在 Docker Hub。网络不稳定时，可以直接替换前缀：

bash

docker pull docker.1ms.run/agentmemory/memory-core:latest
docker pull docker.1ms.run/agentmemory/memory-hub:latest
docker pull docker.1ms.run/agentmemory/memory-proxy:latest

docker pull docker.m.daocloud.io/agentmemory/memory-core:latest
docker pull docker.1panel.live/agentmemory/memory-hub:latest
docker pull docker-0.unsee.tech/agentmemory/memory-proxy:latest

确认某个代理可用后，把 .env 中三项镜像完整改写：

dotenv

MEMORY_CORE_IMAGE=docker.1ms.run/agentmemory/memory-core:latest
MEMORY_HUB_IMAGE=docker.1ms.run/agentmemory/memory-hub:latest
PROXY_IMAGE=docker.1ms.run/agentmemory/memory-proxy:latest

公共代理可能临时不可用。腾讯云 CVM 可尝试仅腾讯云内网生效的 https://mirror.ccs.tencentyun.com；阿里云和华为云用户更适合使用自己账号下的专属加速地址。

全局 Registry 配置会影响宿主机上的所有容器，不在本文直接改写 /etc/docker/daemon.json。确需全局加速时，先读取现有 JSON，按云厂商文档合并 registry-mirrors 并验证 JSON；不要覆盖日志驱动、私有 Registry 或代理配置。

离线导入时三张镜像一起带走：

bash

docker save \
  agentmemory/memory-core:latest \
  agentmemory/memory-hub:latest \
  agentmemory/memory-proxy:latest \
  -o tencentdb-agent-memory-images.tar

docker load -i tencentdb-agent-memory-images.tar

固定镜像，别让 `latest` 悄悄变化

官方模板提醒：本地已有同名 latest 时，脚本会直接复用；PULL=1 才强制更新。生产部署应记录三个 RepoDigest：

bash

for image in \
  agentmemory/memory-core:latest \
  agentmemory/memory-hub:latest \
  agentmemory/memory-proxy:latest
do
  docker pull "$image"
  docker image inspect --format '{{index .RepoDigests 0}}' "$image"
done

把输出的 image@sha256:... 写进 .env。README 的 v2.0.0 是项目版本，不足以证明三张 latest 处于同一个构建批次；摘要才是可复现标识。

安全边界：HTTPS 与网络隔离

推荐流量路径：

text

团队成员 → VPN / HTTPS 反向代理 → Panel 8125、Proxy 8096
Docker 内部网络 → Core 8420、Knowledge 8424

官方脚本当前会发布四个端口。如果只在本机使用，可通过主机防火墙拒绝外部来源；团队部署则把 8125/8096 放到 Caddy 或 Nginx 后，8420/8424 仅允许 Docker 网段和运维机访问。

不要让反向代理把 .admin-key、.env、.memory-core-config/ 或 .proxy-config/ 当作静态文件目录。Knowledge 的 Git 导入功能需要访问外部仓库时，也应通过出站网络策略阻断云元数据地址和内网管理网段。

备份与恢复

需要一起备份三类状态：两个 Docker volume、宿主机的 .admin-key 与配置。Core 卷和 .admin-key 必须匹配；只恢复其中一个会导致 admin key 无法验证。

bash

cd /opt/tencentdb-agent-memory
mkdir -p backups
chmod 700 backups
docker compose stop

docker run --rm \
  -v tdai-memory-core-data:/data:ro \
  -v /opt/tencentdb-agent-memory/backups:/backup \
  alpine:3.22 \
  tar -czf /backup/core-$(date +%F).tar.gz -C /data .

docker run --rm \
  -v tdai-panel-data:/data:ro \
  -v /opt/tencentdb-agent-memory/backups:/backup \
  alpine:3.22 \
  tar -czf /backup/panel-$(date +%F).tar.gz -C /data .

tar -czf "/opt/tencentdb-agent-memory/backups/config-$(date +%F).tar.gz" \
  .env .admin-key config compose.yaml render-config.sh

docker compose up -d

恢复时先停止 Compose，把两个卷和配置归档恢复到同一时间点，再确认 .admin-key 与 Core 卷匹配；随后分阶段启动并重新执行 auth/verify。不要只恢复 key 或只恢复 Core 卷。

备份目录要提前创建并限制权限：

bash

sudo mkdir -p /opt/tencentdb-agent-memory/backups
sudo chown "$(id -u):$(id -g)" /opt/tencentdb-agent-memory/backups
chmod 700 /opt/tencentdb-agent-memory/backups

归档里含 LLM Key、admin key、原始对话和团队知识，敏感级别比普通数据库备份更高。至少做磁盘加密和离机副本访问控制。

更新与回滚

先阅读固定 commit 之后的变更和 Issues，再按上一节备份。确认新镜像后更新 .env 中三个摘要并拉取：

bash

cd /opt/tencentdb-agent-memory
docker compose pull
docker compose up -d
docker compose ps

更新完成要重新检查四个端口、admin 登录、业务用户登录、会话初始化和 L0→L1/L2/L3 后台任务。只看到容器运行不算升级成功。

回滚时恢复三张旧镜像摘要、与该 commit 匹配的两份 YAML，以及同一时间点的数据卷和 .admin-key。若版本包含数据迁移，先看官方迁移文档，别用旧镜像直接打开已经升级的数据卷。

常见问题

admin 初始化后 Hub 或 Proxy 没启动

bash

docker ps -a --format 'table {{.Names}}\t{{.Status}}'
docker logs --tail=200 tdai-memory-core
ls -l .admin-key
curl -fsS http://127.0.0.1:8420/health | jq .

检查 init-admin.json、.admin-key 与 Core 卷是否匹配，并核对 Issue #761 的修复状态。不要删除命名卷重试。

Hub 不健康或 Panel 提示 API 未启动

bash

docker logs --tail=200 tdai-memory-hub
curl -fsS http://127.0.0.1:8424/health | jq .

高频原因是 MEMORY_LLM_* 不可达、KNOWLEDGE_PUBLIC_BASE_URL 缺少 /v3，或 memory-hub 网络别名不可解析。

Agent 没有出现 Team / Agent / Task 选择

确认客户端使用 Proxy 8096，而不是 Core 8420。官方 start-all.sh 默认以 PROXY_FULL_STACK=1 打开 auth、sessionInit 和记忆注入；手动启动 Proxy 时缺少其中任何一项，都可能变成只转发模型请求。

L0 有数据，L1/L2/L3 长时间不增长

bash

curl -s http://127.0.0.1:8420/health | jq .services.pipelineWorker
docker logs --tail=300 tdai-memory-core | grep -Ei 'pipeline|extract|error|timeout'

普通对话用 MEMORY_PROMPT_MODE=chat。代码模式会更严格地筛选可沉淀内容；纯闲聊可能抽取 0 条。还要确认 Memory 组 LLM 的超时、额度和模型名都有效。

部署验证

本稿完成固定 commit 的官方文档、三个启动脚本、镜像名称、派生配置和完整 Compose 静态核对；当前未拉取镜像，也未实际启动完整三容器栈。部署后应逐项验证：

bash

docker compose ps
curl -fsS http://127.0.0.1:8420/health | jq .
curl -fsS http://127.0.0.1:8424/health | jq .
curl -I http://127.0.0.1:8125/
curl -I http://127.0.0.1:8096/

在 Panel 创建 Team、Agent 和 Task 后，从一个受控客户端发送测试请求；同时确认重启后两个数据卷、.admin-key 和配置仍能恢复。真实 LLM 调用、权限隔离和公网访问必须由用户在目标环境验收。

总结

本文按官方 commit 5299c00aaf65481703c180fd69df066d11254eb7 的三个启动脚本派生完整 Compose，并把端口默认限制到本机。当前结果仍停留在静态核对；正式投入使用前必须固定三张镜像摘要，验证 admin、四个 HTTP 入口和真实记忆闭环，并把两个数据卷、两份敏感配置与 .admin-key 纳入同一套恢复演练。

部署完成后

先在隔离的 Linux 测试机上完成一条最小闭环：创建业务用户、Team、Agent，发起一段真实工作对话，确认 L0 被记录、后台任务增长、Panel 能看到资产、下一次会话能召回。闭环跑通后再接入团队客户端、加 HTTPS、固定镜像摘要并演练一次双卷 + key 的恢复。

参考资料

项目仓库 - 核对日期：2026-08-28
固定 commit 5299c00a - 本文 Compose 的证据版本
官方中文安装指南 - 三件套、端口与初始化
Core 启动脚本 - Core 配置、卷与 admin 生命周期
Hub 启动脚本 - Hub 环境变量和端口
Proxy 启动脚本 - Proxy full-stack 配置
启动脚本问题 #761 - 2026-08-28 复核为 open
安全报告 #672 - 2026-08-28 复核为 open

Docker 部署 TencentDB Agent Memory：给多个 AI Agent 搭一套共享记忆服务 ​

项目速览 ​

四个服务如何配合 ​

部署前先做三个决定 ​

机器放在哪里 ​

哪些端口允许外部访问 ​

LLM 凭据怎么分组 ​

Docker Compose 正式部署 ​

准备目录和环境变量 ​

生成 Core 与 Proxy 配置 ​

写入完整 Compose ​

分阶段启动并初始化 admin ​

官方 global-images 脚本对照 ​

下载并锁定源码 ​

填写 .env ​

预检再启动 ​

检查服务是否真的起来 ​

让 Claude Code 走 Proxy ​

Docker 快速体验（不提供） ​

官方 Core-only Compose 的适用边界 ​

国内镜像加速 ​

固定镜像，别让 latest 悄悄变化 ​

安全边界：HTTPS 与网络隔离 ​

备份与恢复 ​

更新与回滚 ​

常见问题 ​

admin 初始化后 Hub 或 Proxy 没启动 ​

Hub 不健康或 Panel 提示 API 未启动 ​

Agent 没有出现 Team / Agent / Task 选择 ​

L0 有数据，L1/L2/L3 长时间不增长 ​

部署验证 ​

总结 ​

部署完成后 ​

参考资料 ​

Docker 部署 TencentDB Agent Memory：给多个 AI Agent 搭一套共享记忆服务

项目速览

四个服务如何配合

部署前先做三个决定

机器放在哪里

哪些端口允许外部访问

LLM 凭据怎么分组

Docker Compose 正式部署

准备目录和环境变量

生成 Core 与 Proxy 配置

写入完整 Compose

分阶段启动并初始化 admin

官方 global-images 脚本对照

下载并锁定源码

填写 `.env`

预检再启动

检查服务是否真的起来

让 Claude Code 走 Proxy

Docker 快速体验（不提供）

官方 Core-only Compose 的适用边界

国内镜像加速

固定镜像，别让 `latest` 悄悄变化

安全边界：HTTPS 与网络隔离

备份与恢复

更新与回滚

常见问题

admin 初始化后 Hub 或 Proxy 没启动

Hub 不健康或 Panel 提示 API 未启动

Agent 没有出现 Team / Agent / Task 选择

L0 有数据，L1/L2/L3 长时间不增长

部署验证

总结

部署完成后

参考资料