如何迁移现有AI项目到TencentDB Agent Memory？完整数据迁移指南

【免费下载链接】TencentDB-Agent-Memory TencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks. 项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory

TencentDB Agent Memory是AI Agent的团队级记忆中枢，能将对话、文档和代码转化为四种可重用的记忆资产（Chat Memory、Skill、LLM-Wiki、Code-Graph），实现跨Agent和框架的治理、共享与赋能。本文将为你提供完整的数据迁移指南，帮助你轻松将现有AI项目迁移到TencentDB Agent Memory。

TencentDB Agent Memory的记忆层次结构

在开始迁移前，让我们先了解TencentDB Agent Memory的记忆层次结构。它采用了四层金字塔结构，从下到上分别是：

• L0 Raw Log：全量保留原始对话与事件流，确保原始信息不丢失，提供证据兜底。
• L1 Atomic Memory：自动提取事实、偏好、约束、状态，从语音中稳定抽出关键信息。
• L2 Scene Block：按项目/主题/工作流场景聚类，带上文召回，减少单场误用。
• L3 Persona：稳定的用户偏好与服务方式画像，让Agent按用户习惯协作。

这个层次结构能够帮助AI Agent更好地组织和利用记忆，提高协作效率和服务质量。

迁移前的准备工作

在进行数据迁移之前，需要确保满足以下前置条件：

1. 环境要求：Node.js >= 22.16.0
2. 插件安装：已通过 openclaw plugins install 安装TencentDB Agent Memory插件
3. 脚本编译：迁移脚本需要先进行编译

编译迁移脚本

迁移脚本使用TypeScript编写，位于项目的scripts/migrate-sqlite-to-tcvdb/目录下。编译命令如下：

npm run build:migrate-sqlite-to-vdb

编译产物将输出到scripts/migrate-sqlite-to-tcvdb/dist/目录，可直接用Node运行。

数据迁移的完整步骤

1. 克隆项目仓库

首先，需要克隆TencentDB Agent Memory项目仓库到本地：

git clone https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory

2. 进入项目目录并安装依赖

cd TencentDB-Agent-Memory
npm install

3. 执行迁移命令

TencentDB Agent Memory提供了灵活的迁移命令，支持多种场景和参数配置。以下是一些常用的迁移命令示例：

预检模式（仅查看源数据，不执行写入）

npm run migrate:sqlite-to-tcvdb -- \
  --plugin-data-dir ~/.openclaw/memory-tdai \
  --openclaw-config-path ~/.openclaw/openclaw.json \
  --tcvdb-url http://127.0.0.1:80 \
  --tcvdb-username root \
  --tcvdb-api-key-env TCVDB_API_KEY \
  --tcvdb-database agent_memory_prod \
  --tcvdb-embedding-model bge-large-zh \
  --dry-run

正式迁移

npm run migrate:sqlite-to-tcvdb -- \
  --plugin-data-dir ~/.openclaw/memory-tdai \
  --openclaw-config-path ~/.openclaw/openclaw.json \
  --tcvdb-url http://127.0.0.1:80 \
  --tcvdb-username root \
  --tcvdb-api-key-env TCVDB_API_KEY \
  --tcvdb-database agent_memory_prod \
  --tcvdb-embedding-model bge-large-zh \
  --yes

只迁移特定记忆层

如果你只需要迁移部分记忆层，可以使用--layers参数指定：

# 只迁移L1记忆层（跳过L0原始消息和Profile）
npm run migrate:sqlite-to-tcvdb -- \
  --plugin-data-dir ~/.openclaw/memory-tdai \
  --openclaw-config-path ~/.openclaw/openclaw.json \
  --tcvdb-url http://127.0.0.1:80 \
  --tcvdb-username root \
  --tcvdb-api-key-env TCVDB_API_KEY \
  --tcvdb-database agent_memory_prod \
  --tcvdb-embedding-model bge-large-zh \
  --layers l1 \
  --yes

英文语料场景迁移

对于英文语料，可以使用英文BM25分词：

npm run migrate:sqlite-to-tcvdb -- \
  --plugin-data-dir ~/.openclaw/memory-tdai \
  --openclaw-config-path ~/.openclaw/openclaw.json \
  --tcvdb-url http://127.0.0.1:80 \
  --tcvdb-username root \
  --tcvdb-api-key-env TCVDB_API_KEY \
  --tcvdb-database agent_memory_prod \
  --tcvdb-embedding-model bge-large-en-v1.5 \
  --bm25-language en \
  --yes

迁移参数详细说明

迁移命令支持多种参数配置，以下是主要参数的详细说明：

参数	必填	默认值	说明
--plugin-data-dir	是	—	插件数据目录路径
--openclaw-config-path	是	—	openclaw.json 配置文件路径
--sqlite-path	否	<plugin-data-dir>/vectors.db	SQLite数据库文件路径
--tcvdb-url	是	—	TCVDB服务地址
--tcvdb-username	是	—	TCVDB用户名
--tcvdb-api-key	*	—	TCVDB API密钥（明文）
--tcvdb-api-key-env	*	—	包含API密钥的环境变量名
--tcvdb-database	是	—	TCVDB数据库名
--tcvdb-embedding-model	是	—	Embedding模型名称
--layers	否	l0,l1,l2,l3	要迁移的层（逗号分隔）
--dry-run	否	false	仅预览，不执行写入
--yes	否	false	跳过交互确认

注意：--tcvdb-api-key和--tcvdb-api-key-env二选一，必须提供其中一个。

迁移后的验证与配置

迁移完成后，建议进行以下验证和配置步骤：

1. 验证迁移结果：迁移命令默认会校验迁移前后的记录数，确保数据完整性。你也可以通过--summary-json-path参数将迁移摘要输出到JSON文件，便于后续分析。

2. 检查配置更新：迁移工具默认会更新openclaw.json配置文件和manifest.json，如果你希望手动管理配置，可以使用--no-apply-config和--no-rewrite-manifest参数禁用自动更新。

3. 测试Agent功能：迁移完成后，启动AI Agent，测试其记忆功能是否正常工作，确保迁移的数据能够被正确读取和使用。

常见问题解决

迁移过程中遇到连接超时怎么办？

可以通过--tcvdb-timeout-ms参数增加请求超时时间，例如：

npm run migrate:sqlite-to-tcvdb -- \
  ...其他参数...
  --tcvdb-timeout-ms 30000 \
  --yes

目标数据库已存在数据，如何进行追加迁移？

可以使用--no-fail-if-target-nonempty和--no-verify-counts参数允许目标库已有数据并跳过计数验证：

npm run migrate:sqlite-to-tcvdb -- \
  ...其他参数...
  --no-fail-if-target-nonempty \
  --no-verify-counts \
  --yes

总结

通过本文的指南，你已经了解了如何将现有AI项目迁移到TencentDB Agent Memory。从记忆层次结构的理解，到迁移前的准备工作，再到完整的迁移步骤和参数配置，以及迁移后的验证和问题解决，我们覆盖了迁移过程中的各个方面。

TencentDB Agent Memory的强大记忆管理能力将帮助你的AI Agent更好地组织和利用知识，提高协作效率和服务质量。如果你在迁移过程中遇到任何问题，可以参考项目中的详细文档或寻求社区支持。

祝你迁移顺利，让你的AI项目在TencentDB Agent Memory的支持下发挥更大的潜力！ 🚀

【免费下载链接】TencentDB-Agent-Memory TencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks. 项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory