cognee 中文指南：用 ECL 管道为 AI 智能体构建持久化知识图谱记忆层-编程实验室

cognee 中文指南：用 ECL 管道为 AI 智能体构建持久化知识图谱记忆层

【免费下载链接】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 中文社区文档为骨架，结合仓库源码进行纵深讲解。cognee 是面向 AI 应用与智能体的开源记忆层：通过可扩展、模块化的 ECL（提取 Extraction、认知 Cognition、加载 Loading）管道，把历史对话、文档、图像、音频转录等数据统一加工成语义化知识图谱，让智能体在会话之间拥有持久、可检索、可推理的长期记忆。读完本文，你将掌握 cognee 的安装配置、add → cognify → search三步核心工作流、常用环境变量与参数含义，以及底层数据管道与加载器体系的实现原理。

什么是 cognee：AI 应用的记忆层

大语言模型本身没有跨会话的持久记忆。每次对话结束后，上下文即被丢弃，智能体无法回忆"上一次我做过什么、用户偏好是什么、哪些方案曾经失败"。cognee 的定位正是补齐这一环——它作为一个记忆层，位于 LLM 与业务应用之间：

把历史对话、文档、图像、音频转录等异构数据互联并检索，形成可查询的知识网络；
通过"以图谱为记忆"的方式减少幻觉、降低开发人员工作量与成本——智能体检索到的是结构化的、带关系的事实，而非孤立文本片段；
仅使用 Pydantic 模型即可将数据加载到图形数据库与向量数据库，模型即模式，无需手写建表语句；
从 30 多个数据源摄取数据时支持数据操作（清洗、转换、路由），摄取与加工一体化。

从仓库入口文件 cognee/init.py 可以看到，import cognee暴露了完整的 V1 API（add、cognify、search、delete、update、prune、validate、visualize_graph等）与面向记忆场景的 V2 API（remember、recall、improve、forget、serve、push、export等），说明 cognee 既可以用最经典的"添加-认知-检索"三步完成知识库构建，也提供了更贴近智能体记忆语义的高级操作原语。

功能特性

互联并检索历史对话、文档、图像和音频转录——多模态内容统一进入记忆体系；
减少幻觉、开发人员工作量和成本——答案由知识图谱中的实体与关系支撑，而非仅靠模型记忆；
仅使用 Pydantic 将数据加载到图形和向量数据库——数据模型即数据库模式，见 cognee/shared/data_models.py；
从 30 多个数据源摄取数据时进行数据操作——内置多种加载器与 DLT（数据加载工具）支持，详见下文"加载器体系"。

环境要求与安装

cognee 支持 Python 3.10 至 3.14，可用pip、poetry、uv或任意 Python 包管理器安装：

pip install cognee

使用uv的等价命令为：

uv pip install cognee

快速开始：三步构建智能体记忆

第一步：配置 LLM

cognee 在运行时需要调用 LLM 完成实体抽取、关系识别与答案生成。最简单的配置方式是在代码中设置环境变量：

import os os.environ["LLM_API_KEY"] = "YOUR OPENAI_API_KEY"

也可以通过创建.env文件来配置，仓库根目录提供了完整的模板 .env.template（含全部可配置项与注释，复制为.env后按需填写即可）。在import cognee时，cognee/init.py 会自动调用dotenv.load_dotenv(override=True)加载.env文件，因此配置会在包导入阶段生效。

第二步：运行默认管道

下面这段脚本是官方文档给出的最小可用示例——添加文本、生成知识图谱、查询图谱：

import cognee import asyncio async def main(): # Add text to cognee await cognee.add("自然语言处理（NLP）是计算机科学和信息检索的跨学科领域。") # Generate the knowledge graph await cognee.cognify() # Query the knowledge graph results = await cognee.search("告诉我关于NLP") # Display the results for result in results: print(result) if __name__ == '__main__': asyncio.run(main())

示例输出：

自然语言处理（NLP）是计算机科学和信息检索的跨学科领域。它关注计算机和人类语言之间的交互，使机器能够理解和处理自然语言。

可以看到，cognee 的默认工作流只有三个 API 调用，且全部为异步函数：

步骤	API	作用
1	`await cognee.add(...)`	摄取原始数据（文本、文件、URL、S3 路径等），存入指定数据集
2	`await cognee.cognify()`	对数据集执行 ECL 管道，产出知识图谱与向量索引
3	`await cognee.search(...)`	基于图谱与向量执行语义检索，返回带上下文的答案

深入 add()：支持哪些数据形态

add是摄入管道的入口，源码位于 cognee/api/v1/add/add.py。从函数签名与文档字符串可以确认，它支持以下输入类型：

纯文本字符串：任意不以/或file://开头的字符串被视为文本内容；
文件路径字符串：绝对路径（/path/to/document.pdf）、文件 URL（file:///path/to/document.pdf）、相对路径 URL（file://relative/path.txt）、S3 路径（s3://bucket-name/path/to/file.pdf）；
二进制文件对象：open("file.txt", "rb")返回的BinaryIO；
列表：以上多种类型的混合列表可在一次调用中批量添加；
Web URL：https:///http://链接，可配合extraction_rules（CSS 选择器/XPath）或 Tavily、Keenable 等抽取服务使用。

# 添加单个文本 await cognee.add("Natural language processing is a field of AI...") # 混合批量添加 await cognee.add([ "/absolute/path/to/research_paper.pdf", # 绝对路径 "file://relative/path/to/dataset.csv", # 相对文件 URL "s3://my-bucket/documents/data.json", # S3 路径 "Additional context text" # 纯文本 ]) # 指定数据集（默认 main_dataset） await cognee.add( data="Project documentation content", dataset_name="project_docs" )

add还提供几个影响摄取行为的关键参数：

dataset_name：目标数据集名称，默认main_dataset，建议按知识领域划分数据集以组织不同领域知识；
run_in_background=True：异步后台摄取，立即返回而不等待完成；
incremental_loading：增量加载开关，默认开启；
importance_weight：数据重要性权重，默认0.5，影响后续记忆检索的加权排序；
preferred_loaders：为指定数据显式指定加载器；
user：用户对象，默认为自动创建的默认用户（default_user@example.com），用户只能访问拥有权限的数据集。

环境变量方面，add必填LLM_API_KEY；可选LLM_PROVIDER（openai默认、anthropic、gemini、ollama、mistral、bedrock）、LLM_MODEL（默认gpt-5-mini）、VECTOR_DB_PROVIDER（默认lancedb，可选pgvector）、GRAPH_DATABASE_PROVIDER（默认ladybug，可选neo4j）等。

深入 cognify()：ECL 管道做了什么

cognify是 cognee 的核心处理步骤，源码位于 cognee/api/v1/cognify/cognify.py。它把add存入的原始内容转换为结构化知识图谱，其处理管道（从源码导入的任务清单可见）大致包含：

文档分类（classify_documents）：识别文档类型与结构；
文本分块（extract_chunks_from_documents+TextChunker）：将内容切成语义上有意义的片段，可按chunk_size、chunks_per_batch控制；
实体与关系抽取（extract_graph_and_summarize）：调用 LLM 抽取实体、关系并生成摘要，产出知识图谱；
矛盾检测与时间矛盾消解（detect_contradictions、resolve_temporal_contradictions）：处理事实冲突与时间线上的矛盾；
事件与时间戳抽取（extract_events_and_timestamps、extract_knowledge_graph_from_events）：启用temporal_cognify=True时构建时序图谱；
数据点入库（add_data_points）与溯源记录（record_provenance）：写入图谱/向量库并记录数据来源。

cognify的可调参数包括：datasets（指定要处理的数据集）、chunker（自定义分块器，默认TextChunker）、graph_model（默认KnowledgeGraph，来自 cognee/shared/data_models.py）、temporal_cognify（是否启用时序认知）、dry_run（试运行）等。分块器体系位于 cognee/modules/chunking，除TextChunker外还提供CsvChunker、JsonListChunker、LangchainChunker、text_chunker_with_overlap等，可按数据形态选择。

深入 search()：多种检索模式

search是检索入口，源码位于 cognee/api/v1/search/search.py，默认query_type为SearchType.HYBRID_COMPLETION（混合补全）。检索前置条件为：数据已通过add添加、知识图谱已通过cognify构建、用户对目标数据集拥有read权限。

cognee 支持的检索类型（SearchType枚举）与适用场景：

检索类型	说明	适用场景
`GRAPH_COMPLETION`	基于完整图谱上下文的自然语言问答（推荐）	复杂问题、分析、总结、洞察
`RAG_COMPLETION`	传统 RAG，仅用文档块、不走图谱遍历	直接文档检索、具体事实查找
`CHUNKS`	纯向量相似度，返回命中的原始文本块	查找具体段落、引用、原文
`SUMMARIES`	返回预生成的内容摘要	快速概览、文档摘要
`CODE`	确定性索引查询与图谱遍历（Enola 代码图）	符号探索、依赖路径、反向影响分析
`CYPHER`	直接使用 Cypher 语法查询图数据库	高级用户、图谱调试
`FEELING_LUCKY`	智能自动选择最合适的检索类型	通用查询、不确定用哪种
`CHUNKS_LEXICAL`	BM25 风格词法分块检索	精确词匹配、停用词感知查询

# 指定检索类型与 top_k results = await cognee.search( "What are the main themes in this research?", query_type=cognee.SearchType.GRAPH_COMPLETION, top_k=15, ) # 限定数据集范围提升速度与相关性 results = await cognee.search( "How do these concepts relate to each other?", datasets=["docs", "reports"], )

常用参数：top_k（返回结果数上限，默认 15，综合场景可从 15 起步，上限 100）、datasets/dataset_ids（限定检索范围，默认跨全部有权限的数据集）、node_type/node_name（按实体类型/名称过滤）、include_references（附带引用信息）、session_id（会话记忆缓存）。注意：skills/tools/max_iter仅在使用AGENTIC_COMPLETION检索类型时可用，且要求恰好指定一个数据集。

加载器体系：30+ 数据源的摄取基础

"从 30 多个数据源摄取数据"的能力由加载器注册表支撑，定义在 cognee/infrastructure/loaders/supported_loaders.py。核心加载器包括：

TextLoader（文本）
PyPdfLoader（PDF）
CodeLoader（代码文件，解析结构与内容）
ImageLoader（图像，OCR/视觉模型抽取）
AudioLoader（音频，转写为文本）
VideoLoader（视频）
CsvLoader（CSV）

此外，注册表通过"可选导入 + ImportError 容错"的方式按需加载增强型加载器：UnstructuredLoader、AdvancedPdfLoader（高级 PDF）、BeautifulSoupLoader（网页抓取）、DoclingLoader（文档智能解析）、DltCsvLoader（通过 DLT 清单路由的 CSV，安装 dlt 扩展后优先于普通 CSV 展平）——这些加载器仅在对应依赖安装后才注册，体现了模块化与最小化依赖的设计。

性能与部署提示

仓库根 README 与配置模板中还包含两类对生产有价值的信息：

性能调优：默认配置优先记忆质量而非延迟。AUTO_FEEDBACK=false可去掉每次回答后用于自调优记忆的一次 LLM 调用，让读取更快更省；CACHING=false会彻底关闭会话记忆（remember(session_id=...)将失效），仅在完全不用会话记忆时设置；DATASET_QUEUE_ENABLED=false移除数据集级并发守卫，但多数据集并行时存在文件锁泄漏与资源耗尽风险，服务端建议保持开启。
部署形态：cognee 可自托管（本地开发完全嵌入式：SQLite、LanceDB、Kuzudb，无需额外服务），也可通过await cognee.serve(url=..., api_key=...)连接托管实例，或参考 distributed/ 目录下的 Modal、Railway、Fly.io、Render、Daytona 等一键部署脚本。