TencentDB-技术解析与体验分析

项目： Tencent/TencentDB-Agent-Memory — 让 Agent 沉淀经验，让人专注创造。
GitHub： https://github.com/Tencent/TencentDB-Agent-Memory

一、项目定位与核心命题

定位

面向 AI Agent 团队的**「记忆 Hub」。核心理念一句话——「让经验沉淀、流动，然后被下一位 Agent 直接继承」**。其价值主张链条：

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

要解决的实际痛点

换一个 Session，同样的背景（项目、文档、结论）要重新讲一遍
换一个 Agent，文档要从第一页重读
一套已经跑通的做法，下次还要从头摸索一遍
关键约束（如「别重构旧鉴权模块，移动端还在用」）这种高代价上下文，不该靠人每次提醒

核心命题

作者用一句自述概括——「TencentDB Agent Memory 不追求『存下所有东西』，而是解决三个问题：什么值得留下、谁可以使用、下一次怎样少拿但拿对。」

展开即三条设计主线：

沉淀（Distill）：对话先落为 L0 原始记录，再由异步 Pipeline 提炼为不同粒度的记忆（L1/L2/L3）。
治理（Govern）：记忆资产带 Owner / 版本 / 状态 / 可见性，不是人人可读的聊天记录仓库。
装配（Loadout）：通过 Fixed Binding + ACL 精准注入某个 Agent 该带的资产，少给噪音、多给完成工作真正需要的记忆。

一个贯穿始终的立场边界

Memory 是「让每一轮 Loop 继承上一轮成果」的电梯，不是替 Agent 跑 Loop 的马达。

「没有 Memory，Loop 可能只是更快地重复；能继承记忆，每一轮才有机会比上一轮更好。」

项目刻意不碰 Agent 编排 / Loop 执行，只做记忆与治理层，与编排框架（LangGraph/AutoGen 等）边界清晰、不重叠。

与 RAG / 聊天历史的边界

RAG 只解决「能查到什么」；本项目额外解决「谁可以用、哪个版本有效、应该给哪个 Agent」。

	聊天历史	普通 RAG	TencentDB Agent Memory
跨会话理解用户	△	△	✅ Chat Memory
沉淀可执行经验	—	—	✅ Skill
文档结构与关系	—	△ 切片检索	✅ Wiki + Link Graph
代码调用与影响范围	—	△ 文本命中	✅ CodeGraph
Owner / 版本 / 状态	—	—	✅
团队分享与 Agent 配装	—	—	✅
私有 / 团队 / ACL	—	△	✅

二、竞品格局

README 明确将普通 RAG / 聊天历史作为对照系（而非「另一套 Agent Memory」）。横向看同类赛道（Agent 记忆 / Agent 上下文 / 团队 AgentOps），主要玩家与差异点：

方向	代表	与它的差异
单 Agent 会话记忆	Claude 原生 Memory、ChatGPT 记忆、mem0、Zep 等	多为「跨会话记住偏好」的轻量层，偏单 Agent；本项目升级为团队级、带 ACL、多框架
RAG / 向量库	LangChain、Milvus / Pinecone / Qdrant 等	RAG 只管检索；本项目在检索之上叠加了治理、装配、逐层提炼
Agent 编排	LangGraph、AutoGen、多 Agent 框架	它们负责跑 Loop；本项目刻意只做记忆层、不碰编排（边界清晰）
给 Agent 配装备	Claude Code 原生 memory、各类记忆插件	本项目以 Loadout + Fixed Binding + ACL 为差异点，且框架中立、可迁移

补充观察： Claude 等原生 Memory 大多存在长度上限，在大型或团队级项目场景下有明显劣势——这也是需要外部记忆 Hub 的客观原因之一。

护城河：① 四类资产（Chat Memory / Skill / Wiki / CodeGraph）统一成一个 Memory Asset 模型；② 框架解耦——同一份记忆资产可配给 OpenClaw / Hermes / Claude Code / CodeBuddy / SDK 任一 Agent，切换不重新训练。

技术继承（致谢）：CodeGraph（@colbymchenry/codegraph）、Hermes Agent（Skill 资产部分）、Andrej Karpathy 的**「LLM Wiki」**思路。这些也构成它的实现基座。

行业印证： LLM-Wiki 项目也有借鉴 Karpathy 的思路，这说明业界基本认可「以 Wiki 方式存储知识有助于 Agent 记忆召回」这一点。

三、技术栈与技术实现路线

3.1 技术栈总览

全部 Node 22+ / TypeScript（ESM），Web 层统一 Hono（轻量、跨运行时），monorepo（无根 package.json，各模块独立版本/安装/测试）。

组件	关键栈	存储
MemoryCore（记忆内核）	Node22、TS、原生 `node:http` Gateway、Vercel AI SDK（`ai` + `@ai-sdk/openai`）`sqlite-vec`、`@node-rs/jieba`(BM25 中文分词)、`js-tiktoken`、zod、OpenTelemetry	SQLite（向量+FTS5+BM25），可选 TCVDB、ClickHouse、Redis、COS、MongoDB、Kafka
MemoryKnowledge（知识）	Hono、Drizzle ORM、`better-sqlite3`、`@colbymchenry/codegraph`、`graphology`、`minisearch`、Vercel AI SDK（openai+anthropic）、MCP SDK、Swagger	SQLite + 磁盘（wiki 页 / git clone / codegraph）
MemoryPanel（控制面）	Hono 后端 + React18/Vite/Tailwind 前端、`zustand`、`react-router-dom`、`i18next`、`sigma`+`graphology`(图可视化)、`tea-component`(腾讯UI)	无状态，转发
MemoryProxy（转发接入）	Hono、`@hono/node-server`、`tsx` 运行时直跑 TS、硬要求 node v22、Langfuse / Opik、ioredis、better-sqlite3	不存记忆；storage 抽象（Redis / COS / SQLite / FS）
SDK	TS（npm）+ Python（pip、httpx）	—

端口（实际部署为准）：MemoryCore 8420、Panel 8125、Knowledge 8424、Proxy 8096。
⚠️ 源码内默认值与文档（8123 / 8421）和实际部署不一致，排查时以 deploy/global-images/.env.example 为准。

3.2 四大自由度的技术选型理由（实现路线）

全 TS + Hono：TypeScript 保证跨模块类型安全与 monorepo 协作；Hono 比 Express/Fastify 更轻、可跑 Node/Bun/Edge、依赖极少，契合「多服务、各自独立演进」。
SQLite 优先 + 向量可选：本地一键起不依赖外部 DB；sqlite-vec 提供向量检索、FTS5 提供全文、BM25（jieba 中文分词）提供稀疏召回，三路混合 RRF 融合。数据层留了 TCVDB（腾讯云向量库）后端抽象，答上规模场景。
Vercel AI SDK（ai）：统一封装 openai / anthropic / 本地 llama 提供方，一套代码换供应商，不为每家 LLM 写适配。
Embedding 双模：远程（openai 兼容）或完全本地离线（node-llama-cpp + embeddinggemma-300m GGUF）——隐私 / 离线场景可用。

3.3 四层记忆管线（最核心的实现路线）

对话 → L0 Conversation（原始记录，落库可核对原文/时间）
      ↓ 异步 LLM 抽取（JSON-mode 结构化输出）+ batch 冲突去重
      → L1 Atom（事实/偏好/约束/事件）              [可精确召回，走检索不常驻]
      ↓ 场景化
      → L2 Scenario（围绕项目/场景的知识块）         [注入 system prompt]
      ↓ 画像触发（checkpoint 5 条件）
      → L3 Core/Persona（长期画像/稳定模式）          [注入 system prompt]

层级	保存什么	主要用途
L0 Conversation	原始对话与完整上下文	核对原话、时间和来源
L1 Atom	从对话提取的事实、偏好、约束与事件	精确召回可执行信息
L2 Scenario	围绕项目或场景组织的知识块	快速恢复一个工作场景
L3 Core / Persona	长期画像、稳定模式与高层认知	让 Agent 迅速进入用户和团队语境

生成侧：l1-extractor（L0→L1）、scene-extractor（L1→L2）、persona-generator/trigger（→L3）。
召回侧：平时用 L2 / L3 快速进语境；需要具体事实时 BM25 + 向量 + RRF（Reciprocal Rank Fusion，RRF_K=60） 下沉到 L1 / L0。结果经过「条数、字符预算、超时」三重约束，避免记忆反过来占满上下文。

3.4 装配与治理路线

所有资产登记为 Memory Asset，通过 Fixed Binding + ACL 决定某个 Agent 能带走哪些——先按 Team、User、Agent、可见性缩小权限范围，再按当前问题召回。
Knowledge 不整库注入、按需调用：Agent 先 /v3/tools/list 发现能力，再用 /v3/tools/call 读取相关页面、源码或影响路径——文档/代码平时只是可用工具，需要时才进上下文。

3.5 三层鉴权（微服务安全路线）

1
2
3

Layer 1: Bearer（gateway key，带凭证才可到达业务接口）
Layer 2: x-tdai-service-id（memory 实例标识，本地固定 "default"）
Layer 3: x-tdai-user-key（用户身份，解析为 userId / isSystemAdmin）

proxy 拿 user_key → core /v3/meta/auth/verify 反查 user_id，按用户维度控制资产可见性。

3.6 L1 抽取机制（一个关键实现细节）

l1-extractor.ts 用单次 LLM 调用 + JSON-mode 结构化输出，一次完成「scene 切分 + memory 抽取」，随后做 batch 冲突检测去重，写 L1。失败时 pipeline 会把任务标记为 Task completed（extracted=0）——这是本系统最容易忽略的静默失效点（详见第八节）。

四、功能清单

四大记忆资产

Chat Memory — L0 原始 → L1 事实 → L2 场景 → L3 画像；跨会话保留偏好、决策、交互历史
Skill — 从跑通的任务提炼可复用 SOP，带版本 / 资源文件 / 触发边界 / 执行步骤 / 验证规则；私有 → 审核 → 团队共享 → 配装
Wiki — 导入文档 → LLM 生成结构化页面 + 链接图谱（灵感源自 Karpathy LLM 知识库）
CodeGraph — 索引符号 / 文件 / 调用关系 / 影响路径，支持 impact analysis；定时自动同步代码库

Memory Hub（管理面板）

建 Team / Agent / Task，资产按 Owner / 版本 / 状态 / 可见性统一管理
四级可见性：private / team / restricted(User/Role/Agent ACL) / agent(定向装配)
双层角色：全局 System Admin + Team 内 Admin / Member
Agent Loadout：给不同 Agent 绑定不同资产、调优先级与使用方式
图可视化（CodeGraph / Wiki 链接图谱）、中英双语切换

Memory Proxy（接入层）

Anthropic / OpenAI 双协议：/claude-code/<spaceId>/v1/messages、/v1/chat/completions
SessionInit：首轮用 AskUserQuestion 表单选 team / agent / task；后续轮 proxy 记住绑定
Header 预选：x-team-id / x-agent-id / x-task-id（三头齐全可跳过表单直接注册）
每轮注入：把该 agent 的 L2/L3 记忆、matched skill、wiki/code-graph 拼进 system prompt
L0 回流：原始对话自动写 memory-core SQLite
**mem: 会话指令**：mem:sync / mem:create-skill [提示词] / mem:help
鉴权 + Cost Guard：让不同 Agent 用不同模型以降低成本

接入形态

Claude Code / CodeBuddy / Hermes / OpenClaw / 通用 OpenAI 兼容平台 / SDK（TS + Python）

运维能力

start-all.sh 一键三件套 · verify.sh 干跑预检 · stop-all.sh 清理 · 数据迁移工具（v2→v3、sqlite→tcvdb）· export-tencent-vdb · read-local-memory

五、使用方法与工作流程

① 部署（三件套）

git clone https://github.com/Tencent/TencentDB-Agent-Memory.git
cd deploy/global-images
cp .env.example .env
$EDITOR .env              # 填两组 LLM 参数
#   MEMORY_LLM_*   → memory + hub 内部所用（embed / summarize / wiki ingest）
#   PROXY_UPSTREAM_* → proxy 转发到的上游 LLM
./verify.sh               # 可选：干跑 LLM 通路预检（--skip-llm 跳过）
./start-all.sh            # 一键起，启动后打印可直接复制的 claude 命令

面板：http://localhost:8125（首次用 .admin-key 里的 sk-mem-… 登录）

② 接 Claude Code

1
2
3

export ANTHROPIC_BASE_URL=http://127.0.0.1:8096/claude-code/default
export ANTHROPIC_AUTH_TOKEN="<业务用户的 user_key / admin user_key>"
claude --model [[ORCA_RICH_MD:9bef3f918c00c31832fcd140e9d654a8:inline-html:%3CPROXY_UPSTREAM_MODEL%20%E9%87%8C%E9%85%8D%E7%9A%84%E4%B8%8A%E6%B8%B8%E6%A8%A1%E5%9E%8B%3E]]

URL 里的 default = memory 实例 ID（x-tdai-service-id），本地固定
ANTHROPIC_AUTH_TOKEN = 用户 user_key，proxy 用它反查 user_id，只暴露该用户 own 的 team/agent/task

③ 工作流闭环

新 CC 会话 → 弹 Team→Agent→Task 表单 → proxy 记住绑定
  → 每轮注入该 agent 的 L2/L3 记忆 + Skill + Knowledge
  → L0 原始对话自动落库 → 后台 L1→L2→L3 逐步提炼
  → 面板审阅 / 审核 / 分享 / 配装 → 冷启动读档（导入旧代码/文档/会话直接复用）

④ 进阶

面板看图图谱、审 Skill、配置 ACL / Loadout
会话内指令 mem:sync / mem:create-skill
对接 CodeBuddy / Hermes / OpenClaw / 其他平台（改各自配置文件，header 方式带四件套 x-*）

六、实现效果与用户价值

量化 Benchmark

Benchmark	无 TencentDB Agent Memory	启用后	相对提升
PersonaMem	48%	76%	+59%

（PersonaMem 检验 Agent 能否在长期交互后正确理解和运用用户信息。）

质性效果 / 价值

减少 Tunknows：跨会话不重复自我介绍 / 重读文档 → 更少 Turn、更少返工
团队经验复利：「公司可以很小，经验可以一直复利」——新成员读档，不必重新训练
共享经验不共享隐私：默认私有，分享是显式动作，不是默认泄漏
可塑性成本低：换 Agent / 换框架只重新装配，不重训
防经验丢失：关键约束沉淀为记忆资产，不靠人每次口头提醒

七、可提炼的方法论

分层沉淀、逐层提炼：L0 原始 → L1 原子 → L2 场景 → L3 画像。既保可核对原文，又让高价值信息进入 system prompt。
召回也要分层：常走快捷通道（L2/L3）+ 精确通道（BM25+向量+RRF 下沉 L1/L0），并加三重预算约束防上下文膨胀。
资产即治理对象：Owner / 版本 / 状态 / 可见性 / 使用次数——知识管理不只存还要管。
装配优先于灌入：Fixed Binding + ACL 先收权限、再按问题召回，力求「少拿但拿对」。
框架中立、解耦迁移：资产模型与 Agent 框架隔离，一套资产多框架复用。
冷启动即读档：把已付的学习成本变成存档，缩短新团队 / 新成员上手曲线。
不碰 Loop、只做记忆：与编排框架边界清晰，避免功能重叠。

两条反面方法论（实战总结）：

失败会被吞成「完成」的静默失效——memory-core 把 LLM 抽取失败标记为 Task completed，/health 的 tasksFailed 恒为 0，只能 grep 日志 l1-extractor 才会发现记忆链路已死。

依赖对象存活决定链路形态——proxy header 预选要求 team/agent/task 三者都活着；task 被删就退表单，不改表单则 session bypass、注入全空转，且请求照常 200、不报错。
这两点都提示：给关键后台流程设计可观测的「自检信号」，而非把失败静默吞掉。

八、局限与风险

功能局限

Knowledge / CodeGraph 异步构建，需要等待 ready
CodeGraph 目前仅支持公开 HTTPS 仓库，私有仓库与 SSH 凭证接入仍在完善
记忆路由仍以人工绑定为主，全自动记忆路由迭代中
PROXY_UPSTREAM_MODEL 只被 /require_vars 校验非空、不参与实际转发（实际模型由请求体 / 客户端 --model 决定）——配置语义易误解

架构 / 运维风险（含本会话实测踩点）

L1 抽取静默失败：LLM 抽取失败被 pipeline 标成 Task completed，extracted=0、health 正常，只能看 core 日志。判断命令：docker logs --tail 600 tdai-memory-core 2>&1 | grep -E 'l1-extractor|L1 complete'。
header 预选依赖 task 存活：x-team-id+x-agent-id+x-task-id 任一失效（尤其 task 被删）→ preset mismatch → fallback to form；不答表单则 session bypassed → injection skipped，input_tokens 骤降，无报错。
thinking-shim 依赖：经 DeepSeek 等 Anthropic 兼容端点，需 shim 强制注入 thinking:{"type":"disabled"}，否则因 Thinking Mode 来回传限制产生第二轮 400。接新的兼容上游时都需复查此类「协议适配」坑。
**joinUrl 只拼裸路径**：白名单未命中时把裸 /messages 拼到 base 后、不补 /v1——真实 API 网关类上游必须自带版本段。
端口默认与实际不一致：文档 8123 / 8421 vs 部署 8125 / 8424。
MemoryProxy 硬要求 node v22：非 v22 直接退出。
proxy→core auth 不带 Bearer：本地栈 MEMORY_CORE_GATEWAY_API_KEY 必须留空，否则 proxy 鉴权失败。
可选依赖多、feature-gate 组合多（ClickHouse/Redis/COS/Kafka/Opik），排查路径长。

安全风险

默认内部凭据 local / admin key admin 只适合个人本地；公网暴露前必须替换成随机长串，否则任何拿到端口者可获 system_admin 权限。

九、可优化项

功能

x-task-id / x-conversation-id 放宽为可选（Roadmap 已在做）——降 Hermes/OpenClaw 接入门槛
全自动记忆路由、私有仓库 / SSH 的 CodeGraph（Roadmap）
mem: 指令族继续扩充（收藏近期高频诉求）

技术

给 L1/L2/L3 静默失败加显式告警 / 自检信号（失败产生可观测 error metric，而非吞成 completed），并让 /health 反映记忆链路健康度
修复 joinUrl 对版本段的规范化，或生成的 config 明确要求 /v1，消除「配置成因」类报错
统一文档端口与部署端口
Cost Guard 与 PROXY_UPSTREAM_MODEL 的配置语义一致性

体验

冷启动默认 Agent + 预置 Skill，跑完 start-all.sh 复制一行就能开始（Roadmap v2.0.1）
Wiki 生成并发化，长文档导入不串行等待（Roadmap）
用户 / 团队级自定义 Prompt + provenance 溯源（Roadmap v2.0.1）——「记忆质量变差」可追溯而非靠猜
面板记忆时间过滤、骨架屏 / 过渡动效 / 无障碍、各资产详情页头部统一（Roadmap v2.0.1）

真实体验

这是一款全面度较高的团队级 Agent Hub：功能齐全、操作便捷、界面简洁，质量与完成度都不错。虽然许多细节仍有打磨空间，但大的功能板块已齐全完整，几乎集成了当下主流开源社区的做法，非常适合团队使用。项目当前正处于高速迭代期，演进很快。

1. 配置：有 API 冲突隐患，建议统一管理

与 Orca 存在 API 冲突的潜在可能，实际运行时应写死 claude-setting.json 与 model。这背后的本质是两点：其一，团队共用同一个 API Key；其二，运行 Memory Hub 功能本身需要大模型。

因此建议提供一个统一的 API 管理界面（相当于内置一个 API 中转站的效果），把客户端接入与管理入口收拢到同一个地方。目前 API Key 主要承担「客户端接入」这一角色，但对于团队型 Hub，我认为还应考虑三方面的负载均衡：

单份 Key 能承受多大的模型访问量；
Hub 的写入 / 写出峰值；
Wiki、Memory 等资产的写入、修改与删除带来的并发压力。

管理方式可以参考 GitLab 的做法（分权、限额、审计）。

2. Agent 成员：可把 Agent 当作团队成员来维护

Agent 完全可以被设定为团队成员进行长期的统一维护。

设想这样一个场景：一个 Agent 接入了 Claude、Codex、飞书乃至一切提供 CLI / MCP 接口的程序与工具，同时具备写代码、回消息、处理办公信息的能力——它会在网络上逐渐逼近一名真实的员工。而它真正需要的，只是一个具备并发能力且支持记忆的底座、以及合适的连接工具。这几乎就是现在的「飞书豆包助手」的雏形。

当越来越多的程序与工具开放 CLI 接口，一个几乎能在网上无所不能的超级 Agent 就将诞生——这也是当前各大厂商正在做的事：打通 AI 链路，推动生产力范式的转变。TencentDB 所做的事已现此苗头。一旦 Agent 获得海量 API 和各种软件的 Skill，叠加未来更强的模型能力，整个 IT 行业的生产逻辑很可能会发生剧变。

3. Wiki 知识库：LLM-Wiki 的项目化落地

Wiki 本质上是 llm-wiki 的迁移弱化版，但结合了本项目自己的团队机制与 Agent 成员理念来组织。其基本功能已基本实现，可以直接读取代码库、文档与对话 Session。后续主要剩性能与体验的优化，例如批量上传、更精确美观的图谱连线与色彩分配等。

4. Chat Memory：多一层的「核心记忆」，尤为巧妙

它的记忆分层设计很巧妙——分为 L0 / L1 / L2 / L3 四层，从具体事实逐步过渡到抽象概括。对比 OpenViking 的「摘要—概览—详情」三重记忆，这里多了一步核心记忆（L3 / Persona）。

这一步往往正是 Agent「人格」的建立，让记忆能够反过来影响输出偏好。而且核心记忆本质上并不怎么进入 RAG 检索，因此不会显著增加搜索层次的繁琐程度——这是一个收益很高、代价很小的设计选择。

5. Skill 技能：双通道沉淀 + 团队内快速流转

Skill 既支持从目录导入，也可以通过 Agent 对话导入。这既能逐步培养 Agent 成员的能力，也能导入已有的 Skill（虽然普通 Claude 等也能做到类似的事情）。最有价值的一点是：Skill 可以快速分享给团队，意味着团队沉淀下的「AI 小工具」能快速分发到各成员手中（尽管手动打包发送也能实现，但接入后的效率与一致性更好）。

6. Code Graph：站在既有开源成果之上

Code Graph 建立在 colbymchenry/codegraph 之上。其核心价值在于让 AI 能够快速分析代码中某个功能是如何实现的，并快速定位对应函数的位置。在 App 中已有可供体验的功能。

总评与推荐优化方向

总评： TencentDB 专注于团队型 Agent 管理，目标客群是初创 AI 团队。功能相对齐全，但当前在优化与能力深度上仍有不足；技术栈基于各大主流开源库建立，具备可靠的技术支撑与持续迭代能力，值得长期关注。

推荐优化方向：

Skill 功能提升：及早打通与各个平台的链路，把 Agents 管理融入成员管理，减少重复步骤。
Wiki 知识库：参考 LLM-Wiki 做进一步改善，补齐工程能力——例如 Wiki 生成并发化、长文档导入不串行等待等。
记忆编辑能力：参考 OpenViking 的思路，提供统一的文件管理方式——一是提升 Agent 调用效率，二是支持人工增删改查。
用户体验：冷启动阶段默认提供一个 Agent，构造类似豆包形象的初始通用助手并直接放在页面内，加快用户上手、解决高频小问题，避免用户拿完整 Agent 去问无关内容、污染记忆与 Wiki。
API 管理：升级为 API 中转站，提供更多可填的 Key、内置负载均衡，并支持进一步中转。
文件管理：参考 OpenViking，补充完整的文件管理系统。

附录：关键文件索引与注释

部署入口 `deploy/global-images/`

文件	说明
`start-all.sh`	一键三件套，顺序 memory→hub→proxy，任一步失败中止并打日志；末尾打印可复制的 claude 命令
`start-memory-core.sh`	内核 gateway 单独拉起（8420），并生成 `.memory-core-config/tdai-gateway.yaml`
`start-memory-hub.sh`	面板 + 知识（8125 + 8424），需 `MEMORY_LLM_*`
`start-proxy.sh`	proxy 单独拉起（8096），从 `.env` 生成 `.proxy-config/config.yaml` 挂载
`_lib.sh`	工具函数：`load_env` / `require_vars` / `wait_healthy` / `find_docker` / `print_endpoints`
`verify.sh`	干跑 LLM 通路预检（`--skip-llm` 跳过），提前拦下 key/URL/模型名错误
`.env.example`	两组 LLM 参数模板（memory 组 + proxy 组）
`stop-all.sh`	停止；`--purge` 连 volume / admin key / 网络一起清

MemoryCore（记忆内核）`MemoryCore/`

文件	说明
`src/gateway/server.ts`	HTTP Gateway（原生 `node:http`），挂 `/v2/`、`/v3/`、`/health`
`src/gateway/v2-router.ts`	v2 兼容路由
`src/core/tdai-core.ts`	host-neutral 核心门面，仅依赖 HostAdapter + LLMRunner 抽象
`src/core/record/l1-extractor.ts`	L0→L1 抽取（单次 LLM JSON-mode 结构化输出 + batch 去重）
`src/core/scene/scene-extractor.ts`	L1→L2 场景化
`src/core/persona/{persona-trigger,persona-generator}.ts`	L2→L3 画像（checkpoint 5 触发条件）
`src/core/store/{sqlite,tcvdb,factory,search-utils,embedding}.ts`	存储抽象（SQLite+sqlite-vec+FTS5 / TCVDB）+ BM25+向量+RRF 混合检索 + 双模 embedding
`src/core/store/types.ts`	整套数据模型：L0 / L1 / L2 / L3 + Team/User/Agent/Task/Asset + Audit
`src/services/pipeline-worker.ts`	异步提炼 worker（`timer-scanner` 驱动）
`src/metadata/router/auth.ts`	`x-tdai-user-key` 用户身份解析层
`index.ts` / `openclaw-plugin/` / `hermes-plugin/`	OpenClaw / Hermes 框架适配

MemoryKnowledge（知识服务）`MemoryKnowledge/`

文件	说明
`src/server.ts`	Hono 入口，挂 `/v3/wiki`、`/v3/code-graph`、`/v3/tools`、`/docs`
`src/engines/wiki/{index,ingest-v2/*}.ts`	LLM Wiki 生成管线（含 ingest-v2 并发增强）
`src/engines/code/index.ts`	CodeGraph 索引（复用 `@colbymchenry/codegraph`）
`src/mcp/server.ts`	MCP 服务形态
`src/db/schema.ts`	Drizzle 表结构（better-sqlite3，WAL）

MemoryPanel（团队控制面）`MemoryPanel/`

文件	说明
`src/index.ts` → `src/panel/index.ts`	后端入口（Hono，无状态）
`web/`	React 18 + Vite + Tailwind 前端（`source/main.tsx`）

MemoryProxy（转发 / 接入）`MemoryProxy/`

文件	说明
`src/server.ts`	Hono 路由：Anthropic / OpenAI 双协议 + bridges + `/health`
`src/handler.ts` / `src/anthropicHandler.ts`	主请求处理（模型闸门、alias 解析、上游转发兜底）
`src/injection/{pipeline,index,injectors}.ts`	注入管线（skill / knowledge / tdai-memory 注入器）
`src/session/` `src/db/` `src/storage/`	会话绑定 / 持久化抽象（Redis / COS / SQLite / FS）
`src/agent-adapters/{claude-code,codebuddy}.ts`	框架适配
`src/guard-adapter.ts`	`joinUrl` 拼接逻辑（白名单 + fallback）
`scripts/setup-claude-code.sh`	一键将接入信息写入 CC settings.json 的助手

SDK `sdk/memory-core/`

文件	说明
`typescript/src/{client,index,v3/*}.ts`	TS 客户端（npm `memory-sdk-ts-v2`）
`python/tencentdb_agent_memory/{v2,v3}/*`	Python 客户端（pip `tencentdb-agent-memory-sdk-python`）

v3 严格隔离 API 要求 team_id / agent_id / user_id（+ session）必填。

官方文档

README_CN.md（产品定位）、INSTALL_CN.md（部署 + 多框架接入 + 已知限制）、ROADMAP_CN.md（v2.0.1 计划）、CHANGELOG.md（版本演进）、deploy/global-images/README.md（部署细节 + 常见问题）、MemoryKnowledge/openapi.yaml（Knowledge OpenAPI）。