从 mem0 迁移记忆到 CogneeMem0Source 三种导入模式与知识图谱重建实战【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee本指南以 cognee 仓库中的可运行教程 migrate_from_mem0.py 为主线系统讲解如何通过Mem0Source把 mem0 平台导出或 OSS dump 的记忆数据导入 Cognee 的知识图谱并支持preserve、re-derive、hybrid三种导入模式。读完本文你将掌握 mem0 导出数据的格式要求、三种模式的取舍逻辑、remember → cognify → recall的完整调用链以及导入背后的 COGX 中间格式与字段映射原理可直接上手完成一次真实的记忆迁移。一、为什么需要记忆迁移从 mem0 到 Cogneemem0 以“原子化短事实文本”的形式存储 Agent 的记忆而 Cognee 面向的是持久化的知识图谱引擎——实体、事实三元组、时间戳与来源信息都以图结构组织。当你希望把已在 mem0 中积累的对话记忆、用户画像、业务事实搬进 Cognee并让这些记忆能够被图谱化查询recall、继续增量演进时就需要一个结构化的迁移通道。Cognee 的迁移能力建立在 COGXCognee eXchange format中间格式之上外部记忆系统Mem0、Zep/Graphiti、Letta 等被翻译成 COGX 记录流再由统一的迁移 loader 写入 Cognee。Mem0Source正是这条链路上针对 mem0 的适配器其源码位于 cognee/modules/migration/sources/mem0.py基类MemorySource位于 cognee/modules/migration/sources/base.py。二、Mem0Source 与三种导入模式Mem0Source的构造签名mem0.py为Mem0Source(data: Union[str, Path, List[Any], Dict[str, Any]], mode: str re-derive)datamem0 导出内容可以是文件路径、JSON 字符串、已解析的 Python 列表或字典mode导入保真模式可选值定义在 base.py 的IMPORT_MODES (re-derive, preserve, hybrid)默认re-derive。三种模式的语义base.py模式行为是否调用 LLM适用场景re-derive默认把原始记忆文本当作数据项DataItem摄入运行 Cognee 自己的抽取管线cognify重建图谱源系统已派生的图结构被忽略是希望用 Cognee 的抽取与本体标准重新理解记忆preserve把 mem0 记忆直接映射为图节点写入零 LLM 调用原始文本作为数据项存储但不做 cognify否但 recall 查询仍需要 LLM 能力快速导入、节省 token或追求导入速度hybrid既保留源图结构又对原始内容执行 cognify是既要完整性又要 Cognee 重新抽取需要特别说明在preserve模式下若希望后续对导入数据做 recall 检索除了初次remember之外还需要额外执行一次cognify()这会调用 LLM教程脚本第 2 步的注释明确指出了这一点。三、mem0 导出数据的格式要求Mem0Source支持 mem0 平台导出 API 与 OSSget_all()调用产生的两种常见形态mem0.py纯 JSON 数组[{...memory object...}, ...]包装对象{results: [...]}、{memories: [...]}、{items: [...]}三种键名均可识别此外也支持直接把已解析的 Python 列表/字典传入适合用mem0ai客户端实时拉取响应后直接喂给 source。仓库自带的示例导出文件 data/mem0_sample_export.json 展示了单个记忆对象的完整字段{ results: [ { id: mem-001, memory: Albert Einstein developed the theory of general relativity in 1915, describing gravity as the curvature of spacetime., user_id: user-01, agent_id: agent-science, run_id: run-2024-03-15, categories: [science, physics], metadata: {confidence: 0.95, source: textbook}, created_at: 2024-03-15T10:30:00Z, updated_at: 2024-03-15T10:30:00Z } ] }字段映射规则mem0.py内容提取按memory、text、data、content的顺序取第一个字符串值全部缺失则跳过该条记录categories接受字符串或字符串数组统一规范为列表缺失时为空列表作用域 scopeuser_id、agent_id、run_id会被原样保留到COGXScope定义于 cogx.py用于还原该记忆在源系统内的归属关系时间戳created_at、updated_at经parse_timestamp解析为时区感知的 UTC 时间支持 ISO 字符串、epoch 秒/毫秒/微秒/纳秒等多种形态见 cogx.py元数据metadata字段整体存入metadata{mem0_metadata: ...}不丢失源信息external_id优先取id字段缺失时退化为mem0-index。单元测试 cognee/tests/unit/migration/test_migration.py 覆盖了这些行为纯列表输入、results包装与text键、文件路径输入、无内容条目跳过、空包装别名不遮蔽有内容的包装键等场景可作为格式验证的参照。四、运行迁移教程4.1 前置条件已安装 cognee 及其依赖建议使用uv运行在.env中配置LLM_API_KEYre-derive模式与recall查询都需要调用 LLM。4.2 执行命令在仓库根目录运行教程 README 中的原始命令uv run python examples/demos/ingestion_and_migration/migrate_from_mem0/migrate_from_mem0.py4.3 脚本执行流程脚本主体位于 migrate_from_mem0.py按七个步骤推进Step 0 — 初始化与清理调用create_db_and_tables()确保关系型数据库表就绪随后await cognee.forget(everythingTrue)清空历史状态保证导入的幂等起点。Step 1 — 检查导出文件打印样本文件路径examples/demos/ingestion_and_migration/migrate_from_mem0/data/mem0_export.json。Step 2 — preserve 模式导入source Mem0Source(DATA_FILE, modepreserve) result await cognee.remember(source) await cognee.cognify()注意这里remember之后紧跟一个显式cognify()——正如前文所述这是 preserve 模式下使 recall 可用的必要条件。Step 3 与 Step 4 — recall 验证分别查询 What database does the project use? 与 Who is Alices manager?逐条打印返回答案。Step 5 — 切换到 re-derive 模式再次forget(everythingTrue)清库后以modere-derive重新remember。此时不需要手动cognify()因为该模式下 loader 会把记忆文本送入标准add cognify路径由 Cognee 自己的抽取管线自动建图见 loader.py。Step 6 — 再次 recall查询 What are the Q2 OKRs?对比两种模式下的检索结果差异。Step 7 — 清理forget(everythingTrue)收尾。日志配置为setup_logging(log_levelERROR)仅输出错误级别日志避免干扰演示输出。五、底层原理COGX 记录与 loader 翻译5.1 Mem0Source 产出 COGXMemoryMem0Source.records()是一个异步迭代器把每条 mem0 记忆翻译成COGXMemory记录cogx.pyclass COGXMemory(COGXRecordBase): kind: Literal[memory] memory content: str categories: List[str] Field(default_factorylist)所有 COGX 记录共享external_system、external_id、scope、created_at、updated_at、metadata基础字段由COGXRecordBase统一提供cogx.py。COGX 记录体系还包括 document、episode、entity、fact、memory_block、raw_node 等类型COGXRecord是它们的联合类型。5.2 loader 的两种翻译目标迁移 loader loader.py 根据导入模式把 COGX 记录翻译成两类下游输入数据项data itemsre-derive模式文本类记录含COGXMemory被包装为DataItemdata_id由uuid5(NAMESPACE_OID, fcogx:{external_system}:{external_id})确定性生成loader.py使重复导入同一记录具备幂等性。随后走标准add cognify路径重建图谱。在re-derive模式下源系统的实体描述与事实还会被渲染成“entities-digest”“facts-digest”摘要文档每 200 条事实一个 digest见 loader.py 与 loader.py确保派生的知识不因重新抽取而丢失。图批次graph batchespreserve/hybrid模式entity/fact 记录被映射为原生Entity数据点与自定义边元组通过add_data_points任务零 LLM 直接入库loader.py。实体 ID 使用与 cognify 抽取一致的Entity.id_for(name)类命名空间方案因此保留的边能与已有图词汇表合并而不是形成孤立的平行图loader.py源事实的时间有效性valid_at/invalid_at会以边属性的形式保留_fact_edge_propertiesloader.py。5.3 批量与流式处理为控制批量导入的内存与事务边界非流式路径按BATCH_NODE_TARGET 2000节点切分批边批次上限为EDGE_BATCH_TARGET 2 * BATCH_NODE_TARGETloader.py 与 loader.pypreserve 模式采用两遍流式导入stream_graph_from_sourceloader.py第一遍流式写入 raw nodes 与实体实体先缓冲以完成同名合并第二遍再次流式读取记录仅凭精简的 ID 注册表解析事实并冲刷边批次。这要求 source 可重放——基类的replayable: bool True表明所有内置 source 每次调用records()都会重新读取文件返回全新迭代器base.py无法解析引用如事实指向档案中不存在的 UUID 节点的事实会被跳过并计数绝不会伪造以 UUID 命名的实体loader.py。六、三种模式的选择建议结合教程与源码三种模式的决策要点可归纳为追求导入速度、节省 token选preserve。零 LLM 导入但务必记住补一次cognify()才能让 recall 生效且最终图谱质量取决于 mem0 原有记忆文本的结构化程度追求图谱质量与一致性选re-derive默认。让 Cognee 用自己的本体抽取与实体识别能力重建图谱代价是消耗 LLM token既要源图又要重新抽取选hybrid。保留源图结构的同时对原始内容做 cognify是迁移数据的完整归档方案同样需要 LLM 支持。任何模式下的recall查询都依赖 LLM因此.env中的LLM_API_KEY是运行本教程的硬性前置条件。七、常见问题与注意事项导出格式不被识别Mem0Source会抛出ValueError提示期望列表或带results/memories键的字典mem0.py。注意多个包装键并存时空别名不会遮蔽后续有内容的键测试test_empty_wrapper_alias_does_not_shadow_the_populated_one验证了此行为。非法 mode 值构造时传入IMPORT_MODES之外的字符串会立即抛出ValueErrorbase.py对应测试位于 test_migration.py。时间戳解析无时区偏移的时间值一律按 UTC 解读避免混合 naive 与 aware 时间导致排序或比较异常cogx.py。重复导入的幂等性COGX 记录的确定性data_id使相同记录重复导入不会产生重复节点preserve 模式流式路径还会在解析层面去重第一条事实优先规避批量 MERGE 在 Ladybug 等图引擎上的冲突loader.py。迁移不止于 mem0同一MemorySource抽象还实现了 Zep/Graphiti、Letta 等来源见 cognee/migration/init.py 的导出列表并支持cognee.export将 Cognee 数据集导出为 COGX 归档以便跨实例迁移或备份恢复本文的三种模式与调用模式可平移复用。八、延伸阅读教程说明文档examples/demos/ingestion_and_migration/migrate_from_mem0/README.md完整演示脚本migrate_from_mem0.py样本导出数据data/mem0_sample_export.json迁移 API 入口与导出清单cognee/migration/init.pyCOGX 格式定义与解析cognee/modules/migration/cogx.py迁移 loader 与图批次构建cognee/modules/migration/loader.py迁移单元测试cognee/tests/unit/migration/test_migration.py【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考