Cognee 深度拆解：文档怎样变成 Agent 可用的关联知识？

Memory Agent 深度拆解 · 第 6 / 8 篇。查看系列目录。

需求写在文档里，接口在代码里，某次事故的原因躺在复盘中。

用户问“这次修改会影响哪些功能”，答案可能散落在这三种材料里。把它们各自做成向量，只完成了寻找相似片段的准备，还没有把对象、关系与来源组织起来。

Cognee 值得从这个角度理解：它提供一条把资料转成关联知识，再组织给 Agent 使用的流水线。

本文依据 2026 年 9 月 22 日的提交 663a2dc15d04。分析来自公开代码与文档，没有执行摄入、检索或性能测试。

1. 从 remember/recall 往下看

当前 Cognee 的公开入口强调 remember() 和 recall()。前者协调摄入及后续处理，后者寻找并返回相应上下文或结果。旧资料里常见的 add → cognify → search，仍能帮助理解底层分层。官方仓库

但两行接口不代表两步内部操作。

remember() 的源码中可以看到数据集、会话、内容哈希、处理项数、流水线 ID、后台任务和改进结果等概念。它承担的职责，是给多阶段工作提供一个较统一的入口。源码：remember

对接应用时，最好将流水线标识带入日志。否则一个文件“上传过了”，很难追到它究竟完成了哪一步。

2. cognify：把内容转换为可连接的对象

cognify 承担将摄入数据组织为知识图谱的工作。源码包含文档分类、分块、图抽取与摘要、数据写入，以及按配置选择的时间处理、来源记录等任务。源码：cognify

从应用角度，可以把它理解为对同一份材料建立不同的访问线索：

源文档
 ├─ 内容片段：保留具体措辞与局部证据
 ├─ 实体与关系：连接材料中的对象
 └─ 摘要等派生内容：辅助把握整体

上图是概念整理，各抽取器与配置不会产生完全相同的输出。

如果把所有内容都压成一段总结，细节可能丢失；如果只保存碎片，跨文档联系又很难利用。多种表示并存，是为了让不同问题能找到合适的证据形式。

代价则是维护多个派生结果。源文档更新之后，旧关系、旧摘要与旧向量怎么处理，往往比第一次导入更难。

3. 没有生成式 LLM，也能有摄入路径

当前仓库提供本地文本工作流，并说明部分路径可不依赖生成式 LLM；cognify 也有不同 extractor 选项。官方使用说明、源码：抽取器参数

这件事需要精确表述。“不用生成式 LLM”不等于不使用任何模型，embedding 或本地抽取模型仍可能存在；也不意味着语音、图片和任意复杂任务都走同一条路径。

选型时应按输入与输出拆开：纯文本想获得什么关系，代码想获得什么结构，回答是否需要生成。然后再决定哪些阶段使用模型、哪些阶段用确定性程序。

这种拆法也方便控制成本。无需让每个文件都经过同样昂贵的处理，前提是你能验证简化路径保留了任务所需的信息。

4. recall 可能先命中会话，而不是永久知识

recall() 的一个重要分支是 session scope。当只提供 session_id、没有指定数据集或查询类型时，可以先搜索会话内容；有命中时，路径可能不必进入永久图。结果用 source 字段区分来源。源码：recall

这对产品响应很有价值，因为刚刚发生的互动可以直接使用。但做长期记忆验证时，它也可能让人产生误判。

同一会话里问出答案，只说明某条可用路径找到内容。要验证持久知识，应换独立会话、明确数据集与 scope，并检查实际返回来源。

这也是为什么评测不能只写“调用 recall，答对了”。输入参数决定系统测试的是哪一层。

5. 查询路由，为什么刻意保持克制？

当前 query_router.py 使用按顺序检查的规则选择检索策略，未命中时回到 HYBRID_COMPLETION。它不会为每个普通问题额外调用 LLM 来决定路由。源码：规则路由

代码还特意不将看似 Cypher 的文本自动送到数据库执行。因为检索接口的读取权限，不能自然扩展为对任意查询文本的执行授权。

显式选择某种查询类型，是另一项调用决策，也仍应配合权限与参数检查。这里能学到的，是不要把“智能识别意图”变成无限扩大操作能力的理由。

对于中文问题，也不能仅凭存在路由器就假设规则完全适用。当前一些规则围绕英文表达，自己的语言与任务分布需要单独验证。

6. HybridRetriever 如何把片段与图放在一起？

当前混合检索器会生成查询向量，并并行寻找内容片段以及实体与事实。实体命中之后，可进一步结合关系组织上下文；可选的全局上下文又是另一项配置。源码：HybridRetriever

这让同一个回答能同时获得两种材料：原文说了什么，以及相关对象之间如何联系。

比如排查接口变更，片段可以提供具体参数约定，关系可以帮助发现相关服务或依赖。但关系的覆盖范围仍受摄入与抽取影响，图里没有出现的依赖不能凭空找回。

还有一项边界很值得肯定：当前混合检索器区分空图与查询未命中，并配置在没有上下文时跳过生成。搜索不应在完全没有资料时悄悄变成一轮普通模型聊天，否则看似流畅的回答会掩盖摄入失败。

7. completed 也有层次：基础摄入与改进要分开

RememberResult 定义了 running、completed、errored、session_stored 等状态。自动改进阶段有自己的结果与 improve_error；改进失败不一定将已经成功的记忆摄入改成失败。源码：RememberResult

这比用一个布尔值描述所有事情更准确。

文件已进入知识库，但经验改进失败，应用应知道哪些能力可用、哪些需要重试。反过来，仅仅存入 session，也不等于永久图已完成构建。

后台模式还有生命周期问题：进程结束前，任务是否真正完成？源码为后台任务保留引用并接入等待与退出排空机制。接入方仍需正确使用这些约定，不能发出请求后立即销毁进程，就认为数据一定已经完成处理。

8. 更新与失败恢复，是长期使用的真实考题

Cognee 有针对 cognify 的回滚处理模块，这表明多阶段写入需要专门照顾失败后的清理。模块存在并不等于所有外部存储都构成一笔全局事务。源码：回滚处理

我会拿一份有版本变化的接口文档测试：先导入旧版，生成关联知识，再导入新版并删除旧约定，最后分别问“现在怎么调用”和“过去怎么调用”。同时检查返回的是原文、旧摘要还是图中的遗留关系。

再模拟一个批次中途失败，确认成功项、失败项、重试项能分清。相比一次 demo 回答，这更接近企业资料持续变化的现实。

9. 什么时候选这条路线？

当 Agent 要持续使用文档、代码和其他资料，并需要把局部内容与关联结构结合起来时，Cognee 值得研究。它带来的工作量也更接近知识工程：资料更新、权限、摄入状态、派生知识和查询类型都要管理。

如果只想保留几条用户偏好，未必需要这么完整的处理链。

Cognee 最值得借鉴的，是将一份材料的原文、结构与使用路径拆开。一个助手能找到答案，应该能进一步说清：它从哪种资料、哪一层表示、哪个版本里找到的。

系列阅读

返回系列目录与全景总览。

上一篇：Hindsight 深度拆解。

下一篇：MemOS 深度拆解。