TencentDB Agent Memory：面向 Agent 团队的记忆中枢

01核心目标与定位

一句话定位：它不是「给单个 Agent 加记忆」，而是给一支 Agent 团队建一个集中式的记忆中枢。 官方英文描述把它称为 a team-level memory hub for AI Agents，把对话、文档、代码转化为 四类可复用记忆资产——Chat Memory、Skill、LLM-Wiki、CodeGraph——并让这些资产被治理、共享、按需装配到不同 Agent 上。

1.1 与「聊天历史」「普通 RAG」的定位差异

官方给出的对比表格清晰地划出了它的边界（下表为仓库 README 原文内容整理）：

这张表透露了它的真实野心：「RAG 解决『能查到什么』，Team Memory 还要解决『谁可以用、哪个版本有效、应该给哪个 Agent』」。 也就是说，它把记忆当成需要治理的资产，而不是可检索的语料。

1.2 目标用户画像

• 主要受众：团队。核心概念围绕 Team / Agent / Task 三元组组织，记忆必须落在具体三元组上才能被使用。
• 典型叙事：「一个人的公司」。README 给出的示例是一个 Team 内配置 Scout（查资料）、Builder（写代码）、Reviewer（测试）三类 Agent，各自挂载不同的记忆资产组合（官方称之为 Loadout）。
• 也覆盖个人场景：仓库同时保留了插件形态（OpenClaw / Hermes），个人用户可零配置起步。

02整体架构与模块划分

下文全部以默认分支（服务版）为准。

2.1 四个核心服务与端口

2.2 支撑性目录

2.3 运行拓扑

03关键功能与实现思路

项目自述「不追求存下所有东西」，而是解决三个问题：什么值得留下、谁可以使用、下一次怎样少拿但拿对。这三个问题恰好对应三套机制。

3.1 机制一：记忆分层（L0 → L3 语义金字塔）

这是整套系统的地基。对话先进 L0，再由异步 Pipeline 逐层提炼。代码层面的目录名直接印证了这一模型：

关键的工程取舍在于异构存储 + 渐进披露：底层（事实、日志、轨迹）落数据库以支持全文检索；顶层（画像、场景、画布） 以人类可读的 Markdown 文件保存，换取高信息密度与白盒可检查性。官方概括为 「下层保存证据，上层保存结构」。

3.2 机制二：符号化短期记忆与上下文卸载

长任务里最大的 token 消耗者是冗长的中间日志（搜索结果、代码、错误堆栈）。项目用 上下文卸载（Offload）+ Mermaid 符号图来处理。源码证据在 MemoryCore/src/offload/：

工作流是四步：① 全量日志卸载到外部文件（refs/*.md）→ ② 抽取关系，生成带 node_id 的 Mermaid 画布 → ③ 只把画布（几百 token）注入上下文 → ④ 需要核实细节时按 node_id grep 回原文。 压缩率与可追溯性被同时保住。

3.3 机制三：记忆即「Agent 的装备」（Loadout + ACL）

Chat Memory、Skill、Wiki、CodeGraph 被统一登记为 Memory Asset。Memory Hub 通过 Fixed Binding（固定绑定）+ ACL 决定某个 Agent 能带走哪些资产： 先按 Team、User、Agent 与可见性缩小权限范围，再按当前问题召回。

权限角色分两层：全局 System Admin（管用户与团队、也能用资产业务功能）与 Team 内角色（Admin / Member）。资产归属用 Owner 标记，Owner 自动获得该资产管理权。 新记忆默认私有——「分享是一个明确动作，不是默认泄漏」。

3.4 知识按需调用：Wiki 与 CodeGraph

MemoryKnowledge 的策略是「不整库注入」。文档被整理成可搜索、可沿链接下钻的 Wiki；代码库被索引成包含文件、符号、调用关系的 CodeGraph。 Agent 先通过 /v3/tools/list 发现能力，再用 /v3/tools/call 读取相关页面、源码或影响路径。 源码结构：src/engines/{wiki,code}、src/mcp/{server,tools,http-client}、src/source-fetcher/。

请注意一个职责切分的细节：MemoryCore 只存知识的元数据（标识、类型、状态、关联、服务地址）， 不存知识内容本身；解析、构图、索引、检索全部由 MemoryKnowledge 承担。这条边界写在 MemoryCore/README 的显著位置。

3.5 检索实现：BM25 + 向量 + RRF

召回策略可选 keyword / embedding / hybrid，其中 hybrid 使用 RRF 融合，是官方推荐项。 值得注意的是中文分词的落点：MemoryCore 依赖 @node-rs/jieba，配置项 bm25.language 默认 zh（jieba）/ en 可切。

3.6 分层记忆与符号化记忆的协同

3.7 零代码接入的实现：Proxy 如何工作

这是该版本最具传播力的设计。传统接入需要插件、Hook 或 MCP Server；这里只要把 Agent 的 base URL 指向 Proxy。 MemoryProxy 的实现按框架切分得很干净：

会话内指令 mem: 是一个轻量而实用的入口，已随 v2.0.0 发布：

04技术栈清单

以下全部来自各模块 package.json 的实读结果。

4.1 基础与运行时

4.2 数据与检索

4.3 模型与可观测性

4.4 前端（MemoryPanel/web）

05典型使用方式与适用场景

5.1 团队版：一键三件套

git clone https://github.com/Tencent/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
cp .env.example .env
$EDITOR .env          # 填两组 LLM 参数：memory 组 + proxy 组
./start-all.sh        # 拉起 memory-core + memory-hub + proxy
# 结束时会打印一行可直接复制的 claude 命令

面板地址：http://localhost:8125。也可只拉 Memory Hub 镜像单独用：docker pull docker.io/agentmemory/memory-hub:latest。

5.2 四步完成 Agent 接入（以 Claude Code 为例）

1. 建 Team / Agent / Task：在面板里建。注意面板上只有 admin 能建 Team，业务用户看不到入口属正常设计（可用 API 自助建）。
2. 把 Agent 指向 Proxy：
   export ANTHROPIC_BASE_URL=http://127.0.0.1:8096/claude-code/default
export ANTHROPIC_AUTH_TOKEN="<业务用户的 sk-mem-... user_key>"
3. 首次会话选择绑定：Proxy 借助客户端的 AskUserQuestion 工具连续弹出三个选择——Team → Agent → Task（Task 可跳过）。
4. 此后自动运行：每一轮请求自动注入该 Agent 的 L2/L3 记忆、Skill 与 Knowledge 到 system prompt；满足触发条件时后台跑 L1 → L2 → L3。

5.3 WorkBuddy / CodeBuddy 等其他客户端的接入差异

各客户端走各自的 handler，差异已被封装。以 WorkBuddy 为例，配置落在 ~/.workbuddy/models.json：

[
  {
    "id": "claude-opus-4.7-1m",
    "name": "claude-opus-4.7-1m",
    "vendor": "Custom",
    "url": "http://127.0.0.1:8096/workbuddy/default",
    "apiKey": "<业务用户的 sk-mem-... user_key>",
    "supportsToolCall": true
  }
]

WorkBuddy 走 OpenAI Responses API（桌面端）与 Chat Completions（Web 端）双协议，由独立的 workbuddyHandler.ts 处理； 会话初始化流程与其他客户端一致（选 Team → Agent → Task），Session ID 由客户端自动管理。 仓库为八个框架各配了 README 与资产导入手册，支持把本地历史对话导入 Memory Hub。

5.4 适用场景判断

06优点：值得肯定之处

07缺点与风险

7.1 版本与分支的混乱（可验证）

五个版本标识并存。对一个刚接触项目的开发者来说，「我装的到底是哪个版本」需要自己交叉比对才能确认。这不影响功能，但会显著提高上手成本，也让 Issue 定位变得困难。

7.2 CI 覆盖存在明显缺口

全仓只有一个工作流 .github/workflows/pr-ci.yml，共五个作业：

三个可验证的问题：

• 没有测试作业。仓库内确有 Vitest 测试，但 CI 流程中不执行任何 test 命令。
• 只覆盖 main（触发条件为 pull_request: branches: [main]），而默认分支是 feat/server_team——针对默认分支的 PR 不触发 CI。
• 工作目录固定在 MemoryCore，Knowledge / Panel / Proxy 三个模块的 PR 不受任何流水线约束。

考虑到 828 个未关闭 Issue，这样的质量闸门与项目体量并不相称。

7.3 复用第三方代码带来的许可与维护问题

项目在感谢章节中主动披露了两处代码复用，态度值得肯定，但也带来实际风险：

• CodeGraph 模块复用了 colbymchenry/codegraph 的代码，其依赖 @colbymchenry/codegraph 直接出现在 MemoryKnowledge 的 package.json 中。
• Skill 资产模块复用了 Hermes Agent 的部分 Skill 相关代码并做了优化。

对商业使用的团队而言，需要自行核验被复用代码的许可证是否与本项目的 MIT 兼容，以及上游项目变更时的维护风险。

7.4 代理层是设计上的单点与隐私汇聚点

「改 base URL 即可接入」的优雅设计，代价是 Proxy 在架构上是一次合法的中间人：它能看到并改写所有经过的提示词与响应。 同时它集中了团队全部记忆的读写入口。这意味着：

• Proxy 必须严格绑定回环地址，或启用 TDAI_GATEWAY_API_KEY 与 CORS 白名单。官方已内置警告机制，这一步不能省。
• Proxy 成为可用性单点——它不可用时，所有接入的 Agent 同时失去模型能力（不只是失去记忆）。
• 团队记忆集中存储，本身就是高价值攻击目标。虽然提供了分层权限，但存储层的物理隔离需要部署方自行加固。

7.5 其他需要留意的限制

08值得关注的九个要点

09事实来源与核验说明

核验方式说明

• 架构与端口：取自 INSTALL_CN.md「三个服务默认端口」表格，并与 deploy/global-images/ 下的启停脚本、.env.example 交叉验证。
• 模块职责与边界：取自各模块 README.md 与源码目录结构（find 实读，非文档转述）。
• 技术栈：逐模块读取 package.json 的 dependencies / devDependencies，版本号为文件内实际声明值。
• 「未使用依赖」结论：以全仓 grep 检索 node-pty 的 import 语句，结果仅命中 package.json 与 package-lock.json。
• CI 结论：完整读取 .github/workflows/pr-ci.yml（共 159 行、5 个作业），据此判定无测试作业、触发分支限于 main、工作目录限于 MemoryCore。
• Benchmark 数据：直接引用仓库 README 公布的数值，本报告未独立复现，引用时请保留来源标注。
• 明确未验证项：本报告未实际部署运行该系统，未验证其运行时行为、性能表现与 Benchmark 可复现性。所有涉及「实现思路」的描述均基于源码结构与官方文档的对照阅读。