拆解2.8万Star开源项目Cognee:如何基于知识图谱做RAG和Agent记忆
项目:topoteretes/cognee
Stars:27.1k | 语言:Python 85% | 许可:Apache-2.0
Cognee是面向智能体的开源AI记忆平台。它用一套可本地部署的知识图谱引擎,为AI智能体提供跨会话的持久长期记忆。项目实现路径本质还是基于RAG的那套体系。
记忆数据分两层摄入:
- 知识记忆
把文档、PDF、代码库等领域的知识,通过 cognee.add()+cognify()构建成知识图谱 - 会话记忆
把对话片段、用户偏好、交互模式等会话内容通过 cognee.remember()存入系统,并且支持session_id维度的缓存
项目自身提供的Claude Code插件是典型的应用场景:记录prompts、工具调用轨迹和助手回复,在会话结束时自动同步到知识图谱。
部署使用
Cognee的部署门槛很低:只要接入一个LLM的API key就能跑,因为它所有的默认数据库都是类似SQLite这种单文件数据库。
最小依赖
uv pip install cognee
只需要一个环境变量:
LLM_API_KEY="your_openai_api_key"
默认的嵌入式存储,不需要额外服务:
补充一个细节:项目文档里仍然把本地图库入口写成Kuzudb,但源码配置里的默认
GRAPH_DATABASE_PROVIDER已经是ladybug,只是继续兼容旧的kuzu命名和历史数据路径。Ladybug是Kuzu的直接继承者和活跃的开源分支。Kuzu原开发团队的核心成员被苹果公司收购后,原项目被归档停止维护,开源社区接管并启动了Ladybug,负责修复安全漏洞并持续推进。社区称它为“图数据库界的DuckDB”
生产环境
生产环境部署建议直接切到PostgreSQL,而且也是一个数据库搞定图、向量、会话、元数据存储,部署也很方便:
pip install "cognee[postgres]"# .envDB_PROVIDER=postgresVECTOR_DB_PROVIDER=pgvectorGRAPH_DATABASE_PROVIDER=postgresCACHE_BACKEND=postgresDB_HOST=localhostDB_PORT=5432DB_USERNAME=cogneeDB_PASSWORD=cogneeDB_NAME=cognee_db
项目的CI benchmark说明是:同样跑在PostgreSQL上时,搜索速度比“图+向量分离”的方案快约10%,但是没说召回准确率相关的数据。
可换后端数据库
图数据库:可以切到 postgres、neo4j、neptune向量数据库:可以切到 pgvector、chromadb、qdrant、weaviate、milvus会话缓存:支持 sqlite、postgres、redis、fs、tapes,默认是sqlite
支持 Docker 部署
# 基础 API 服务docker compose up# 加前端 UIdocker compose --profile ui up# 加 MCP 服务docker compose --profile mcp up# 全套docker compose --profile ui --profile mcp --profile postgres up
资源参考:API服务建议4 CPU / 8GB内存,MCP服务建议2 CPU / 4GB内存。
LLM 兼容性
Cognee基于litellm接主流模型提供商。切换时改provider和key就够:
LLM_PROVIDER="anthropic"LLM_API_KEY="your_anthropic_key"
litellm是一个Python SDK,以OpenAI兼容格式接入100多个LLM API,内置成本追踪和负载均衡。
怎么接入使用
Cognee的接入方式:
Python API:精确管控使用add → cognify → search。直接走Agent记忆层,用remember → recall
import cognee# graph pipelineawait cognee.add("document.pdf")await cognee.cognify()results = await cognee.search("What is...")# memory APIawait cognee.remember("User prefers detailed explanations.", session_id="chat_1")results = await cognee.recall("What does the user prefer?", session_id="chat_1")CLI命令行:适合快速验证和脚本集成
cognee-cli remember "Cognee turns documents into AI memory."cognee-cli recall "What does Cognee do?"cognee-cli forget --all
项目自带本地Web UI:cognee-cli -ui。另外这个命令背后的MCP server是跑在Docker容器里的,所以本机要能跑的起来Docker。
Claude Code插件:直接给Claude Code加持久记忆
claude plugin marketplace add topoteretes/cognee-integrationsclaude plugin install cognee-memory@cognee
插件会监听Claude Code的生命周期:SessionStart → UserPromptSubmit → PostToolUse → Stop → PreCompact → SessionEnd,自动注入上下文并在session结束时回刷知识图谱。
运行模式分本地和远端:本地模式默认会在http://localhost:8011自举本地Cognee API;远端/云端模式则改用COGNEE_BASE_URL + COGNEE_API_KEY直连远端实例。
MCP Server:标准MCP协议接入,支持HTTP / SSE / stdio三种传输模式。
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 cognee/cognee-mcp:main
多语言客户端:除Python外,官方还提供了Rust (cargo add cognee)和TypeScript (npm install @cognee/cognee-ts)客户端。
OpenClaw插件:npm install @cognee/cognee-openclaw
Docker容器:两种方式
# 方式一:从源码构建docker compose up # API 服务docker compose --profile ui up # + 前端界面(localhost:3000)docker compose --profile mcp up # + MCP 服务(localhost:8001)docker compose --profile postgres up # + PostgreSQLdocker compose --profile neo4j up # + Neo4j# 方式二:拉取预构建镜像docker run --env-file ./.env -p 8000:8000 cognee/cognee:main
Cognee Cloud:官方提供的全托管服务,通过SDK直连
import cogneeawait cognee.serve(url="https://your-instance.cognee.ai", api_key="ck_...")
其他云平台:Modal(Serverless)、Railway(PaaS)、Fly.io(边缘部署)、Render(托管Postgres),每个都有对应的部署脚本或一键部署方式。
以上是安装部署使用的介绍,下面是主要实现部分的技术拆解,目录:
数据摄入 分片策略 检索/召回 核心算法:Brute Force Triplet Search(暴力三元组搜索) GraphCompletionRetriever:默认检索器 存储架构 与传统RAG的差异 基准测试Benchmark
数据摄入
Cognee的数据处理有两层API:
- memory API
remember()、recall()、forget()、improve(), Agent记忆链路主路径 - graph pipeline API
add()、cognify()、search(),精确控制数据摄入、抽取、检索链路
如果只是Agent记忆系统,从官方quickstart看其实主要走remember/recall方法
如果看具体技术实现路径,就要看add/cognify/search这些方法实现。remember()内部实现(如果不带会话ID参数)也是走add()+cognify()。
执行主链是这样:
await cognee.add("document.pdf") # 添加数据await cognee.cognify() # 构建知识图谱results = await cognee.search("What is...")add()负责接收、处理数据:
默认loader加载器覆盖PDF、CSV、JSON和普通文本,代码文件也是按文本导入 docx/pptx/xlsx这类Office文档,通常要额外装 cognee[docling]或cognee[docs]可选依赖。cognify()是核心处理步骤,把原始数据构建成知识图谱:
classify_documents把原始Data item归类成Document extract_chunks_from_documents切chunk extract_graph_and_summarize并行做chunk级图抽取和摘要 add_data_points把节点、边和embedding落到图/向量库 extract_dlt_fk_edges如果是DLT数据,再补外键边
如果启用temporal_cognify=True,这条链会换成事件/时间戳抽取的时间线流水线(temporal pipeline)。
remember() 先决定走哪条摄入路径
remember()是统一的记忆注入入口,根据参数走不同的模式:
无session_id(永久记忆):自动运行add() + cognify();如果不手动关闭self_improvement,还会继续跑一次improve()做enrichment增强
有session_id(会话记忆):先写会话缓存(session cache);只要self_improvement=True,后台就会异步improve(dataset=..., session_ids=[session_id]),把session的Q&A和trace桥接回永久图,同时把feedback作用到图元素权重上
这里的
self_improvement不是一个抽象的“自动优化”开关,而是remember()默认附带的第二段处理:对永久记忆路径,它会在cognify()之后继续跑improve(),给图补三元组嵌入(triplet embedding)和索引;对会话记忆路径,它会把session里的内容异步桥接回永久知识图谱,让后续检索不只停留在临时cache。
会话内容是有时效性的,系统对此的处理方式如下:
会话缓存本身有独立生命周期,默认TTL是7天;但improve(session_ids=...)把会话桥接到永久图时,当前实现主要是把整段Q&A序列化后写进user_sessions_from_cache这个node set,并不会把cache的TTL语义原样带到图里。
这意味着,Cognee现在对“这是不是时效性记忆”的区分,更多还是靠来源分层和上层策略,也就是需要外部业务系统处理,项目不包含永久图内建的过期治理:
user_sessions_from_cache把原始会话回灌进图,适合保留可复用问答、偏好、反馈线索,也方便后续追溯 session_learnings先经过会话上下文的置信度和有害内容门控(harmful gating),再提炼成经验(lesson),更适合长期沉淀的“提炼后记忆”
所以“哪些值得永久化、哪些只是临时上下文、是否要在session end时同步、是否要过滤路径/任务状态/一次性噪音”这些,更多还是你在外层决定。
remember()示例
# 永久记忆:进入知识图谱await cognee.remember("Einstein was born in Ulm.")# 会话记忆:先写缓存,后台同步到图await cognee.remember("User prefers detailed explanations.", session_id="chat_1")remember()还支持结构化记忆条目:
- QAEntry
问答对(问题、上下文、答案、反馈) - TraceEntry
Agent追踪步骤(函数调用、状态、输入输出) - FeedbackEntry
用户反馈(关联到某个QA) - SkillRunEntry
技能运行记录
这些条目类型让Agent记住的不只是文本,还有问答、工具调用轨迹、反馈和技能运行结果。
分片策略
分片链路执行是在永久记忆路径进入
cognify()之后,如果参数带session_id,首次写入不会走分片逻辑,但是如果self_improvement开启,需要把会话写入永久图,这时候也可能发生分片(把会话内容序列化后分片)。
Cognee默认的分片处理器是TextChunker。它的执行顺序是一条四层流水线:
async def TextChunker.read(document): buffer = [] buffer_size = 0 for text_block in document.get_text(): for chunk_data in chunk_by_paragraph( text_block, max_chunk_size=max_chunk_size, batch_paragraphs=True, ): if buffer_size + chunk_data["chunk_size"] buffer.append(chunk_data) buffer_size += chunk_data["chunk_size"] elif not buffer: # 单个 chunk 本身就够大,直接产出 yield DocumentChunk(text=chunk_data["text"], ...) else: # 把前面攒下来的段落块拼成一个正式 DocumentChunk yield DocumentChunk(text=" ".join(chunk["text"] for chunk in buffer), ...) buffer = [chunk_data] buffer_size = chunk_data["chunk_size"]def chunk_by_paragraph(text, max_chunk_size): # 按 sentence 流累积,超上限时切一块 for paragraph_id, sentence, sentence_size, end_type in chunk_by_sentence( text, maximum_size=max_chunk_size, ): accumulate_sentences_until_limit()def chunk_by_sentence(text, maximum_size): # 用 embedding tokenizer 计 token;句子超上限就切成 sentence_cut for word, word_type in chunk_by_word(text): accumulate_words_until_sentence_end_or_size_limit()def chunk_by_word(text): # 先切最底层 token:单词 / 空格 / 句末符 / 段落换行 yield word_or_sentence_boundary
它尽量保住词边界,再保句子边界,再拼成段落块,最后由TextChunker聚合成真正写入图谱的DocumentChunk。
DocumentChunk字段包含:text、chunk_size、chunk_index、document_id、document_name和contains。
其中contains初始是空列表,后面extract_graph_from_data()方法会把抽出来的chunk图谱和实体回填进去(基于LLM提取),于是形成一条chunk → contains → 节点/边的映射链,后面的检索召回也是可以通过这个字段回查DocumentChunk。
Cognee还另外提供了TextChunkerWithOverlap(带重叠)、LangchainChunker(递归字符分割)、CsvChunker(CSV专用)等分片器,但分片不是Cognee的核心,用默认的就差不多了。
检索/召回
Cognee的检索层支持17种模式,但主要检索路径有三条:
CHUNKS最轻,纯向量检索,直接返回文档块 RAG_COMPLETION中间态,用文档块做传统RAG,再交给LLM生成答案 GRAPH_COMPLETION最重,也是Cognee的主要能力,先从图里找相关三元组,再让LLM组织回答
如果显式设置GRAPH_COMPLETION模式,走的是知识图谱三元组,不是完整的文档块,而且这条路径的前提是数据摄入的时候跑过cognify(…