topoteretes--cognee/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/topoteretes/cognee) · [上游 README](https://github.com/topoteretes/cognee/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<div align="center">
  <a href="https://github.com/topoteretes/cognee">
    <img src="https://raw.githubusercontent.com/topoteretes/cognee/refs/heads/dev/assets/cognee-logo-transparent.png" alt="Cognee Logo" height="60">
  </a>

  <br />

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

  <p align="center">
  <a href="https://www.youtube.com/watch?v=8hmqS2Y5RVQ&t=13s">Demo</a>
  .
  <a href="https://docs.cognee.ai/">Docs</a>
  .
  <a href="https://cognee.ai">了解更多</a>
  ·
  <a href="https://discord.gg/NQPKmU5CCg">加入 Discord</a>
  ·
  <a href="https://www.reddit.com/r/AIMemory/">加入 r/AIMemory</a>
  .
  <a href="https://github.com/topoteretes/cognee-community">社区插件与扩展</a>
  </p>


  [![GitHub forks](https://img.shields.io/github/forks/topoteretes/cognee.svg?style=social&label=Fork&maxAge=2592000)](https://GitHub.com/topoteretes/cognee/network/)
  [![GitHub stars](https://img.shields.io/github/stars/topoteretes/cognee.svg?style=social&label=Star&maxAge=2592000)](https://GitHub.com/topoteretes/cognee/stargazers/)
  [![GitHub commits](https://badgen.net/github/commits/topoteretes/cognee)](https://GitHub.com/topoteretes/cognee/commit/)
  [![GitHub tag](https://badgen.net/github/tag/topoteretes/cognee)](https://github.com/topoteretes/cognee/tags/)
  [![Downloads](https://static.pepy.tech/badge/cognee)](https://pepy.tech/project/cognee)
  [![License](https://img.shields.io/github/license/topoteretes/cognee?colorA=00C586&colorB=000000)](https://github.com/topoteretes/cognee/blob/main/LICENSE)
  [![Contributors](https://img.shields.io/github/contributors/topoteretes/cognee?colorA=00C586&colorB=000000)](https://github.com/topoteretes/cognee/graphs/contributors)
  <a href="https://github.com/sponsors/topoteretes"><img src="https://img.shields.io/badge/Sponsor-❤️-ff69b4.svg" alt="Sponsor"></a>

<p>
  <a href="https://trendshift.io/repositories/13955" target="_blank" style="display:inline-block;">
    <img src="https://trendshift.io/api/badge/repositories/13955" alt="topoteretes%2Fcognee | Trendshift" width="250" height="55" />
  </a>
</p>

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

  <p align="center">
  🌐 本 README 还提供以下语言版本：
  :
  <!-- Keep these links. Translations will automatically update with the README. -->
  <a href="https://www.readme-i18n.com/topoteretes/cognee?lang=de">Deutsch</a> |
  <a href="https://www.readme-i18n.com/topoteretes/cognee?lang=es">Español</a> |
  <a href="https://www.readme-i18n.com/topoteretes/cognee?lang=fr">Français</a> |
  <a href="https://www.readme-i18n.com/topoteretes/cognee?lang=ja">日本語</a> |
  <a href="README_ko.md">한국어</a> |
  <a href="https://www.readme-i18n.com/topoteretes/cognee?lang=pt">Português</a> |
  <a href="https://www.readme-i18n.com/topoteretes/cognee?lang=ru">Русский</a> |
  <a href="https://www.readme-i18n.com/topoteretes/cognee?lang=zh">中文</a>
  </p>

<p align="center">
  <img src="assets/cognee-demo.gif" alt="Cognee Demo" width="80%" />
</p>
</div>

📄 阅读研究论文：[Optimizing the Interface Between Knowledge Graphs and LLMs for Complex Reasoning](https://arxiv.org/abs/2505.24478) — Markovic et al., 2025


## 关于 Cognee

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

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

:books: _查看我们的详细[文档](https://docs.cognee.ai/getting-started/installation#environment-configuration)，了解安装与配置。_

:crab: _可作为 OpenClaw 插件使用 — [cognee-openclaw](https://www.npmjs.com/package/@cognee/cognee-openclaw)_

✴️ _可作为 Claude Code 插件使用 — [claude-code-plugin](https://github.com/topoteretes/cognee-integrations/tree/main/integrations/claude-code)_

🦀 _提供 Rust 客户端 — [cognee-rs](https://github.com/topoteretes/cognee-rs)_

🟦 _提供 TypeScript 客户端 — [@cognee/cognee-ts](https://www.npmjs.com/package/@cognee/cognee-ts)_



### 为何使用 Cognee：

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

### 工作原理

<p align="center">
  <img src="assets/remember.svg" alt="Cognee Products" width="80%" />
</p>

<p align="center">
  <img src="assets/recall.svg" alt="Cognee Recall" width="80%" />
</p>

## 基础用法与功能指南

想了解更多，可[查看这份简短、端到端的 Colab 实操教程](https://colab.research.google.com/drive/1HRrzIvzcbwrESVfX76wJLKmtIg00SUga?usp=sharing)，了解 Cognee 的核心功能。

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1HRrzIvzcbwrESVfX76wJLKmtIg00SUga?usp=sharing)

## 快速开始

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

### 前置条件

- Python 3.10 to 3.14

### 步骤 1：安装 Cognee

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

```bash
uv pip install cognee
```

### 步骤 2：配置 LLM
```python
import os
os.environ["LLM_API_KEY"] = "YOUR OPENAI_API_KEY"
```
或者，使用我们的[模板](https://github.com/topoteretes/cognee/blob/main/.env.template). 创建 `.env` 文件

要接入其他 LLM 提供商，请参阅我们的 [LLM Provider Documentation](https://docs.cognee.ai/setup-configuration/llm-providers).

### 步骤 3：运行流水线

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

```python
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

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

cognee-cli recall "What does Cognee do?"

cognee-cli forget --all
```

要打开本地 UI，请运行：
```bash
cognee-cli -ui
```

> **Note:** 由 `cognee-cli -ui` 启动的 MCP 服务器在 Docker 容器内运行。
> 需要 Docker Desktop、Colima 或任何兼容 OCI 且 `docker` CLI 可正常使用的运行时。详见 [Docker & Colima Setup](docs/docker-colima-setup.md)。

## 使用 Docker 运行

更喜欢容器化部署？Cognee 会在每次推送到 `main` 时，将预构建镜像发布到 Docker Hub：
[`cognee/cognee`](https://hub.docker.com/r/cognee/cognee)（API 服务器）以及
[`cognee/cognee-mcp`](https://hub.docker.com/r/cognee/cognee-mcp)（MCP 服务器）。

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

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

```bash
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 — 拉取预构建镜像（无需克隆）

```bash
# 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](cognee-mcp/README.md)。

## 与 AI Agent 配合使用

### Claude Code

安装 [Cognee memory plugin](https://github.com/topoteretes/cognee-integrations/tree/main/integrations/claude-code)，让 Claude Code 在会话之间保持持久记忆。该插件会将提示词、工具调用轨迹和助手回复写入会话记忆，在每次提示时注入相关上下文，并在会话结束时将会话记忆同步到永久知识图谱。

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

```bash
# 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，会自动生成：

```bash
export LLM_API_KEY="sk-..."
```

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

```bash
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](https://github.com/topoteretes/cognee-integrations/tree/main/integrations/claude-code)。

### 连接到 Cognee Cloud

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

```python
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/`](examples/) 文件夹中浏览更多示例 — 演示、指南、自定义流水线以及数据库配置。

**用例 1 — 客户支持 Agent**

```python
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）**

```python
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 — 无需额外启动服务。

```bash
pip install "cognee[postgres]"
```

```bash
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](https://www.cognee.ai) 获得全托管体验，或使用下方一键部署配置之一自行托管。

| 平台 | 最适合 | 命令 |
|----------|----------|---------|
| **Cognee Cloud** | 托管服务，无需维护基础设施 | [Sign up](https://www.cognee.ai) 或 `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/`](distributed/) 文件夹。

## 在其他语言中使用 Cognee

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

### Rust 入门

使用 [cognee-rs](https://github.com/topoteretes/cognee-rs) crate，在 Rust 中执行 add、cognify 和 search 操作。

```bash
cargo add cognee
```

完整设置与示例请参阅 [cognee-rs 仓库](https://github.com/topoteretes/cognee-rs)。

### 使用 TypeScript 入门

使用 [@cognee/cognee-ts](https://www.npmjs.com/package/@cognee/cognee-ts) package，在 Node.js 或浏览器中执行 add、cognify 和 search 操作。

```bash
npm install @cognee/cognee-ts
```

完整设置与示例请参阅 [@cognee/cognee-ts 包](https://www.npmjs.com/package/@cognee/cognee-ts)。

## 基准测试

我们在 [BEAM](https://github.com/topoteretes/cognee), 这一长上下文基准测试中对 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 |

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

## 最新动态

[![Watch Demo](https://img.youtube.com/vi/8hmqS2Y5RVQ/maxresdefault.jpg)](https://www.youtube.com/watch?v=8hmqS2Y5RVQ&t=13s)


## 社区与支持

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

### 行为准则

我们致力于营造包容、尊重的社区环境。行为准则请参阅 [Code of Conduct](https://github.com/topoteretes/cognee/blob/main/CODE_OF_CONDUCT.md)。

## 研究与引用

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

```bibtex
@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},
}
```