TencentDB Agent Memory 部署指南｜开源 AI Agent 分层长期记忆框架本地部署与接入手册

腾讯云数据库团队开源的 AI Agent 团队级分层长期记忆框架：把对话、任务、文档与代码沉淀为可管理、可审核、可配装给指定 Agent 的记忆资产，支持三件套 Docker 一键部署、独立 Memory Hub、Proxy 接入 Claude Code 等 8 类客户端，以及轻量插件、独立容器与 TypeScript SDK。

1 项目简介

1.1 项目定位与开源信息

TencentDB Agent Memory 是腾讯云数据库团队开源、面向 AI Agent 团队的分层长期记忆框架，主语言为 TypeScript，采用 MIT 协议发布。项目解决三类重复劳动：同一背景不换会话就要重复讲解、已有文档不被每个 Agent 从头重读、一套跑通的做法下次仍需重新摸索。框架把对话、任务、文档与代码沉淀为可管理、可审核、可配装给指定 Agent 的记忆资产；记忆资产与具体 Agent 框架解耦，可跨框架迁移，也可在团队内多个 Agent、多名成员之间共享与维护。

仓库当前默认分支为 feat/server_team；截至 2026 年 10 月 25 日上午查询时点，GitHub 仓库 Star 数为 29,889、Fork 数为 2,899。本文所有命令、端口与环境变量名均以该分支官方文件为准。

1.2 核心能力

• Chat Memory：保留偏好、事实、决策与交互历史；每个 Agent 创建时自动获得独立记忆，下次对话不必从自我介绍开始。
• Skill 技能库：Agent 完成复杂工作后，可从对话与工具调用中提炼、管理可复用 Skill；Skill 不只是一段 Prompt，它包含版本、资源文件、触发边界、执行步骤与验证规则。个人 Skill 默认私有，审核后可分享给团队，再配装给其他 Agent。
• Wiki 知识库：把产品文档、设计方案与运维手册生成结构化页面与链接图谱，Agent 可搜索、可沿链接下钻，不必先读完所有文件目录再开工。
• CodeGraph 代码图谱：索引代码符号、文件、调用关系与影响路径；Agent 可搜索、阅读、查询调用方与被调用方，也可以在改代码前先做影响面分析。
• 分层生长：对话首先作为 L0 保存，再由异步 Pipeline 提炼为不同粒度的记忆；平时用 L2、L3 快速进入语境，需要具体事实时再通过 BM25、向量检索与 RRF 回到 L1、L0，并受条数、字符预算与超时限制约束，避免记忆反过来占满上下文。
• 资产治理：统一登记 Owner、版本、状态、可见性、使用次数与 Agent 绑定；可见性分为 private（仅 Owner）、team（全队可见）、restricted（经 User / Role / Agent ACL 精确授权）与 agent。
• 冷启动友好：可导入已有文档、代码库与 Agent 历史 Session，新 Agent Team 从现有经验开始工作，不必从头学习。
• 本地优先：默认使用 SQLite + sqlite-vec，零外部依赖；MongoDB 数据面为试验特性，默认关闭。

1.3 公开评测

项目官方 README 披露的基准测试为 PersonaMem：无 TencentDB Agent Memory 时为 48%，启用后为 76%，相对提升 +59%。该基准检验 Agent 能否在长期交互后正确理解并运用用户信息。基准结果与任务类型、模型、提示词及上下文配置相关，仅代表官方测试条件下的表现，不构成对任意工作流的通用效果承诺；接入前建议用自身工作流做小样本验证。

1.4 技术架构

框架不追求存下所有东西，而是解决三个问题：什么值得留下、谁可以使用、下一次怎样少拿但拿对。对话、任务、文档与代码库先沉淀为 L0 至 L3 分层记忆以及 Skill、Wiki、CodeGraph 等记忆资产，统一登记到 Memory Hub，由 Hub 完成绑定、ACL 与版本管理，再按身份装配给具体 Agent，如图 1 所示。

▲ 图 1 技术实现总览：分层沉淀、记忆资产、Memory Hub 与按身份装配到 Agent

记忆按四个层级逐层生长，各层级保存内容与主要用途如表 1 所示。

表 1 L0 至 L3 分层记忆说明

▲ 图 2 L0 至 L3 分层记忆金字塔（官方英文原图，层级中文对照见表 1）

▲ 图 3 符号结构、摘要索引与事实证据之间的可追溯下钻链

知识不整库注入，而是按需调用：文档被整理为可搜索、可沿链接下钻的 Wiki；代码库被索引为包含文件、符号与调用关系的 CodeGraph。Agent 先通过 /v3/tools/list 发现能力，再通过 /v3/tools/call 读取相关页面、源码或影响路径；文档与代码因此也成为记忆，但平时只是可用工具，只有真正需要时才进入上下文。

2 资源下载与官方跳转

2.1 下载渠道

项目提供源码、Docker 镜像、npm 插件包与 TypeScript SDK 等多种获取方式，渠道与说明如表 2 所示。

表 2 下载渠道一览

2.2 官方文档与社区跳转

官方文档、API 说明、路线图与社区入口如表 3 所示，接入排障时优先查阅对应官方页面。

表 3 官方文档与社区入口

2.3 版本与协议信息

• 开源协议：MIT，版权归属 Tencent，允许在遵守协议前提下自由使用与二次开发。
• 运行环境门槛按形态区分：三件套 Docker 形态宿主机仅需 Docker；插件或源码形态需要 Node.js ≥ 22.16；接入 OpenClaw 插件还要求 OpenClaw ≥ 2026.3.13。
• 版本口径：三件套镜像当前标签为 latest 与 1.0.3-beta.1；仓库最新 Release 为 v2.0.3-beta.1；npm 插件包为 1.0.3；TypeScript SDK 为 1.0.0。各包发布节奏独立，接入前请以仓库 README 与 npm 页面标注为准。

3 部署前准备

3.1 环境要求

表 4 三件套部署环境要求

3.2 组件与端口

三件套由 memory-core、memory-hub 与 proxy 三个容器组成，组件、容器名、镜像、端口与用途如表 5 所示。

表 5 三件套组件、端口与用途

3.3 存储后端与数据持久化

默认存储为 SQLite，零外部依赖，数据落在命名卷中；MongoDB 数据面是试验特性，默认关闭，不建议作为生产默认后端。两个默认数据卷如表 6 所示。

表 6 默认数据持久化卷

说明：执行 docker volume rm 之前数据一直保留；切换 SQLite 与 MongoDB 后端不会迁移已有数据，需要先自行备份并手工迁移。

4 部署方式一：三件套 Docker 一键部署（推荐）

4.1 获取源码

方式一：使用 Git 克隆仓库。

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git

方式二：从 2.1 节给出的源码 ZIP 链接下载压缩包并解压，效果与克隆一致。

4.2 进入部署目录

cd TencentDB-Agent-Memory/deploy/global-images

4.3 编写 .env 配置

start-all.sh 在 .env 不存在时会自动从 .env.example 复制一份；也可以手动执行 cp .env.example .env 后再编辑。memory 组参数供 memory-core 与 memory-hub 内部调用 LLM 使用，如表 7 所示。

表 7 memory 组 LLM 参数

proxy 组参数供 proxy 把用户请求转发到上游 LLM 使用，如表 8 所示。

表 8 proxy 组上游参数

• 两组参数可以填相同值，都指向同一个 LLM；也可以完全不同，例如 memory 组使用成本较低的模型做 embedding 与总结，proxy 组使用较强模型做主对话。
• 脚本启动前会一次性列出所有缺失参数并退出，不会跑到一半才失败；填写后立即检查 LLM 通路：OpenAI 兼容协议请求 GET {base}/models，只验证 URL 与 Key，不消耗 token；Anthropic 协议请求 POST {base}/v1/messages，发送 max_tokens=1 的最小消息，消耗不超过 10 token。

记忆提示词模式由 MEMORY_PROMPT_MODE 控制：code 为默认值，面向代码工程、团队协作，抽取项目事实、任务、决策、SOP 与禁忌，产物为 Team Operating Doctrine；chat 面向个人对话、教学与闲聊，抽取 persona、episodic 与 instruction 类记忆，产物为 persona.md。code 模式下纯闲聊可能抽出 0 条记忆，此时应先检查提示词模式是否与对话场景匹配。

端口与对外地址沿用默认值即可；如与本地已有服务冲突，可在 .env 中修改。KNOWLEDGE_PUBLIC_BASE_URL 必须包含 /v3 前缀，缺失会导致 Panel 报错。

表 9 端口与对外地址变量

内部凭据与安全提醒

• MEMORY_CORE_GATEWAY_API_KEY 留空时关闭 Bearer 网关，属于本地零配置体验；KNOWLEDGE_SERVICE_KEY 留空时首次启动自动生成 ks-svc-* 随机串并写回 .env，重启复用；MEMORY_CORE_ADMIN_USERNAME 默认值为 admin。
• 上述默认值只适合个人本地跑通流程。生产环境、联调环境或公网暴露前，必须替换为随机长串凭据，否则任何拿到端口的人都可能获得 system_admin 权限。

4.4 启动脚本与交互流程

在部署目录执行启动命令：

./start-all.sh

脚本为交互式，运行时依次完成以下步骤：

• .env 不存在时自动从 .env.example 复制一份；
• 引导填写两组 LLM 参数，回车即保留当前默认值；
• 填完立即检查 LLM 通路，不通会提示重新输入，直到通过或主动放弃；
• 把填写值写回 .env 持久化，下次启动默认复用；
• 通过后依次拉起 memory-core（等待 healthy）、memory-hub（等待 healthy）与 proxy。
• 拉取远端最新镜像：PULL=1 ./start-all.sh；本地已存在同名 latest 时脚本默认复用，不会自动感知远端更新。

可选干跑校验：只检查环境与通路，不启动容器。

./verify.sh              # 默认全检，含 LLM 通路预检
./verify.sh --skip-llm   # 离线环境跳过 LLM 检查

4.5 启动后核验

• Panel UI：http://localhost:8125
• Knowledge Swagger 接口调试页：http://localhost:8424/docs
• Memory Gateway：http://localhost:8420
• Proxy：http://localhost:8096

首次启动时 init-admin 生成 admin 用户，user_key 为随机 32 位，持久化到 deploy/global-images/.admin-key（sk-mem-... 前缀），同一数据卷下每次重启复用；脚本结尾会打印一段可直接 export 后启动 Claude Code 的命令。

健康检查与后台 Pipeline 状态查询命令如下：

curl http://localhost:8420/health
curl -s http://localhost:8420/health | jq .services.pipelineWorker

第二条命令中 tasksConsumed 与 tasksCompleted 数字应随着对话逐步增长，表示后台记忆抽取 Pipeline 正在工作。

4.6 单独启动组件

三个脚本可单独执行，便于调试或只需要部分能力，如表 10 所示。

表 10 独立组件启动脚本与依赖关系

任意组件缺失时脚本会给出 warn 提醒，但不阻塞启动。

5 部署方式二：独立部署 Memory Hub

适用前提：本机已经运行 memory-core 并监听 8420 端口（即已有 Memory Core）。此时可以只拉取 Memory Hub 镜像，单独打开团队记忆面板。先拉取镜像：

docker pull docker.io/agentmemory/memory-hub:latest

随后执行以下命令启动 Panel 与 Knowledge Service：

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

• REMOTE_INSTANCE_URL 指向本机已有的 memory-core；REMOTE_INSTANCE_KEY=local 对应本地默认网关凭据。
• KNOWLEDGE_PUBLIC_BASE_URL 必须包含 /v3；LLM_MODE=custom 配合 LLM_BASE_URL、LLM_API_KEY、LLM_MODEL 供 hub 内部总结使用。
• 启动完成后访问 http://localhost:8125 打开面板。

6 部署方式三：通过 Proxy 接入各类 Agent

三件套启动后，coding Agent 只需把 API base URL 指向 proxy 即可接入团队记忆，无需为每个 Agent 安装插件、Hook 或 MCP 服务。本章以 Claude Code 为例给出完整五步流程，其余客户端配置要点见 6.7 节。

6.1 登录管理面板与权限模型

浏览器打开 http://localhost:8125，使用 .admin-key 中的 admin user_key 登录。先理解两层权限模型，后续步骤才不会走错：

• admin 是运维口：负责创建 Team、创建用户、把用户拉进 Team 等组织管理操作；面板上「新建团队」「新建用户」的入口只有 admin 可见。
• 业务用户是应用口：在被 admin 加入的 Team 内管理 Agent、Task、Skill、Wiki、CodeGraph 与记忆资产，并用自己的 user_key 启动 Claude Code 等 coding Agent。
• 单机本地体验也建议遵循该分层，不要直接用 admin key 跑客户端。

6.2 管理员创建团队与业务用户（推荐隔离）

当前版本面板没有独立的「用户管理」菜单，创建业务用户的入口挂在某个 Team 的成员管理中，因此顺序是先由 admin 建好 Team，再在该 Team 里创建业务用户，这一步只能由 admin 完成。

• 用 admin 登录后，点击左上角 Team 切换器（顶栏显示当前团队名的下拉），在面板底部选择「+ 新建团队」，填写团队名后创建；该入口仅 admin 可见。
• 进入该 Team 的「成员管理」，点击右上角「添加成员」。
• 在弹窗中把方式切换为「新建用户并加入团队」，填写用户名（仅英文字母、数字、下划线），点击「新建并添加」；需要指定初始 key 时可打开「自定义 User_Key」开关。
• 创建成功后弹窗会一次性显示该用户的 user_key（sk-mem-...），务必当场复制保存，面板之后不会再展示完整值。

上述流程也可以通过 API 完成，且必须分两步：user/create 仅创建账号，不会加入任何 Team；随后再调用 team-member/add 把用户加入团队。两个接口均需要 admin 或团队 admin 权限，使用普通业务用户 key 调用会返回 permission_denied。

ADMIN_KEY=$(cat ./.admin-key)

# 第 1 步：创建用户（仅建账号，不加入任何团队），记下返回的 user_id 与 default_user_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

# 第 2 步：把上一步的 user_id 加入已存在的 Team，role 一般填 member
curl -sS -X POST http://localhost:8420/v3/meta/team-member/add \
  -H "x-tdai-user-key: $ADMIN_KEY" \
  -H "x-tdai-service-id: default" \
  -H "Content-Type: application/json" \
  -d '{"team_id":"<TEAM_ID>","user_id":"<上一步返回的 user_id>","role":"member"}' | jq

只执行第 1 步只会建出一个不属于任何团队的用户，它无法在面板中被自己管理，也进不了会话表单；必须接着执行第 2 步才等价于面板的「新建用户并加入团队」。

完成后退出 admin 登录，使用新业务用户的 key 重新登录，即可在已加入的 Team 内管理资产。

6.3 建立 Team、Agent 与 Task

coding Agent 使用记忆必须落到具体的 team、agent、task 三元组上：

• Team（团队）：一组资产的归属容器，memory、skill、knowledge 都归 Team 所有。
• Agent（智能体）：进入 Team 后在「Agents 管理」中新建，填写清晰的 description 与 system prompt 作为角色说明，例如 bug-fix 工程师、前端评审 Agent、SQL 优化师。
• Task（任务，可选）：在 Team 的「任务看板」中新建，对应一次具体工作，例如修复登录页 XSS、上线 v1.4 灰度。

不建 Task 也能使用，但当 Team 内 Task 为 0 且未配置 sessionInit.defaultTaskId 时，交互式 session-init 会进入 bypass；需要「本次不关联任务」入口时按 6.8 节配置默认任务。

6.4 将 Claude Code 指向 Proxy

方式一：使用环境变量启动。

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

方式二：写入 ~/.claude/settings.json 的 env 字段持久化，启动时自动加载。

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<业务用户的 sk-mem-... user_key>",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8096/claude-code/default",
    "ANTHROPIC_MODEL": "<PROXY_UPSTREAM_MODEL 中配置的上游模型>"
  }
}

• ANTHROPIC_BASE_URL 把 Claude Code 的 API 从 anthropic.com 改指到本机 proxy；路径中的 default 是 memory 实例 ID（x-tdai-service-id），本地部署固定为 default。
• ANTHROPIC_AUTH_TOKEN 使用业务用户的 user_key；proxy 据此反查 user_id，只有该用户 own 的 team、agent、task 才会出现在下一步表单中。
• --model 或 ANTHROPIC_MODEL 使用 .env 中 PROXY_UPSTREAM_MODEL 配置的上游模型名，proxy 会把请求转发到 PROXY_UPSTREAM_URL。

6.5 首次会话选择 Team、Agent 与 Task

每开启一个新的 Claude Code 会话，proxy 通过 Claude Code 自带的 AskUserQuestion 工具依次弹出 Team、Agent、Task 三个连续选择；选项超过 3 个时自动分页，每页 3 个真实选项加 1 个「更多」翻页项。使用方向键选择、回车确认即可。

• 选完之后，proxy 记住本次会话的 team、agent、task 绑定；后续每一轮请求，proxy 自动把该 Agent 的 L2、L3 记忆、skill 与 knowledge 注入 system prompt。
• L0 原始对话默认落到 memory-core 的 SQLite；启用 MongoDB 试验后端后落到 MongoDB；满足触发条件时后台依次执行 L1 抽取、L2 场景聚合与 L3 画像生成。
• 只有新会话才会弹表单，同一 claude 进程内的多轮不会再次询问；在任意一步输入「跳过」或「skip」可跳过该步，跳过后 proxy 透传请求，不注入资产。
• 想切换到其他 team 或 agent，需要新开一个 Claude Code 会话，新会话会重新弹出选择表单。

6.6 观察记忆逐层生长

完成一段工作后，可在面板中检查记忆沉淀结果：

• 左侧「记忆」→ Chat Memory：查看 L0 原始对话被切分出的 scene。
• Agent 详情页 → Profile：查看该 Agent 的 L2 scene 与 L3 persona 逐步累积情况。
• Skill 列表：对话中被 LLM 判定为可复用操作方法的内容会自动抽出并保存。
• 使用 4.5 节的 pipelineWorker 探针命令，确认后台抽取任务持续消费与完成。

6.7 其余 Agent 客户端接入一览

Proxy 当前支持 8 类 AI Agent 客户端，各客户端配置文件、会话初始化方式与独立文档如表 11 所示。

表 11 支持的 Agent 客户端与配置入口

Proxy 处理链路依次为：auth 校验 user_key → sessionInit 选择 team、agent、task → injection 把 L2、L3 记忆、skill、knowledge 注入 system prompt → 转发到上游 LLM。执行 PROXY_FULL_STACK=0 ./start-proxy.sh 可关闭完整流水线，仅做透传。

Hermes 通过 ~/.hermes/config.yaml 配置，示例如下：

model:
  default: gpt-5.5
  provider: custom
  base_url: http://<proxy-host>:8096/hermes/default
  api_key: <业务用户的 sk-mem-... user_key>
  default_headers:
    x-team-id: <从面板获取的 team_id>
    x-agent-id: <从面板获取的 agent_id>
    x-task-id: <从面板获取的 task_id>
    x-conversation-id: <自定义的会话标识>

OpenClaw 通过 ~/.openclaw/openclaw.json 的 models.providers 段配置，示例如下：

{
  "models": {
    "mode": "merge",
    "providers": {
      "memory-proxy": {
        "baseUrl": "http://<proxy-host>:8096/openclaw/default",
        "apiKey": "<业务用户的 sk-mem-... user_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": "<上游模型 ID>", "name": "Model",
          "reasoning": false, "input": ["text"]
        }]
      }
    }
  }
}

OpenClaw 默认禁止请求内网地址，allowPrivateNetwork: true 用于允许访问 127.0.0.1 或内网 IP 上的 proxy；models[].id 必须与 proxy 上游配置的模型 ID 匹配。

6.8 当前版本已知限制

• x-task-id 在 Hermes / OpenClaw 场景下必填：Proxy 的 Header 预选机制要求 x-team-id、x-agent-id、x-task-id 三者齐全才能完成 session 直接注册；缺少 x-task-id 时 proxy 会尝试弹出交互式表单，但 Hermes 与 OpenClaw 无法响应表单，最终导致 session bypass，记忆注入与对话回流均不生效。需要先在面板创建 Task 并获取 task_id，切换任务时手动修改配置文件；后续版本计划支持 x-task-id 可选。
• x-conversation-id 需手动管理：Hermes 与 OpenClaw 在配置文件中静态指定该 ID；同一个 conversation ID 的所有请求共享同一个 session，每次开启新对话需要手动更换，否则会沿用上次 session 状态；部分客户端 tool call 后续请求可能不携带 extra headers，对应轮次会跳过记忆注入与对话回流。
• 可选免任务绑定：在 proxy config.yaml 的 sessionInit 段配置 defaultTaskId（start-proxy.sh 生成的模板已包含该段），会话表单可提供「本次不关联任务」选项；相关 header 映射见 agents 目录下对应文档。

7 轻量独立形态：插件、独立容器与 SDK

第 4、6 章为团队版三件套加 Proxy，适合多人多 Agent 协作、资产审核与权限治理；本章面向个人 OpenClaw / Hermes 宿主与自研 Agent，默认使用本地 SQLite + sqlite-vec，不依赖 Memory Hub 面板与团队权限治理。两类形态按场景二选一。

7.1 OpenClaw 宿主插件

插件包安装与重启命令如下，要求 Node.js ≥ 22.16、OpenClaw ≥ 2026.3.13：

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

在 ~/.openclaw/openclaw.json 中零配置启用：

{
  "memory-tencentdb": {
    "enabled": true
  }
}

启用后插件自动完成对话捕获、记忆抽取、场景聚合、画像生成与下一轮召回。可选开启短期压缩（要求插件版本 ≥ 0.3.4）：

{
  "memory-tencentdb": {
    "config": {
      "offload": { "enabled": true }
    }
  },
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

注册 slots.contextEngine 后，还需按插件文档执行 after-tool-call 运行时补丁，使工具调用后的消息能够正确卸载与恢复；分层记忆产物位于 ~/.openclaw/memory-tdai/ 目录。

7.2 独立体验容器

官方发布了 Hermes 与 OpenClaw 两个独立体验镜像，多架构自动匹配，无需本地构建：

docker pull agentmemory/hermes-memory:1.0.0-beta
docker pull agentmemory/openclaw-memory:1.0.0-beta

Hermes + Memory 独立容器启动示例：

docker run -d --name hermes-memory \
  --restart unless-stopped \
  -v hermes-memory-data:/opt/data \
  -e MODEL_API_KEY="<LLM_API_KEY>" \
  -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \
  -e MODEL_NAME="deepseek-v3.2" \
  -e MODEL_PROVIDER="custom" \
  agentmemory/hermes-memory:1.0.0-beta

# 进入 Hermes 对话
docker exec -it hermes-memory hermes

# 检查容器内 Memory Gateway
docker exec hermes-memory curl -s http://127.0.0.1:8420/health

OpenClaw + Memory 独立容器启动示例：

docker run --rm -it --name openclaw-memory \
  -p 18789:18789 \
  -v openclaw-memory-data:/home/node/.openclaw \
  -v openclaw-memory-store:/opt/data \
  -e MODEL_API_KEY="<LLM_API_KEY>" \
  -e MODEL_BASE_URL="<LLM_BASE_URL>" \
  -e MODEL_NAME="<MODEL_ID>" \
  -e OPENCLAW_CONFIG_OVERWRITE=1 \
  agentmemory/openclaw-memory:1.0.0-beta \
  openclaw-memory-tui

• 两个独立容器各自在 127.0.0.1:8420 运行独立 Memory Gateway，常规使用不需要把 8420 映射到宿主机；需要从宿主机调试时再加 -p 8421:8420 等非冲突映射。
• 复用 hermes-memory-data 卷时，容器沿用卷内 /opt/data/config.yaml 与 .env；修改 MODEL_API_KEY、MODEL_BASE_URL、MODEL_NAME 或 MODEL_PROVIDER 时需加 -e HERMES_CONFIG_OVERWRITE=1 重建配置；删除数据卷会清除本地记忆。

7.3 TypeScript SDK 接入自研 Agent

自研 Agent 可通过 TypeScript SDK 程序化读写记忆，安装命令如下：

npm install @tencentdb-agent-memory/memory-sdk-ts

客户端初始化示例：

import { MemoryClient } from "@tencentdb-agent-memory/memory-sdk-ts";

const client = new MemoryClient({
  endpoint: "http://127.0.0.1:8420",
  apiKey: "local",
  serviceId: "default",
});

• 独立模式下 apiKey 使用 local、serviceId 使用 default；接入团队版三件套时替换为对应业务用户凭据与实例 ID。

表 12 TypeScript SDK 分层方法概览

7.4 形态选择建议

• 个人单 Agent、轻量备忘：选择 7.1 插件或 7.2 独立容器。
• 团队多人多 Agent、资产审核、权限与配装：选择第 4、6 章三件套加 Proxy。
• 自研框架需要程序化读写记忆：选择 7.3 SDK 接入本地或团队版 Gateway。

8 运维操作

8.1 查看日志

docker logs -f tdai-memory-core
docker logs -f tdai-memory-hub
docker logs -f tdai-proxy

memory-hub 内部运行 panel 与 knowledge 两个进程，日志分别位于容器内 /data/knowledge/logs/panel.log 与 /data/knowledge/logs/knowledge.log。

8.2 停止与清理

./stop-all.sh            # 停止容器，保留 volume 数据与 admin key
./stop-all.sh --purge    # 停止容器并删除 volume、admin key 与 proxy config

8.3 端口冲突调整

如果 8125、8420、8424、8096 与本地已有服务冲突，直接在 .env 中修改对应端口，KNOWLEDGE_PUBLIC_BASE_URL 中的端口号同步修改，示例：

MEMORY_CORE_PORT=18420
PANEL_PORT=18125
KNOWLEDGE_PORT=18424
PROXY_PORT=18096
KNOWLEDGE_PUBLIC_BASE_URL=http://host.docker.internal:18424/v3

8.4 镜像升级与版本固定

• 默认使用 :latest，本地已有同名镜像时脚本默认复用；需要拉取远端最新版本时执行 PULL=1 ./start-all.sh。
• 需要固定版本时，把 .env 中三行镜像 tag 改为具体版本（例如 :1.0.2）；升级前建议先备份两个数据卷。

8.5 旧版本数据迁移

已在 v1.x 或 v0.x 版本运行、需要升级到 v2.0.0+ 的用户，使用仓库提供的迁移工具 MemoryCore/scripts/migrate-v2-to-v3；新安装可跳过该步骤。切换 SQLite 与 MongoDB 后端不会迁移已有数据，需先备份并手工迁移。

8.6 可选高级能力

• MongoDB 存储后端：试验特性，默认关闭；执行 ./start-all-mongo.sh 会把 MEMORY_CORE_STORE_MODE=mongodb 写入 .env，流程与 start-all.sh 一致；详细说明见 deploy/global-images/README.md 与 INSTALL_CN.md。
• 数据分析与可观测性：基于 ClickHouse 的上报默认关闭；准备实例后按 INSTALL_CN.md「数据分析与可观测性」章节配置 Proxy、Knowledge 与 Core 上报，面板可渲染 session-init、tool-call 与 usage 图表。

9 界面与记忆资产

对话与任务中产生的经验先沉淀为四类记忆资产，在 Memory Hub 中完成审核、分享与配装，再交付给下一个 Agent，如图 4 所示。

▲ 图 4 四类资产沉淀与流转：Skill、Wiki、CodeGraph、Chat Memory 汇入 Memory Hub

每完成一次工作闭环，经验持续积累，下一个 Agent 从团队已到达的地方开始，如图 5 所示。

▲ 图 5 Agent 完成工作、验证、审核写回与下次复用的经验积累闭环

9.1 Chat Memory 面板

Chat Memory 面板按 L0 对话原文、L1 原子记忆、L2 场景记忆与 L3 核心记忆分层呈现，可直接核对原话、时间与来源，如图 6 所示。

▲ 图 6 Memory Hub 面板 Chat Memory 分层视图

9.2 Skill 技能库

Skill 资产包含 Agent 归属、版本、Owner 与 Body 步骤说明；个人 Skill 默认私有，审核后可团队共享并配装给其他 Agent，如图 7 所示。

▲ 图 7 Skill 技能资产管理面板

9.3 Wiki 知识图谱

Wiki 把文档切片为概念、实体与来源等节点，并生成链接边；面板同时展示节点数、边数与检索入口，如图 8 所示。

▲ 图 8 Wiki 知识库图谱面板

9.4 CodeGraph 代码图谱

CodeGraph 面板展示文件数、图节点与图边统计，支持代码符号搜索与自然语言影响面探索，如图 9 所示。

▲ 图 9 CodeGraph 代码图谱面板

9.5 资产分配与可见性

「我的资产分配」页支持共享与私密切换，列出各 Agent 的资产清单；private 严格属于 Owner，team 对团队内其他成员只读可见，restricted 通过 User、Role、Agent ACL 精确授权，如图 10 所示。

▲ 图 10 资产分配与共享 / 私密可见性管理面板

10 常见问题

10.1 ./start-all.sh 卡在 wait_healthy？

镜像可能仍在拉取。先使用 docker pull <IMAGE> 手动预拉对应镜像，再重新运行启动脚本。

10.2 memory-hub 启动成功但 Panel 打不开？

检查 .env 中 KNOWLEDGE_PUBLIC_BASE_URL 是否包含 /v3；同时执行 docker logs tdai-memory-hub 排查 REMOTE_INSTANCE_URL、LLM_BASE_URL 等配置错误。

10.3 proxy 转发返回 401？

通常是 PROXY_UPSTREAM_API_KEY 无效或 PROXY_UPSTREAM_URL 不匹配；执行 docker logs tdai-proxy 查看具体错误。

10.4 Claude Code 会话没有弹出选择表单？

检查 PROXY_FULL_STACK 是否开启；start-all.sh 默认 PROXY_FULL_STACK=1。如果手动改过 .env 或以 PROXY_FULL_STACK=0 启动，执行 PROXY_FULL_STACK=1 ./start-proxy.sh 重启 proxy。

10.5 表单选项为空，或只能看到别人的 Team？

确认当前账号已在面板创建 Team 与 Agent；使用 admin 账号时检查是否已创建相关资产，使用业务用户账号时检查是否已在对应 Team 下创建 Agent。

10.6 业务用户登录后找不到「新建团队」按钮？

这是面板权限设计而非缺陷：建 Team 仅对 admin 开放。可请 admin 建好团队并把成员拉入，或业务用户使用 team/create API 自助创建（owner_user_id 填自己，建成后即为该 Team admin）。

10.7 L1、L2 长期没有产出，records 目录为空？

检查 MEMORY_PROMPT_MODE 是否匹配对话场景；code 模式下纯闲聊可能抽出 0 条记忆，可改回 chat，或与 Agent 开展真实工作对话，例如修改文件、运行测试、给出结论。

10.8 如何切换到其他 Team 或 Agent？

新开一个 Claude Code 会话（新窗口或新 session），新会话会重新弹出选择表单；同一进程内不会重复询问。

10.9 容器外需要访问宿主机其他服务（Ollama、Langfuse 等）？

脚本已默认 --add-host=host.docker.internal:host-gateway，容器内使用 http://host.docker.internal:<port> 即可回环到宿主机。

10.10 面板提示 Panel API 8125 未启动？

执行 docker ps 检查 tdai-memory-hub 是否 healthy；未 healthy 时查看容器日志，常见原因为 REMOTE_INSTANCE_URL 或 LLM_BASE_URL 配置错误。

11 使用边界与注意事项

• Wiki 与 CodeGraph 为异步构建，需要等待一定时间处理至 ready 状态后再使用。
• CodeGraph 当前首先支持公开 HTTPS 仓库；私有仓库与 SSH 凭证接入仍在完善中。
• Hub 已支持人工绑定资产；全自动记忆路由仍在持续迭代。
• 生产、联调或公网部署前必须替换默认内部凭据，不要把默认 admin key 用于客户端接入。
• 记忆内容可能包含对话中的敏感信息，团队共享与 ACL 授权前应完成脱敏与边界确认。
• 基准测试结果仅代表特定任务、模型与提示词组合，接入前请使用自身工作流做小样本验证。
• 本文命令与变量名以仓库 feat/server_team 分支官方文件为准；版本更新后请对照 2.2 节最新文档跳转表复核。

附录 A 环境变量清单

表 13 汇总三件套部署常用环境变量，完整注释与可选高级变量以仓库 deploy/global-images/.env.example 为准。

表 13 三件套常用环境变量

L3 即时更新决策（JEV 组）与 MongoDB 连接组等可选变量，见 .env.example 注释块，本文不再展开。

附录 B 参考来源

本文事实与命令核验时点为 2026 年 10 月 25 日，内容来自仓库 feat/server_team 分支的以下官方文件与公开元数据：

• README_CN.md、README.md：项目定位、能力边界、分层记忆、四类资产、公开评测与注意事项。
• INSTALL_CN.md、INSTALL.md：三件套部署、面板建组与建用户、Claude Code 接入、独立 Memory Hub、Agent 接入总览与已知限制。
• deploy/global-images/README.md 与 .env.example：组件端口、镜像、环境变量、独立组件、数据持久化、停止清理与端口冲突说明。
• agents/claude-code/、agents/hermes/、agents/openclaw/ 等目录：各客户端配置文件、Header 约定与会话初始化机制。
• npm registry 与 Docker Hub 公开元数据：插件包、SDK 与镜像版本、标签与架构支持情况。

如本文与官方最新文件存在差异，以 2.2 节列出的官方仓库页面为准。