TencentDB Agent Memory 安装使用教程 — Windows / Linux / macOS 三平台

本文最后更新于：2026年8月7日下午

项目简介

TencentDB Agent Memory 是腾讯云开源的 Agent 记忆框架（MIT 协议），解决的核心问题是：怎样减少使用 Agent 时的重复工作——项目背景不用换个 Session 再讲一遍、文档不用每个 Agent 从第一页重读、跑通的做法不用下次再摸索。

1	`已有信息 → 可复用记忆资产 → 更少 Turns → 更少返工 → 更稳定的结果`

记忆分层：L0 原始对话 → L1 Atom → L2 Scene → L3 Persona，逐层沉淀
Chat Memory 保留偏好/事实/决策；Skill 自动从对话提炼可复用操作方法；Wiki + CodeGraph 建立文档和代码的知识地图
与 Agent 框架解耦，支持 Claude Code / CodeBuddy / Hermes / OpenClaw 及任意 OpenAI 兼容客户端

三件套架构

服务	容器名	宿主机端口	用途
Memory Core	tdai-memory-core	`8420`	记忆读写、鉴权、skill/RAG 数据面
Memory Hub（Panel + Knowledge）	tdai-memory-hub	`8125` / `8424`	团队记忆管理面板 / Wiki、CodeGraph 服务
Proxy	tdai-proxy	`8096`	LLM 请求代理（Anthropic / OpenAI 双协议），coding agent 的 API 入口

镜像发布在 Docker Hub 的 agentmemory 命名空间（memory-core / memory-hub / memory-proxy），多架构 amd64 + arm64，公开可拉无需登录。

前置要求

平台	Docker	shell	推荐方式
Linux	docker-ce / docker.io	bash	原生跑脚本
macOS	Docker Desktop / OrbStack / colima 任一	bash（macOS 自带 3.2 可跑）	原生跑脚本
Windows	Docker Desktop（WSL2 backend）	WSL2 内 bash（推荐）/ Git Bash	WSL2 里跑脚本；纯 PowerShell 只能 docker run 单组件

git、curl
一组可用的 LLM API Key（OpenAI 兼容或 Anthropic 协议，如 DeepSeek）
端口 8420 / 8125 / 8424 / 8096 空闲

安装：完整三件套（推荐）

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
cp .env.example .env
$EDITOR .env    # 填两组 LLM 参数
./verify.sh     # 干跑校验（可选，会做 LLM 通路预检，--skip-llm 跳过）
./start-all.sh  # 一键拉起三件套

Linux

# Ubuntu/Debian（任选一种 Docker）
sudo apt update && sudo apt install -y docker.io docker-compose-plugin git
sudo systemctl enable --now docker
# 或官方 docker-ce 源：https://docs.docker.com/engine/install/ubuntu/

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
cp .env.example .env
$EDITOR .env
./verify.sh
./start-all.sh

macOS

安装 Docker Desktop（或更轻量的 OrbStack / colima），然后把 Docker Desktop 启动起来，其余步骤与 Linux 完全一致：

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
cp .env.example .env
$EDITOR .env
./verify.sh
./start-all.sh

macOS 自带 bash 3.2 即可运行脚本；Docker Desktop 原生支持 host.docker.internal。

Windows

官方脚本是 bash 写的，Windows 上推荐用 WSL2 + Docker Desktop 跑全套：

# 1) WSL2 里装 Ubuntu，Windows 上装 Docker Desktop 并启用 WSL2 backend
# 2) 进入 WSL2 终端：
sudo apt update && sudo apt install -y git
# （Docker Desktop 的 WSL2 backend 会让 WSL 里直接有 docker 命令）

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
cp .env.example .env
$EDITOR .env
./verify.sh
./start-all.sh

WSL2 会自动把容器端口转发到 Windows 宿主，浏览器直接访问 http://localhost:8125 即可
备选：Git Bash + Docker Desktop 也能跑脚本（脚本探测宿主机 IP 的 hostname -I 在 Git Bash 下可能失效，会自动回落 localhost，单机使用无影响）
纯 PowerShell/CMD：只能执行”只装 Memory Hub”的 docker run 单组件命令，无法跑 start-all.sh

.env 配置

两组独立 LLM 参数，可以相同，也可以完全不同（比如 memory 组用便宜模型做 embedding，proxy 组用强模型做主对话）：

变量	说明	示例
`MEMORY_LLM_BASE_URL`	memory + hub 内部用（embed/summarize、wiki ingest）	`https://api.deepseek.com/v1`
`MEMORY_LLM_API_KEY`	上述端点 Key	`sk-xxxxxxxx`
`MEMORY_LLM_MODEL`	模型 ID	`deepseek-chat`
`MEMORY_LLM_PROTOCOL`	`openai` 或 `anthropic`，默认 `openai`	`openai`
`PROXY_UPSTREAM_URL`	proxy 转发到的上游 base URL	`https://api.deepseek.com/v1`
`PROXY_UPSTREAM_API_KEY`	转发用 Key（可与 memory 组不同）	`sk-xxxxxxxx`
`PROXY_UPSTREAM_MODEL`	面向用户的模型 ID	`deepseek-chat`
`MEMORY_CORE_PORT` / `PANEL_PORT` / `KNOWLEDGE_PORT` / `PROXY_PORT`	端口，冲突时改这里	`8420` / `8125` / `8424` / `8096`
`KNOWLEDGE_PUBLIC_BASE_URL`	knowledge 外部可达地址，必须含 `/v3` 前缀	`http://host.docker.internal:8424/v3`

参数缺失时脚本会在启动前一次性列出所有缺失项并 exit 1，不会跑到一半才失败
verify.sh 默认预检两组 LLM 通路：OpenAI 兼容协议只请求 GET {base}/models（不消耗 token）；Anthropic 协议发 max_tokens=1 最小消息（≤10 token）；容器已运行时还会从容器内 exec curl 验证”容器 → LLM”可达性（企业代理/DNS 隔离环境下宿主机可达但容器不可达的情况能提前暴露）
⚠️ 安全：脚本默认 MEMORY_CORE_GATEWAY_API_KEY=local、admin 用户 key 为 admin，只适合个人本地跑通。生产/联调/公网暴露前必须换成随机长串，否则任何拿到端口的人都能拿到 system_admin 权限

启动完成后脚本自动生成 admin 用户，user_key 随机 32 位持久化到 ./.admin-key，并打印一段可直接 export + claude 的运行命令。

使用：让 Claude Code 用上团队记忆

第 1 步：登录管理面板

浏览器打开 http://localhost:8125，用 deploy/global-images/.admin-key 里那串 sk-mem-... 登录。

admin 是”运维口”：管用户、建团队，也能用 Wiki / CodeGraph / Skill 等资产管理功能
推荐隔离：用 API 建一个业务用户（面板「用户」→「新建」等价）：

ADMIN_KEY=$(cat ./.admin-key)
curl -sS -X POST http://localhost:8420/v3/meta/user/create \
  -H "x-tdai-user-key: $ADMIN_KEY" \
  -H "x-tdai-service-id: default" \
  -H "Content-Type: application/json" \
  -d '{"username":"you"}' | jq

返回体里 data.default_user_key（sk-mem-...）就是新用户登录 key，只显示这一次，保存好。之后面板退出登录，用新 key 重新登录，业务用户是”应用口”用来建资产。

注：2.0.0-beta.1 中 admin 不能拥有业务资产；2.0.0 正式版起 admin 也可以直接操作资产。

第 2 步：建 Team / Agent / Task

Coding agent 用记忆必须落到具体 team / agent / task 三元组上：

Team：面板左侧「团队」→ 新建。一组资产的归属容器（memory、skill、knowledge 都归 Team）
Agent：进入 Team → 「Agent」→ 新建。填 description + system prompt 作为角色说明（如 bug-fix 工程师、SQL 优化师）
Task（可选）：Team → 「任务」→ 新建。本次工作的抓手（如「修复登录页 XSS」）；不建也能用，但 L2/L3 会缺 Task 维度

先建至少 1 个 Team + 1 个 Agent。

第 3 步：CC 走 Proxy

1
2
3

export ANTHROPIC_BASE_URL=http://127.0.0.1:8096/claude-code/default
export ANTHROPIC_AUTH_TOKEN="<业务用户的 sk-mem-...>"
claude --model <PROXY_UPSTREAM_MODEL 里配的上游模型>

ANTHROPIC_BASE_URL 把 CC 的 API 改指到本机 proxy；路径里 default 是 memory 实例 ID（本地部署固定叫 default）
ANTHROPIC_AUTH_TOKEN 用业务用户的 user_key，proxy 会拿它去 core 反查 user_id，只有该用户 own 的 team/agent/task 会出现在表单里
--model 用 .env 里 PROXY_UPSTREAM_MODEL 配的上游模型名

第 4 步：新会话选 Team → Agent → Task

每开一个新的 CC 会话，proxy 用 CC 自带的 AskUserQuestion 工具弹出 3 个连续选择（Team → Agent → Task，Task 可选，箭头选择回车确认）。选完后：

proxy 记住本次会话的 team/agent/task 绑定，同一次 claude 进程内多轮不再询问
后续每一轮请求自动把该 agent 的 L2/L3 记忆、skill、knowledge 注入 system prompt
L0 原始对话自动落到 memory-core 的 SQLite；满足触发条件时后台跑 L1 → L2 → L3
想切换 team/agent：起一个新的 claude 会话即可重新弹表单

第 5 步：观察记忆生成

面板左侧「记忆」→ Chat Memory：看 L0 原始对话切分成的 scene
「Agent」详情页 → Profile：L2 scene 与 L3 persona 逐步累积
「Skill」列表：对话里 LLM 判定”可复用的操作方法”会自动抽出 skill
后台 pipeline 干活情况：

1 2	`curl -s http://localhost:8420/health \| jq .services.pipelineWorker # 期望 tasksConsumed / tasksCompleted 随对话增长`

其他 Agent 接入

CodeBuddy

⚠️ 版本限制：4.10.2 / 4.10.3 / 4.10.4 有 Bug（请求不携带 sessionId，Proxy 无法完成 Session 初始化），请用 ≥ 4.10.5 或 ≤ 4.10.1。

编辑 ~/.codebuddy/models.json：

{
  "models": [
    {
      "id": "claude-sonnet-4-20250514",
      "name": "proxy-memory-agent",
      "vendor": "claude",
      "apiKey": "<业务用户的 sk-mem-... user_key>",
      "maxInputTokens": 200000,
      "url": "http://127.0.0.1:8096/codebuddy/default",
      "supportsToolCall": true,
      "supportsImages": true
    }
  ]
}

id 必须与 proxy 上游支持的模型 ID 匹配；apiKey 用业务用户 user_key（不建议直接使用 admin key）；url 是 proxy 地址 + /codebuddy/default。配置后在对话框选择该模型即可，Session init 流程与 Claude Code 一致。

Hermes

编辑 ~/.hermes/config.yaml：

model:
  default: gpt-5.5
  provider: custom
  base_url: http://<proxy-host>:<port>/hermes/<spaceId>
  api_key: <从面板获取的 API Key>
  extra_headers:
    x-team-id: <从面板获取的 team_id>
    x-agent-id: <从面板获取的 agent_id>
    x-task-id: <从面板获取的 task_id>
    x-conversation-id: <自定义的会话标识>

base_url：proxy 地址 + /hermes/<spaceId>，spaceId 是 memory 实例 ID（本地通常为 default）
api_key：业务用户的 user_key（面板「API Key」页获取）
x-task-id：当前版本必填，缺少会导致 session 注册失败、记忆不生效（见下方已知限制）

OpenClaw

编辑 ~/.openclaw/openclaw.json，在 models.providers 中添加：

{
  "models": {
    "mode": "merge",
    "providers": {
      "memory-proxy": {
        "baseUrl": "http://<proxy-host>:<port>/openclaw/<spaceId>",
        "apiKey": "<从面板获取的 API Key>",
        "api": "openai-completions",
        "headers": {
          "x-team-id": "<从面板获取的 team_id>",
          "x-agent-id": "<从面板获取的 agent_id>",
          "x-task-id": "<从面板获取的 task_id>",
          "x-conversation-id": "<自定义的会话标识>"
        },
        "request": { "allowPrivateNetwork": true },
        "models": [
          {
            "id": "gpt-5.5",
            "name": "GPT-5.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 32000,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          }
        ]
      }
    }
  }
}

models[].id 必须与 proxy 上游配置的模型 ID 匹配。

通用接入（任意 OpenAI 兼容平台）

把平台的 API base URL 指向 Proxy，请求 path 自动拼接 /v1/chat/completions（OpenAI）或 /v1/messages（Anthropic）：

1	`http://<proxy-host>:<port>/<agent-source>/<spaceId>`

<agent-source> 必须为 claude-code / codebuddy / hermes / openclaw 之一（其他平台可伪装成其中一个接入），<spaceId> 本地固定 default。

必须携带的 Header（缺一不可，Proxy 通过 header 直接完成 session 注册，跳过交互式表单）：

Header	说明
`Authorization: Bearer <key>`	业务用户 API Key
`x-team-id`	团队 ID
`x-agent-id`	Agent ID
`x-task-id`	任务 ID（当前版本必填）
`x-conversation-id`	会话标识，客户端自行生成管理

只装 Memory Hub（已有 Core）

已有 Memory Core 跑在本机 8420 时，单命令拉起面板（此命令在 Windows PowerShell / CMD 也能直接跑）：

docker pull docker.io/agentmemory/memory-hub:latest
docker run -d --name tdai-memory-hub \
  --add-host=host.docker.internal:host-gateway \
  -p 8125:8125 -p 8424:8424 \
  -v tdai-panel-data:/data/knowledge \
  -e REMOTE_INSTANCE_URL=http://host.docker.internal:8420 \
  -e REMOTE_INSTANCE_KEY=local \
  -e KNOWLEDGE_PUBLIC_BASE_URL=http://host.docker.internal:8424/v3 \
  -e LLM_MODE=custom \
  -e LLM_BASE_URL=<OPENAI_COMPATIBLE_BASE_URL> \
  -e LLM_API_KEY=<YOUR_API_KEY> \
  -e LLM_MODEL=<MODEL_ID> \
  docker.io/agentmemory/memory-hub:latest

打开 http://localhost:8125。

常见问题

问题	排查
CC 会话没有弹选择表单	`start-all.sh` 默认已开 `PROXY_FULL_STACK=1`；若手动改过或 `PROXY_FULL_STACK=0` 起的，重启：`PROXY_FULL_STACK=1 ./start-proxy.sh`
表单选项为空/只有别人的 team	确认当前账号已创建过 Team 和 Agent（业务用户需在对应 team 下建过 Agent）
面板显示”Panel API 8125 未启动”	`docker ps` 看 `tdai-memory-hub` 是否 healthy；不 healthy 看 `docker logs tdai-memory-hub`（大概率 `REMOTE_INSTANCE_URL` / `LLM_BASE_URL` 配错）
L1/L2 一直没跑，records/ 没东西	默认 `promptMode=chat`；若配了 `code` 而对话是闲聊，LLM 会认为没有可沉淀内容返回 0。改回 `chat` 或做真实工作对话（改文件、跑测试、给结论）
`./start-all.sh` 卡在 wait_healthy	镜像还在拉取，先 `docker pull agentmemory/memory-core:latest` 等手动预拉
proxy 转发 401	`PROXY_UPSTREAM_API_KEY` 无效或 `PROXY_UPSTREAM_URL` 不匹配，`docker logs tdai-proxy` 看错误
端口冲突	在 `.env` 改 `MEMORY_CORE_PORT` 等四个端口，`KNOWLEDGE_PUBLIC_BASE_URL` 跟着 `KNOWLEDGE_PORT` 改
想接宿主机上的 Ollama/Langfuse	脚本已默认 `--add-host=host.docker.internal:host-gateway`，容器内用 `http://host.docker.internal:<port>`

停止 / 清理

1 2	`./stop-all.sh # 停容器，保留 volume 数据 & admin key ./stop-all.sh --purge # 连 volume、admin key、proxy config 一起清`

数据持久化在 named volume：tdai-memory-core-data（记忆 SQLite）、tdai-panel-data（knowledge SQLite / wiki 文件），docker volume rm 前一直保留。

已知限制（当前版本）

x-task-id 在 Hermes / OpenClaw 场景下必填：header 预选机制要求 team + agent + task 三者齐全才能完成 session 直接注册，否则 session bypass，记忆注入和对话回流都不生效。需要预先在面板创建 Task 并获取 task_id，切换任务时要手动改配置。下个版本将支持可选（自动选默认 task 或跳过绑定）
x-conversation-id 需静态配置：Hermes / OpenClaw 在配置文件中指定，同一 conversation ID 的所有请求共享同一 session；每次开新对话需手动更换 ID，否则沿用上次 session 状态；部分客户端 tool call 后续请求可能不携带 extra headers，导致那些轮次跳过记忆注入

#Claude Code #TencentDB #Agent Memory #Docker #团队记忆 #AI 编程

TencentDB Agent Memory 安装使用教程 — Windows / Linux / macOS 三平台

https://kingjem.github.io/2026/08/07/TencentDB-Agent-Memory-三平台安装使用教程/

作者

Ruhai

发布于

2026年8月7日

许可协议

mise 使用教程 — 在 Linux/macOS 上管理 Node/Python 多版本下一篇