topoteretes--cognee/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Cognee - 面向智能体的开源 AI 记忆平台

Demo . Docs . 了解更多 · 加入 Discord · 加入 r/AIMemory . 社区插件与扩展

Cognee 是开源 AI 记忆平台，为 AI 智能体提供跨会话的持久长期记忆。可摄取任意格式的数据，构建自托管知识图谱，让每个智能体都能在全量上下文中回忆、关联并行动

🌐 本 README 还提供以下语言版本： : Deutsch | Español | Français | 日本語 | 한국어 | Português | Русский | 中文

📄 阅读研究论文：Optimizing the Interface Between Knowledge Graphs and LLMs for Complex Reasoning — Markovic et al., 2025

关于 Cognee

Cognee 是面向 AI 智能体的开源 AI 记忆平台。可摄取任意格式的数据，Cognee 会持续构建自托管知识图谱，为你的智能体提供跨会话的持久长期记忆。Cognee 结合向量嵌入（vector embeddings）、图推理（graph reasoning）以及基于认知科学的本体生成（cognitive-science-grounded ontology generation），让文档既可按语义搜索，又能通过随知识演进而发展的关系彼此连接。

⭐ 帮助我们触达更多开发者并壮大 cognee 社区。请为本仓库点 Star！

📚 查看我们的详细文档，了解安装与配置。

🦀 可作为 OpenClaw 插件使用 — cognee-openclaw

✴️ 可作为 Claude Code 插件使用 — claude-code-plugin

🦀 提供 Rust 客户端 — cognee-rs

🟦 提供 TypeScript 客户端 — @cognee/cognee-ts

为何使用 Cognee：

• 轻松构建企业大脑（Company Brain）- 将来自各类数据源的数据统一汇聚到一处，并用你的领域知识赋能智能体
• 知识基础设施 — 统一摄取、图/向量搜索、本地运行、本体锚定（ontology grounding）、多模态
• 持久且可学习的智能体 - 从反馈中学习、上下文管理、跨智能体知识共享
• 可靠且可信赖的智能体 - 智能体级用户/租户隔离、可追溯性、OTEL collector、审计特性

工作原理

基础用法与功能指南

想了解更多，可查看这份简短、端到端的 Colab 实操教程，了解 Cognee 的核心功能。

快速开始

只需几行代码即可试用 Cognee。

前置条件

• Python 3.10 to 3.14

步骤 1：安装 Cognee

可使用 pip、poetry、uv 或你偏好的 Python 包管理器安装 Cognee。

uv pip install cognee

步骤 2：配置 LLM

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

或者，使用我们的模板. 创建 .env 文件

要接入其他 LLM 提供商，请参阅我们的 LLM Provider Documentation.

步骤 3：运行流水线

Cognee 的 API 提供四项操作 — remember、recall、forget 和 improve：

import cognee
import asyncio


async def main():
    # Store permanently in the knowledge graph (runs add + cognify + improve)
    await cognee.remember("Cognee turns documents into AI memory.")

    # Store in session memory (fast cache, syncs to graph in background)
    await cognee.remember("User prefers detailed explanations.", session_id="chat_1")

    # Query with auto-routing (picks best search strategy automatically)
    results = await cognee.recall("What does Cognee do?")
    for result in results:
        print(result)

    # Query session memory first, fall through to graph if needed
    results = await cognee.recall("What does the user prefer?", session_id="chat_1")
    for result in results:
        print(result)

    # Delete when done
    await cognee.forget(dataset="main_dataset")


if __name__ == '__main__':
    asyncio.run(main())

使用 Cognee CLI

cognee-cli remember "Cognee turns documents into AI memory."

cognee-cli recall "What does Cognee do?"

cognee-cli forget --all

要打开本地 UI，请运行：

cognee-cli -ui

Note: 由 cognee-cli -ui 启动的 MCP 服务器在 Docker 容器内运行。 需要 Docker Desktop、Colima 或任何兼容 OCI 且 docker CLI 可正常使用的运行时。详见 Docker & Colima Setup。

使用 Docker 运行

更喜欢容器化部署？Cognee 会在每次推送到 main 时，将预构建镜像发布到 Docker Hub： cognee/cognee（API 服务器）以及 cognee/cognee-mcp（MCP 服务器）。

选项 A — Docker Compose（从源码构建）

克隆仓库，创建至少包含 LLM_API_KEY 的 .env，然后：

cp .env.template .env   # then edit .env and set LLM_API_KEY

# Start the API server (http://localhost:8000)
docker compose up

# Optional profiles (combine as needed):
docker compose --profile ui up        # + frontend on http://localhost:3000
docker compose --profile mcp up       # + MCP server on http://localhost:8001
docker compose --profile postgres up  # + Postgres/PGVector
docker compose --profile neo4j up     # + Neo4j

cognee 与 cognee-mcp 服务会发布不同的主机端口（8000 与 8001）， 因此你可以同时运行两者。

选项 B — 拉取预构建镜像（无需克隆）

# Create a minimal .env in the current directory
echo 'LLM_API_KEY="YOUR_OPENAI_API_KEY"' > .env

# API server
docker run --env-file ./.env -p 8000:8000 --rm -it cognee/cognee:main

# MCP server (HTTP transport)
docker pull cognee/cognee-mcp:main
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

有关 SSE/stdio 传输、可选扩展项以及 MCP 客户端配置，请参阅 MCP server README。

与 AI Agent 配合使用

Claude Code

安装 Cognee memory plugin，让 Claude Code 在会话之间保持持久记忆。该插件会将提示词、工具调用轨迹和助手回复写入会话记忆，在每次提示时注入相关上下文，并在会话结束时将会话记忆同步到永久知识图谱。

安装：从 Claude Code 市场安装。推荐方式是在启动 Claude Code 之前 在 shell 中完成安装，这样首次 claude 启动就是一个干净会话，可自动引导记忆：

# Add the marketplace and install the plugin (one-time, user-scoped)
claude plugin marketplace add topoteretes/cognee-integrations
claude plugin install cognee-memory@cognee

# Set env vars for your mode (see below), then launch
export LLM_API_KEY="sk-..."   # local mode; or COGNEE_BASE_URL + COGNEE_API_KEY for cloud
claude

本地模式（默认）— 插件会在 http://localhost:8011 引导本地 Cognee API。只需 LLM_API_KEY；若未提供 Cognee API key，会自动生成：

export LLM_API_KEY="sk-..."

Cognee Cloud 或远程服务器 — 同时设置：

export COGNEE_BASE_URL="https://your-instance.cognee.ai"
export COGNEE_API_KEY="ck_..."

启动时你应看到 “Cognee Memory Connected” 系统消息。

该插件接入 Claude Code 的生命周期 — SessionStart 选择模式并设置身份，UserPromptSubmit 注入数据集作用域上下文，PostToolUse 捕获工具调用轨迹，Stop 写入助手回答，PreCompact 在上下文重置时保留记忆，SessionEnd 触发最终同步到永久图谱。

有关会话、数据集和完整配置，请参阅 plugin README。

连接到 Cognee Cloud

将任意 Python agent 指向托管的 Cognee 实例 — 所有 SDK 调用都会路由到云端：

import cognee

await cognee.serve(url="https://your-instance.cognee.ai", api_key="ck_...")

await cognee.remember("important context")
results = await cognee.recall("what happened?")

await cognee.disconnect()

示例

在 examples/ 文件夹中浏览更多示例 — 演示、指南、自定义流水线以及数据库配置。

用例 1 — 客户支持 Agent

Goal: Resolve customer issues using their personal data across finance, support, and product history.

User: "My invoice looks wrong and the issue is still not resolved."

Cognee tracks: past interactions, failed actions, resolved cases, product history

# Agent response:
Agent: "I found 2 similar billing cases resolved last month.
        The issue was caused by a sync delay between payment
        and invoice systems — a fix was applied on your account."

# What happens under the hood:
- Unifies data sources from various company channels
- Reconstructs the interaction timeline and tracks outcomes
- Retrieves similar resolved cases
- Maps to the best resolution strategy
- Updates memory after execution so the agent never repeats the same mistake

用例 2 — 专家知识蒸馏（SQL Copilot）

Goal: Help junior analysts solve tasks by reusing expert-level queries, patterns, and reasoning.

User: "How do I calculate customer retention for this dataset?"

Cognee tracks: expert SQL queries, workflow patterns, schema structures, successful implementations

# Agent response:
Agent: "Here's how senior analysts solved a similar retention query.
        Cognee matched your schema to a known structure and adapted
        the expert's logic to fit your dataset."

# What happens under the hood:
- Extracts and stores patterns from expert SQL queries and workflows
- Maps the current schema to previously seen structures
- Retrieves similar tasks and their successful implementations
- Adapts expert reasoning to the current context
- Updates memory with new successful patterns so junior analysts perform at near-expert level

在 Postgres 上运行完整记忆层

传统图记忆通常意味着要运维一整套技术栈 — 用图数据库维护关系、用向量数据库存储嵌入、用 Redis 管理会话、用关系数据库存放元数据 — 在 agent 记住任何东西之前，这些都要先部署、加固并付费。在 cognee 1.0 中，你可以用单个 Postgres 实例运行整个记忆层。

记忆层	传统技术栈	cognee on Postgres
关系	Neo4j 或其他图数据库	cognee 的 Postgres 图后端
嵌入	专用向量数据库	pgvector
会话	Redis	SQL session-cache 后端
元数据	关系数据库	同一 Postgres

图谱依然存在 — 它只是与文本、元数据和嵌入一起存放在同一 Postgres 支撑的记忆层中，因此检索可以在相似性与结构之间切换，而无需跨越服务边界。在我们的 CI 基准测试中，Postgres 搜索比独立的图加向量方案快约 10%。

Postgres 是我们对大多数部署的默认推荐，但当工作负载需要时，你仍可替换为专用后端（Neo4j 和 Neptune 用于图，Redis 用于会话，pgvector 和 LanceDB 用于向量，另可通过社区适配器使用 Qdrant、ChromaDB、Weaviate 和 Milvus）。本地开发保持完全嵌入式 — SQLite、LanceDB 和 Kuzudb — 无需额外启动服务。

pip install "cognee[postgres]"

DB_PROVIDER=postgres
VECTOR_DB_PROVIDER=pgvector
GRAPH_DATABASE_PROVIDER=postgres
CACHE_BACKEND=postgres

DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=cognee
DB_PASSWORD=cognee
DB_NAME=cognee_db

部署 Cognee

使用 Cognee Cloud 获得全托管体验，或使用下方一键部署配置之一自行托管。

平台	最适合	命令
Cognee Cloud	托管服务，无需维护基础设施	Sign up 或 await cognee.serve()
Modal	Serverless、自动扩缩容、GPU 工作负载	bash distributed/deploy/modal-deploy.sh
Railway	最简单的 PaaS，原生 Postgres	railway init && railway up
Fly.io	边缘部署、持久卷	bash distributed/deploy/fly-deploy.sh
Render	带托管 Postgres 的简单 PaaS	Deploy to Render button
Daytona	云端沙箱（SDK 或 CLI）	参见 distributed/deploy/daytona_sandbox.py

有关部署脚本、worker 配置和更多细节，请参阅 distributed/ 文件夹。

在其他语言中使用 Cognee

不想用 Python？Cognee 也提供 Rust 和 TypeScript 的官方客户端。

Rust 入门

使用 cognee-rs crate，在 Rust 中执行 add、cognify 和 search 操作。

cargo add cognee

完整设置与示例请参阅 cognee-rs 仓库。

使用 TypeScript 入门

使用 @cognee/cognee-ts package，在 Node.js 或浏览器中执行 add、cognify 和 search 操作。

npm install @cognee/cognee-ts

完整设置与示例请参阅 @cognee/cognee-ts 包。

基准测试

我们在 BEAM, 这一长上下文基准测试中对 cognee 进行了评测；该测试检验系统能否在对话不断变化时跟踪长对话——这比典型的「大海捞针」（needle-in-a-haystack）基准测试更能衡量智能体记忆能力。我们仅使用 cognee 的默认设置和标准开源功能（无自定义模型、无 BEAM 专用流水线），在 100K token 设置下超越了此前的最先进水平（SOTA），在 10M token 设置下与其持平。

基准测试	设置	cognee	此前 SOTA	Obsidian / RAG 基线
BEAM	100K tokens	0.79（采用 per-question routing 时 >0.8）	0.735	~0.33
BEAM	10M tokens	0.67	0.641	~0.33

这些数字更多是方向性信号，而非定论性指标——完整方法论、注意事项及结果含义请参阅专题说明。

最新动态

社区与支持

贡献

我们欢迎社区贡献！您的参与能让 Cognee 变得更好。请参阅 CONTRIBUTING.md 开始贡献。

行为准则

我们致力于营造包容、尊重的社区环境。行为准则请参阅 Code of Conduct。

研究与引用

我们最近发表了一篇关于优化知识图谱以提升 LLM 推理能力的研究论文：

@misc{markovic2025optimizinginterfaceknowledgegraphs,
      title={Optimizing the Interface Between Knowledge Graphs and LLMs for Complex Reasoning},
      author={Vasilije Markovic and Lazar Obradovic and Laszlo Hajdu and Jovan Pavlovic},
      year={2025},
      eprint={2505.24478},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2505.24478},
}