拆解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"

默认的嵌入式存储,不需要额外服务:

数据库
职责
存储内容
SQLite
关系数据
元数据、用户、数据集、权限
LanceDB
向量存储
embedding向量
Ladybug(兼容旧Kuzu路径)
图数据库
知识图谱(实体、关系、三元组)

补充一个细节:项目文档里仍然把本地图库入口写成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()
    是核心处理步骤,把原始数据构建成知识图谱:
  1. classify_documents
    把原始Data item归类成Document
  2. extract_chunks_from_documents
    切chunk
  3. extract_graph_and_summarize
    并行做chunk级图抽取和摘要
  4. add_data_points
    把节点、边和embedding落到图/向量库
  5. 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(…

— 以上为试看内容(约 40%),开通会员后阅读全文 —