OpenHuman 记忆数据迁移指南：从 OpenClaw 与 Hermes Agent 工作区导入记忆（migrate 命名空间）

OpenHuman 记忆数据迁移指南从 OpenClaw 与 Hermes Agent 工作区导入记忆migrate 命名空间【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman导读本文讲解 OpenHuman 内置的记忆迁移助手src/openhuman/config/migration_helpers/如何把其他 AI 助手OpenClaw、Hermes Agent工作区中积累的长期记忆通过migrate.openclaw/migrate.hermes两个 RPC 控制器导入当前 OpenHuman 工作区的记忆后端。读完本文你将掌握源工作区的路径解析规则、OpenClaw SQLite 与 Markdown 记忆的读取方式、Hermes 固定文件映射、dry-run 演练模式、幂等重跑与冲突重命名策略、迁移前的自动备份机制以及通过 CLI / JSON-RPC 安全执行迁移的完整流程。模块定位用户记忆数据迁移而非配置 schema 升级在 OpenHuman 的代码库中存在两个名字相近但职责完全不同的模块理解二者的区别是使用本模块的前提src/openhuman/config/migration_helpers/单数 migration_helpers本文主角用户主动触发的 RPC 服务负责把其他厂商 AI 助手工作区里的用户记忆数据brain.db、MEMORY.md等导入当前工作区对应migrate命名空间下的两个控制器src/openhuman/config/migrations/复数 migrations自动运行的 schema 版本迁移器由Config::schema_version门控在Config::load_or_init时执行负责持久化config.toml与会话转录数据的版本升级与用户记忆无关。从 migrations/README.md 的模块文档可以看到同样的对照说明migrations复数是每次工作区首次启动新构建时触发一次的自动 schema-version runner而migration_helpers单数是用户触发的、从旧 OpenClaw 工作区导入记忆的 RPC。模块结构与公共 APImigration_helpers是一个典型的core 逻辑 ops 适配 schemas 注册三层结构目录下共 8 个文件文件职责mod.rs仅做导出声明core/ops/schemaspub use core::*与pub use ops::*将ops别名导出为rpc并对外暴露all_migration_controller_schemas/all_migration_registered_controllers这对注册函数core.rs核心逻辑MigrationStats、MigrationReport、私有SourceEntry类型migrate_openclaw_memory/migrate_hermes_memory两个核心函数SQLite Markdown 源读取器、工作区路径解析、key/分类归一化、备份与冲突重命名辅助函数ops.rsJSON-RPC / CLI 适配层被mod.rs重新导出为rpc别名migrate_openclaw/migrate_hermes包装核心函数将anyhow::Error映射为String返回RpcOutcomeMigrationReport并附带migration completed日志schemas.rs控制器 schema 与处理器定义MigrateOpenClawParams/MigrateHermesParams参数结构、all_controller_schemas、all_registered_controllers、schemas(function)以及两个handle_migrate_*处理器core_tests.rs/ops_tests.rs/schemas_tests.rs三组单元测试覆盖归一化、路径解析、dry-run、apply、缺失源、自迁移拒绝等场景公共导出面mod.rs 重新导出类型MigrationReport、MigrationStats核心函数migrate_openclaw_memory(config, source_workspace, dry_run) - ResultMigrationReport、migrate_hermes_memory(...)RPC 函数经ops/ 别名rpcmigrate_openclaw(...) - ResultRpcOutcomeMigrationReport, String、migrate_hermes(...)控制器注册导出all_migration_controller_schemas、all_migration_registered_controllers。其中SourceEntry与core.rs内部辅助函数保持私有不构成公共 API。RPC 控制器migrate 命名空间两个控制器通过all_registered_controllers注册位于migrate命名空间参见 schemas.rs方法描述输入输出migrate.openclaw将 OpenClaw 记忆迁移到当前工作区source_workspace?: String、dry_run?: boolreport: MigrationReportmigrate.hermes将 Hermes Agent 记忆迁移到当前工作区source_workspace?: String、dry_run?: boolreport: MigrationReport两个输入字段均可选schema 中required: false。dry_run省略时默认值为true——handle_migrate_openclaw/handle_migrate_hermes使用payload.dry_run.unwrap_or(true)见 schemas.rs。这意味着在 RPC 边界上不带dry_run参数调用只会生成迁移计划而不会真正写入只有显式传dry_run: false才会实际执行迁移。这是本模块最重要的安全默认值。处理器内部通过config_rpc::load_config_with_timeout()加载配置再委托给migration_helpers::rpc::*执行。若传入未知函数名schemas()会返回一个namespace: migrate、function: unknown的占位 schema输出为error字段。一个完整的 JSON-RPC 调用示例先演练、再实迁// 1. 演练模式只生成迁移计划报告 {jsonrpc: 2.0, method: migrate.openclaw, params: {dry_run: true}, id: 1} // 2. 显式指定源路径并实际执行 {jsonrpc: 2.0, method: migrate.openclaw, params: {source_workspace: /home/user/.openclaw/workspace, dry_run: false}, id: 2} // 3. 迁移 Hermes 记忆 {jsonrpc: 2.0, method: migrate.hermes, params: {dry_run: false}, id: 3}返回的RpcOutcomeMigrationReport经into_cli_compatible_json()转为 CLI 兼容 JSON包含migration completed日志与MigrationReport主体。控制器的全局注册all_migration_registered_controllers()在 src/core/all.rs 中以DomainGroup::Config分组注册进全局控制器注册表因此两个方法同时通过 CLI 与 JSON-RPC 暴露schema 注册由all_migration_controller_schemas()提供。源工作区路径解析规则迁移的第一步是确定源工作区路径。core.rs中resolve_openclaw_workspace与resolve_hermes_workspace的实现遵循显式覆盖优先否则回退到厂商默认的规则厂商显式source_workspace默认路径未提供时OpenClaw原样使用~/.openclaw/workspace经directories::UserDirs获取主目录Hermes原样使用Windows 下优先%LOCALAPPDATA%\hermes否则~/.hermes路径解析的源码证据见 core.rs其中 Hermes 的 Windows 分支用#[cfg(windows)]std::env::var_os(LOCALAPPDATA)检测环境变量对应测试见 core_tests.rs。若解析出的源工作区不存在核心函数直接bail!返回错误如OpenClaw workspace not found at {}. Provide a valid source workspace.。ops.rs层测试migrate_openclaw_returns_error_for_missing_source_workspace验证了缺失源必须作为Err浮出水面确保 JSON-RPC 调用方能拿到失败原因。自迁移防护无论哪个厂商的迁移函数在读取任何数据之前都会先做自迁移检查若解析出的源工作区与当前 OpenHuman 工作区config.workspace_dir是同一路径则直接拒绝执行。paths_equal先尝试canonicalize()规范化比较失败时退回直接路径比较见 core.rs。测试migrate_hermes_refuses_self_migration验证错误信息必须包含self-migration字样。这一防护的意义在于把当前工作区当作源迁移到自己身上毫无意义反而可能触发备份覆盖或冲突重命名因此模块选择在最前面拦截。数据源读取OpenClawOpenClaw 的记忆数据来自两类文件collect_source_entries会把二者合并后统一去重1. SQLitememory/brain.db读取逻辑位于read_openclaw_sqlite_entriescore.rs具有显著的schema 容错设计数据库以只读方式打开OpenFlags::SQLITE_OPEN_READ_ONLY绝不修改源数据先查sqlite_master确认存在名为memories的表不存在则静默返回空列表通过PRAGMA table_info(memories)读取真实列名再从候选名列表中按大小写不敏感匹配挑选列key 列候选key/id/name缺失时回退为CAST(rowid AS TEXT)content 列候选content/value/text/memory若连一个 content 类列都找不到直接报错no content-like column was detected因为无法判断内容就没有导入价值category 列候选category/kind/type缺失时回退为常量core逐行读取时key 读取失败回退为openclaw_sqlite_{idx}content 为空的记录被跳过category 经parse_category归一化。由于采用动态列检测而非硬编码 schemaOpenClaw 不同版本的memories表结构变化不会导致迁移中断——这是模块对第三方数据格式兼容性的核心设计。2. MarkdownMEMORY.md与memory/*.mdread_openclaw_markdown_entriescore.rs处理 Markdown 记忆工作区根目录的MEMORY.md若存在且非空导入为 keyopenclaw_memory_md、分类Corememory/目录下所有*.md文件以文件名去掉扩展名作为 key经normalize_key归一化分类统一为Core空文件跳过。空内容检查贯穿所有读取路径确保不会把空白文件当作有效记忆导入。数据源读取HermesHermes Agent 的迁移采用固定文件映射见hermes_file_mappingscore.rs源文件导入 key目标分类MEMORY.mdhermes_memoryMemoryCategory::CoreUSER.mdhermes_user_profileMemoryCategory::Custom(user_profile)SOUL.mdhermes_personaMemoryCategory::Custom(persona)三个文件各自独立可选缺失的文件会以 warning 形式记录如USER.md not found in ...空文件同样被跳过并告警但不会中断其他文件的导入。测试migrate_hermes_skips_missing_optional_files验证了部分文件存在时的行为migrate_hermes_apply_imports_markdown_entries则覆盖了完整三文件映射——包括SOUL.md→Custom(persona)这条曾被评审点名的分支。归一化、分类映射与去重key 归一化normalize_key从源读取的 key 会经过normalize_key处理core.rs非字母数字字符除-与_一律替换为_再修剪首尾的_若结果为空白回退为openclaw_{idx}。例如测试用例中的hello/world会变为hello_world。对于 SQLite 读取时 key 缺失的行同样在行号索引基础上回退生成openclaw_sqlite_{idx}。分类映射parse_categorySQLite 中的 category 字符串按小写匹配映射到MemoryCategory枚举源分类字符串目标MemoryCategorycoreCoredailyDailyconversationConversationpersonalCustom(personal)projectCustom(project)episodeCustom(episode)其他Custom(原字符串)即已知枚举走标准分类未知字符串兜底为自定义分类不会因为源数据出现新分类而失败。精确去重collect_source_entries在合并 SQLite 与 Markdown 来源后用key content category三元组签名做HashSet去重core.rs保证重复运行迁移时结果确定这是幂等性的第一层保障。目标端写入策略备份、跳过与冲突重命名1. 迁移前自动备份非 dry-run 模式下backup_target_memorycore.rs会把目标工作区现有的记忆产物复制到workspace_dir/memory_backup/MEMORY.md→memory_backup/MEMORY.mdmemory/brain.db→memory_backup/brain.dbmemory/目录下所有*.md→memory_backup/memory/*.md。若目标工作区本来就没有任何记忆文件则不创建备份目录并返回None成功创建备份后报告会追加一条Backup created: pathwarning。fs::copy的失败以.ok()宽容处理不阻断迁移主流程。2. 写入与冲突处理写入通过target_memory_backend获取目标记忆后端后对每个条目执行如下逻辑见migrate_openclaw_memory与migrate_hermes_memory的写入循环memory.get(, key) 查询已有条目 ├─ 不存在 → 直接 storeimported 1 ├─ 存在且内容相同 → skipped_unchanged 1跳过 └─ 存在但内容不同 → next_available_key 生成 key_1、key_2…… renamed_conflicts 1以新 key storenext_available_keycore.rs从key_1开始递增探测空闲 key确保冲突条目不覆盖已有记忆、也不相互覆盖。所有条目写入时使用空命名空间memory.store(, key, ...)与目标记忆后端的默认命名空间一致。3. 幂等性总结源端精确重复条目去重HashSet签名目标端内容未变的条目跳过skipped_unchanged冲突端内容冲突条目重命名renamed_conflicts。三者叠加使得重复执行同一迁移是安全且确定性的第二次运行时大部分条目落入skipped_unchanged。报告结构MigrationReport 与 MigrationStats无论 dry-run 还是 apply迁移都会返回MigrationReportcore.rspub struct MigrationReport { pub source_workspace: PathBuf, // 源工作区 pub target_workspace: PathBuf, // 目标工作区config.workspace_dir pub dry_run: bool, // 是否为演练模式 pub stats: MigrationStats, // 迁移统计 pub warnings: VecString, // 警告列表 }MigrationStats六个计数core.rs字段含义from_sqlite从 SQLite 读取的条目数from_markdown从 Markdown 读取的条目数imported实际写入目标后端的条目数skipped_unchanged因内容未变而跳过的条目数renamed_conflicts因内容冲突而重命名的条目数当源工作区没有任何可导入记忆时entries.is_empty()函数不会报错而是返回一份空统计报告并附上提示性 warnings如No importable memory found in ...与Checked for: memory/brain.db, MEMORY.md, memory/*.md。ops_tests.rs中migrate_openclaw_dry_run_on_empty_source_returns_report明确验证了这一空源返回报告而非报错的行为。目标记忆后端绑定与空驱动拒绝target_memory_backendcore.rs是 apply 路径的关键防护点。它通过memory::binding::for_config解析当前配置绑定的记忆驱动再经由agent::experience::ops::DriverMemory::for_config构造写入后端DriverMemory包装的是未加守卫的驱动不会受capture_max_chars截断影响因此长记忆正文可完整导入。若绑定的驱动是null driverDriverClass::Null模块会拒绝导入并精确说明原因而不是静默丢弃写入配置了[subsystems.memory] driver null——memory is disabled by configuration配置的驱动绑定失败并回退到 null——报告被拒的驱动与其原因配置了可持有数据的驱动但当前构建未编译入对应 memory 模块modulesfeature 关闭module_provider代之以 null provider——报告this build has no memory module compiled in。错误信息统一以refusing to import memory into the null driver — ... Nothing was imported; the source workspace is untouched.收尾明确承诺源工作区未被触碰。这一防护的理由在源码注释中阐述得很清楚如果迁移报告显示已导入 N 条而实际一条都没写入用户可能据此删除源工作区造成无法挽回的数据丢失。对应测试apply_refuses_and_names_the_build_when_no_memory_module_is_compiled_in#[cfg(not(feature modules))]还断言了源文件在拒绝后保持字节级一致。关键回归记录#1440ops_tests.rs中的migrate_openclaw_apply_imports_markdown_entries_into_target_workspace#[cfg(feature modules)]记录了一次重要回归此前 apply 路径dry_run false在统一命名空间记忆核心下会于create_memory_for_migration处直接中断hard-disable导致导入无法真正执行该禁用被移除后apply 路径必须能实际把 OpenClaw 源工作区的 Markdown 条目写入目标。测试用伪造的 OpenClaw 工作区仅含MEMORY.md与memory/sprint.md无需brain.db验证imported 1。Hermes 侧同样有对应的 apply 测试覆盖三个文件的完整导入imported 3、from_markdown 3。使用建议与注意事项始终先 dry-run 再 apply由于 RPC 边界上dry_run默认true未显式传参的调用只生成计划。建议先运行一次不带dry_run: false的调用查看MigrationStats确认来源与数量无误后再显式传入dry_run: false执行。迁移前确认目标记忆后端可用若配置为 null 驱动或构建未启用modulesfeatureapply 会被拒绝且源不受影响——这是保护而非故障请按错误信息给出的原因调整配置或重新构建。迁移后核对memory_backup/apply 模式会自动在workspace_dir/memory_backup/生成目标记忆的备份核对无误前不建议删除源工作区。幂等可重跑重复执行迁移会跳过未变条目、重命名冲突条目报告中的skipped_unchanged/renamed_conflicts计数可用于确认收敛。Windows 路径注意Hermes 默认源路径在 Windows 上是%LOCALAPPDATA%\hermes与其他平台的~/.hermes不同显式传source_workspace可覆盖一切默认值。总结OpenHuman 的migration_helpers模块为从其他 AI 助手切换到 OpenHuman提供了完整、安全的记忆迁移通道schema 容错的 SQLite 读取兼容 OpenClaw 不同版本固定文件映射覆盖 Hermes 的MEMORY.md/USER.md/SOUL.mddry-run 默认值 自迁移拒绝 null 驱动拒绝 自动备份 幂等写入五重保障确保任何一步都不会造成数据丢失。通过migrate.openclaw与migrate.hermes两个 RPC 控制器CLI 与 JSON-RPC 调用方都能以统一方式完成演练 → 备份 → 导入 → 报告的完整迁移闭环。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考