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三步核心工作流、常用环境变量与参数含义以及底层数据管道与加载器体系的实现原理。什么是 cogneeAI 应用的记忆层大语言模型本身没有跨会话的持久记忆。每次对话结束后上下文即被丢弃智能体无法回忆上一次我做过什么、用户偏好是什么、哪些方案曾经失败。cognee 的定位正是补齐这一环——它作为一个记忆层位于 LLM 与业务应用之间把历史对话、文档、图像、音频转录等异构数据互联并检索形成可查询的知识网络通过以图谱为记忆的方式减少幻觉、降低开发人员工作量与成本——智能体检索到的是结构化的、带关系的事实而非孤立文本片段仅使用 Pydantic 模型即可将数据加载到图形数据库与向量数据库模型即模式无需手写建表语句从 30 多个数据源摄取数据时支持数据操作清洗、转换、路由摄取与加工一体化。从仓库入口文件 cognee/init.py 可以看到import cognee暴露了完整的 V1 APIadd、cognify、search、delete、update、prune、validate、visualize_graph等与面向记忆场景的 V2 APIremember、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快速开始三步构建智能体记忆第一步配置 LLMcognee 在运行时需要调用 LLM 完成实体抽取、关系识别与答案生成。最简单的配置方式是在代码中设置环境变量import os os.environ[LLM_API_KEY] YOUR OPENAI_API_KEY也可以通过创建.env文件来配置仓库根目录提供了完整的模板 .env.template含全部可配置项与注释复制为.env后按需填写即可。在import cognee时cognee/init.py 会自动调用dotenv.load_dotenv(overrideTrue)加载.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作用1await cognee.add(...)摄取原始数据文本、文件、URL、S3 路径等存入指定数据集2await cognee.cognify()对数据集执行 ECL 管道产出知识图谱与向量索引3await cognee.search(...)基于图谱与向量执行语义检索返回带上下文的答案深入 add()支持哪些数据形态add是摄入管道的入口源码位于 cognee/api/v1/add/add.py。从函数签名与文档字符串可以确认它支持以下输入类型纯文本字符串任意不以/或file://开头的字符串被视为文本内容文件路径字符串绝对路径/path/to/document.pdf、文件 URLfile:///path/to/document.pdf、相对路径 URLfile://relative/path.txt、S3 路径s3://bucket-name/path/to/file.pdf二进制文件对象open(file.txt, rb)返回的BinaryIO列表以上多种类型的混合列表可在一次调用中批量添加Web URLhttps:///http://链接可配合extraction_rulesCSS 选择器/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( dataProject documentation content, dataset_nameproject_docs )add还提供几个影响摄取行为的关键参数dataset_name目标数据集名称默认main_dataset建议按知识领域划分数据集以组织不同领域知识run_in_backgroundTrue异步后台摄取立即返回而不等待完成incremental_loading增量加载开关默认开启importance_weight数据重要性权重默认0.5影响后续记忆检索的加权排序preferred_loaders为指定数据显式指定加载器user用户对象默认为自动创建的默认用户default_userexample.com用户只能访问拥有权限的数据集。环境变量方面add必填LLM_API_KEY可选LLM_PROVIDERopenai默认、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_documentsTextChunker将内容切成语义上有意义的片段可按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_cognifyTrue时构建时序图谱数据点入库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_LEXICALBM25 风格词法分块检索精确词匹配、停用词感知查询# 指定检索类型与 top_k results await cognee.search( What are the main themes in this research?, query_typecognee.SearchType.GRAPH_COMPLETION, top_k15, ) # 限定数据集范围提升速度与相关性 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文本PyPdfLoaderPDFCodeLoader代码文件解析结构与内容ImageLoader图像OCR/视觉模型抽取AudioLoader音频转写为文本VideoLoader视频CsvLoaderCSV此外注册表通过可选导入 ImportError 容错的方式按需加载增强型加载器UnstructuredLoader、AdvancedPdfLoader高级 PDF、BeautifulSoupLoader网页抓取、DoclingLoader文档智能解析、DltCsvLoader通过 DLT 清单路由的 CSV安装 dlt 扩展后优先于普通 CSV 展平——这些加载器仅在对应依赖安装后才注册体现了模块化与最小化依赖的设计。性能与部署提示仓库根 README 与配置模板中还包含两类对生产有价值的信息性能调优默认配置优先记忆质量而非延迟。AUTO_FEEDBACKfalse可去掉每次回答后用于自调优记忆的一次 LLM 调用让读取更快更省CACHINGfalse会彻底关闭会话记忆remember(session_id...)将失效仅在完全不用会话记忆时设置DATASET_QUEUE_ENABLEDfalse移除数据集级并发守卫但多数据集并行时存在文件锁泄漏与资源耗尽风险服务端建议保持开启。部署形态cognee 可自托管本地开发完全嵌入式SQLite、LanceDB、Kuzudb无需额外服务也可通过await cognee.serve(url..., api_key...)连接托管实例或参考 distributed/ 目录下的 Modal、Railway、Fly.io、Render、Daytona 等一键部署脚本。更多资源交互式入门notebooks/目录下的 cognee_simple_demo.ipynb、cognee_demo.ipynb示例代码examples/guides/下的simple_cognee_example.py、ontology_quickstart.py、graph_visualization.py等以及examples/demos/下的完整演示生态组件cognee-mcp/MCP 服务器、cognee-frontend/本地 UI、cognee-starter-kit/入门脚手架项目治理CONTRIBUTING.md贡献指南、CODE_OF_CONDUCT.md行为准则。如果你希望参与社区贡献欢迎参考上述文档提交改进——cognee 的开源开发强调模块化管道与可扩展的加载器/数据库适配器设计新的数据源或检索策略大多可以按既有接口低成本接入。【免费下载链接】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），仅供参考