企业官网建设流程全解析

TencentDB Agent Memory：SQLite 到腾讯云向量数据库（TCVDB）离线迁移工具完全指南

【免费下载链接】TencentDB-Agent-MemoryTencentDB 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

本文导读：本文围绕 MemoryCore/scripts/migrate-sqlite-to-tcvdb/README.md 展开，系统讲解 TencentDB Agent Memory 项目中用于将 memory-tdai 插件本地 SQLite 数据迁移到腾讯云向量数据库（TCVDB）的离线迁移工具。你将掌握该工具的前置条件、编译方式、预检（dry-run）与正式迁移的完整命令行用法、全部参数语义与默认值、源码层面的执行流程与校验机制，以及迁移后 openclaw.json 与 manifest.json 的自动改写规则，可据此在生产环境中安全、可回溯地完成存储后端切换。

一、工具定位：为什么要做 SQLite → TCVDB 迁移

TencentDB Agent Memory 是一个面向 AI Agent 的团队级记忆中枢（Memory Hub），将对话、文档与代码沉淀为 Chat Memory、Skill、LLM-Wiki、Code-Graph 四类可复用记忆资产。在 MemoryCore 的存储设计中，插件运行时默认将记忆数据落在本地 SQLite（配合sqlite-vec向量检索），而当数据量增长、需要多实例共享与云端托管时，则需要将存储后端切换到腾讯云向量数据库 TCVDB。

migrate-sqlite-to-tcvdb正是为这一切换场景设计的离线迁移工具：它读取 memory-tdai 插件数据目录下的 SQLite 文件（默认vectors.db），将 L0 原始消息、L1 结构化记忆记录以及本地 Profile 数据写入 TCVDB，并自动改写插件配置与数据目录的 manifest 元数据，使存量记忆无缝迁移到云端。从源码结构看，该工具位于 scripts/migrate-sqlite-to-tcvdb/ 目录，通过 package.json 中定义的build:migrate-sqlite-to-vdb与migrate-sqlite-to-tcvdb两个 npm script 驱动编译与执行。

需要特别说明的是：该迁移脚本通过../../src/引用核心存储实现（VectorStore、TcvdbMemoryStore等），但不依赖openclaw/plugin-sdk，配置写回直接使用json5，因此它可以作为独立 CLI 在插件安装环境之外运行。

二、前置条件

开始迁移前，请确认以下环境要求（来自原文档并对照 package.json 的engines字段）：

• Node.js >= 22.16.0：迁移脚本基于 Node 内置node:util的parseArgs与node:fs/promises编写，需要较新运行时；
• 插件已通过openclaw plugins install安装：迁移目标数据来自插件数据目录（默认~/.openclaw/memory-tdai），同时迁移过程中需要读取/改写openclaw.json；
• 迁移脚本已编译：源码为 TypeScript，运行前需先执行编译（见下节）；
• TCVDB 服务可用：目标库 URL、用户名、API Key 与 Embedding 模型需要预先就绪。

三、编译迁移脚本

迁移脚本使用 TypeScript 编写，首次运行前必须编译。在 MemoryCore 根目录执行：

npm run build:migrate-sqlite-to-vdb

该命令实际执行tsc -p scripts/migrate-sqlite-to-tcvdb/tsconfig.json --noEmitOnError false（见 package.json）。编译产物输出到scripts/migrate-sqlite-to-tcvdb/dist/（已在 gitignore 中），可直接用 Node 运行。

运行时入口有两个等价方式：

1. npm script 方式：npm run migrate:sqlite-to-tcvdb -- <参数>，内部执行node ./bin/migrate-sqlite-to-tcvdb.mjs；
2. 直接调用 bin：node ./bin/migrate-sqlite-to-tcvdb.mjs <参数>。

bin/migrate-sqlite-to-tcvdb.mjs 是一个极薄的包装层，仅负责定位并动态import编译产物scripts/migrate-sqlite-to-tcvdb/dist/scripts/migrate-sqlite-to-tcvdb/cli-entry.js，真正的入口逻辑在 cli-entry.ts：调用runMigrationCli(process.argv.slice(2))，成功时将迁移摘要以 JSON 形式输出到 stdout，失败时向 stderr 输出错误并设置退出码 1。

四、使用方法与命令示例

4.1 预检模式（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 \ --dry-run

从源码实现看（sqlite-to-tcvdb.ts），预检阶段会：

• 检查插件数据目录与 SQLite 文件是否存在，若不存在（全新部署尚无数据）则返回"全零"摘要并优雅跳过，而不是报错；
• 以只读方式打开 SQLite 源库（VectorStore），统计l0Count、l1Count，并通过listLocalProfiles统计本地 Profile 数量；
• 读取 manifest（readManifest）记录当前 store 类型（sqlite/tcvdb）；
• 校验openclaw.json可读（ensureReadablePath）；
• 若指定了--summary-json-path，将摘要写入该文件。

4.2 正式迁移

确认预检结果无误后，去掉--dry-run并加上--yes跳过交互确认，即执行正式迁移：

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

正式迁移的完整执行流程（对应 sqlite-to-tcvdb.ts 中runMigrationCli的逻辑）如下：

1. 参数解析与预检：resolveMigrationCliOptions使用parseArgs（strict: true、allowNegative: true）解析全部选项，随后collectMigrationPreflight汇总源/目标信息；
2. 目标库初始化：默认通过createTargetStoreDefault构造TcvdbMemoryStore（见 tcvdb.ts），传入 URL、用户名、API Key、数据库名、Embedding 模型、超时时间与 BM25 编码器，然后调用init()；若初始化进入 degraded 模式则中止；
3. 目标库非空检查：默认（--fail-if-target-nonempty=true）会先统计目标库 L1/L0/Profiles 数量，任一非零即抛错中止，防止覆盖已有数据；
4. 分批迁移数据：以 50 条/批（DEFAULT_MIGRATION_PAGE_SIZE = 50）游标分页读取源库，按--layers选择迁移范围——L1 与 L0 走游标分页写入，Profile 通过listLocalProfiles+syncProfiles同步；
5. 数量校验：默认（--verify-counts=true）在迁移后等待约 10 秒让远端数据落盘（verifyDelayMs默认为 10000），再对比源/目标 L1、L0、Profiles 数量，不一致则抛错；
6. 配置写回：默认（--apply-config=true）将storeBackend: "tcvdb"及 TCVDB/BM25 配置写入openclaw.json；
7. manifest 重写：默认（--rewrite-manifest=true）将数据目录下的manifest.json的 store 绑定更新为tcvdb；
8. 输出摘要：最终摘要（含各层迁移数量、目标库数量、配置与 manifest 写入状态）写回 stdout，若指定--summary-json-path同时落盘。

4.3 更多典型场景

直接传入 API Key（不通过环境变量）

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 'your-api-key-here' \ --tcvdb-database agent_memory_prod \ --tcvdb-embedding-model bge-large-zh \ --yes

安全提示：明文 API Key 会出现在命令行与进程列表中，生产环境更推荐--tcvdb-api-key-env。二者必须二选一，同时提供或都未提供都会在参数解析阶段直接报错（见resolveTcvdbApiKey）。

指定自定义 SQLite 路径（数据库不在默认 vectors.db 位置时）

npm run migrate:sqlite-to-tcvdb -- \ --plugin-data-dir ~/.openclaw/memory-tdai \ --sqlite-path /backup/2026-04/vectors-snapshot.db \ --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

该场景适合从备份快照恢复迁移，--sqlite-path缺省时为<plugin-data-dir>/vectors.db。

只迁移 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

只迁移 L0 和 L1（不迁移 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 l0,l1 \ --yes

--layers接受逗号分隔的层名，合法值为l0,l1,l2,l3（ALL_MIGRATION_LAYERS）。从 sqlite-to-tcvdb.ts 的实现看，L0/L1 分别由migrateL0Records/migrateL1Records处理，而Profile 的迁移由--layers中的l2或l3触发（options.layers.includes("l2") || options.layers.includes("l3")时调用migrateProfiles）。

英文语料场景：使用英文 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

禁用 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-zh \ --no-bm25-enabled \ --yes

BM25 编码器由 bm25-local.ts 的createBM25Encoder创建：当enabled=false时返回空编码器；否则以zh或en语言初始化本地 BM25 编码器。开启 BM25 后，迁移写入的数据会同时携带稀疏向量，检索时支持"密集 + 稀疏"混合召回。

仅迁移数据，不自动更新 openclaw.json 和 manifest（手动管理配置）

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 \ --no-apply-config \ --no-rewrite-manifest \ --yes

追加迁移：允许目标库已有数据，跳过非空检查

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 \ --no-fail-if-target-nonempty \ --no-verify-counts \ --yes

输出迁移摘要到 JSON 文件（适合 CI/自动化流水线）

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 \ --summary-json-path ./migration-report.json \ --job-id "migrate-2026-04-13" \ --yes

摘要 JSON 会先mkdir目标目录再落盘（writeSummaryJson），内容包含源数据统计、目标配置、选项快照以及迁移结果（各层迁移数、目标库计数、configWritten/manifestWritten、manifestBackupPath），便于 CI 断言与审计。

设置自定义超时和别名

npm run migrate:sqlite-to-tcvdb -- \ --plugin-data-dir ~/.openclaw/memory-tdai \ --openclaw-config-path ~/.openclaw/openclaw.json \ --tcvdb-url http://10.0.1.50:80 \ --tcvdb-username admin \ --tcvdb-api-key-env TCVDB_API_KEY \ --tcvdb-database agent_memory_prod \ --tcvdb-embedding-model bge-large-zh \ --tcvdb-alias "生产环境-主库" \ --tcvdb-timeout-ms 30000 \ --yes

--tcvdb-alias会随 manifest 一起写入 TCVDB 绑定信息，便于多环境标识；--tcvdb-timeout-ms需为正整数，非法值在parseTimeout中直接报错。

五、参数说明

下表完整列出迁移工具的全部参数（含必填、默认值与说明）：

*--tcvdb-api-key和--tcvdb-api-key-env二选一，必须提供其中一个；两者同时提供会报错。

参数解析的源码细节（对应 sqlite-to-tcvdb.ts 的resolveMigrationCliOptions）：

• 布尔开关支持--xxx/--no-xxx两种写法，通过parseArgs的allowNegative: true实现，因此--no-apply-config、--no-verify-counts等与表格中的默认值语义完全对应（resolveBooleanOption仅在值为 boolean 时覆盖默认值）；
• --layers会做去重与合法性校验（parseLayers），出现未知层名（如--layers foo）直接抛错；
• --bm25-language仅接受zh/en（parseBm25Language）；
• 必填参数缺失、API Key 未提供、环境变量为空等都会以清晰错误信息终止（getRequiredString/resolveTcvdbApiKey）。

六、迁移后的配置与元数据自动改写

正式迁移成功后（除非显式禁用），工具会自动完成两项关键改写，保证插件下次启动即使用 TCVDB 后端：

6.1 改写 openclaw.json（--apply-config）

config-write.ts 使用json5解析单文件 JSON/JSON5 配置（解析失败会抛出明确错误，说明该写回器仅支持单文件配置），然后按插件 ID 定位plugins.entries.<pluginId>.config并深度合并补丁。写入的配置结构为：

// openclaw.json 中 plugins.entries.<pluginId>.config 的最终形态 { storeBackend: "tcvdb", tcvdb: { url: "<tcvdb-url>", username: "<tcvdb-username>", apiKey: "<tcvdb-api-key>", database: "<tcvdb-database>", alias: "<tcvdb-alias>", embeddingModel: "<tcvdb-embedding-model>", timeout: <tcvdb-timeout-ms> }, bm25: { enabled: true, language: "zh" } }

合并采用"保留原有字段 + 覆盖补丁字段"的策略（applyPluginConfigPatch），不会破坏插件原有的其他配置项。默认（--config-backup=true）在写入前会备份原配置文件，但从 config-write.ts 当前实现看，备份能力由参数控制并在上层决定调用方式，生产环境建议自行保留原配置副本以便回滚。

6.2 重写 manifest.json（--rewrite-manifest）

manifest-write.ts 负责更新数据目录下.metadata/manifest.json（路径定义见 manifest.ts）。manifest 是数据目录的自描述元数据，包含 store 绑定（sqlite/tcvdb）与 seed 信息。重写逻辑：

• 若 manifest 不存在，则创建version: 1的新 manifest，store 类型为tcvdb（含 url、database、可选 alias），并返回created: true；
• 若已存在，默认先备份为manifest.json.migrate.bak（同目录），再用buildStoreInfo({ type: "tcvdb", ... })替换 store 绑定，其余字段（如createdAt、seed）原样保留，返回updated: true与备份路径；
• 备份路径会记录在迁移摘要的manifestBackupPath字段中，便于追溯。

七、目录结构与代码组织

scripts/migrate-sqlite-to-tcvdb/ ├── cli-entry.ts # CLI 入口（调用 runMigrationCli，输出 JSON 摘要） ├── sqlite-to-tcvdb.ts # 迁移核心逻辑（参数解析、预检、分批数据迁移、数量校验） ├── config-write.ts # OpenClaw 配置更新（JSON5，自包含） ├── manifest-write.ts # Manifest 重写（含迁移备份 manifest.json.migrate.bak） ├── *.test.ts # 就近放置的测试文件 ├── tsconfig.json # 迁移脚本编译配置 ├── dist/ # 编译产物（已 gitignore） └── README.md # 本文件 bin/migrate-sqlite-to-tcvdb.mjs # 极薄 bin 包装 → dist/

各模块职责边界清晰：cli-entry.ts只做入口转发；sqlite-to-tcvdb.ts承载全部迁移编排（同时导出runMigrationCli、resolveMigrationCliOptions、collectMigrationPreflight等可复用函数，并支持依赖注入RunMigrationCliDeps，便于测试）；config-write.ts与manifest-write.ts分别隔离了"配置写回"与"元数据重写"两个副作用操作。

迁移脚本通过../../src/引用存储实现（VectorStore、TcvdbMemoryStore等），其中：

• VectorStore（sqlite.ts）负责源库只读打开与游标分页查询（queryL1RecordsCursor/queryL0RecordsCursor）；
• TcvdbMemoryStore（tcvdb.ts）负责目标库写入，提供upsertL1Batch、upsertL0Batch、countL1、countL0、pullProfiles、syncProfiles等批量接口，迁移工具优先走批量写入路径，失败时回退到逐条写入；
• 集合命名规则为${database}_${SUFFIX}（如agent_memory_prod_l1），以保证 TCVDB 实例内集合全局唯一，避免跨库冲突。

八、执行流程总览与最佳实践

8.1 完整执行流程

参数解析 (resolveMigrationCliOptions) │ ▼ 预检 (collectMigrationPreflight) ├── 源目录/SQLite 不存在 → 返回全零摘要并跳过 ├── 统计 L0/L1/Profiles 数量、读取 manifest └── 校验 openclaw.json 可读 │ ▼ dry-run ? ──是──→ 输出摘要，结束（不写任何数据） │ ▼ 初始化目标 TcvdbMemoryStore（校验非 degraded） │ ▼ 目标库非空检查（--fail-if-target-nonempty=true 时） │ ▼ 分批迁移（每批 50 条游标分页） ├── l1 → migrateL1Records ├── l0 → migrateL0Records └── l2/l3 → migrateProfiles（listLocalProfiles + syncProfiles） │ ▼ 数量校验（--verify-counts=true：等待 10s 落盘后对比源/目标计数） │ ▼ 写回 openclaw.json（--apply-config=true，json5 深度合并） │ ▼ 重写 manifest.json（--rewrite-manifest=true，先备份 .migrate.bak） │ ▼ 输出/落盘迁移摘要（--summary-json-path）

8.2 生产环境最佳实践

1. 先 dry-run 后正式迁移：预检模式零副作用，能提前暴露路径错误、权限问题与数据规模，建议作为上线流程的第一步；
2. 使用环境变量承载 API Key：优先--tcvdb-api-key-env，避免密钥进入 shell 历史与进程列表；
3. 保留备份与审计痕迹：开启--summary-json-path+--job-id记录每次迁移的任务标识与统计，manifest 自动备份为manifest.json.migrate.bak，openclaw.json 也建议自行留存迁移前副本；
4. 明确迁移范围：仅需要语义记忆时用--layers l1，需要保留原始对话与画像时用--layers l0,l1,l2,l3（注意 Profile 迁移由 l2/l3 触发）；
5. 按语料选择 BM25 语言与 Embedding 模型：中文语料用bge-large-zh+--bm25-language zh，英文语料用bge-large-en-v1.5+--bm25-language en；
6. 追加迁移需显式授权：目标库已有数据时，必须同时提供--no-fail-if-target-nonempty与--no-verify-counts才能继续，这层默认保护能防止误覆盖生产库；
7. HTTPS 场景配置 CA：若 TCVDB 走 HTTPS 且使用自签证书，可通过--tcvdb-ca-pem指定 CA 证书 PEM 路径。

九、常见问题排查

十、总结

SQLite → TCVDB 迁移工具是 TencentDB Agent Memory 从本地单机存储升级到云端向量库的关键路径工具。它通过"预检 → 分批迁移 → 数量校验 → 配置写回 → manifest 重写"五个阶段的完整编排，配合丰富的开关参数（层选择、BM25 语言、超时、别名、摘要输出、非空检查等），让存储后端切换既安全（默认非空保护与计数校验）又可追溯（job-id + 摘要 JSON + manifest 备份）。结合 sqlite-to-tcvdb.ts、config-write.ts、manifest-write.ts 等源码，开发者可以深入理解其实现细节，并在自己的生产环境中安全地复现这一迁移流程。

【免费下载链接】TencentDB-Agent-MemoryTencentDB 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