topoteretes/cognee · 上手攻略

  • 仓库：topoteretes/cognee
  • 链接：https://github.com/topoteretes/cognee
  • 分类：trending
  • 作者：Tom
  • 更新：2026-07-09

这是什么

Cognee（发音接近"cog-knee"）是一个开源的 AI 记忆平台，专门为 AI Agent 设计持久化长期记忆能力。它的核心理念是：让 AI 不再是"每次对话都是一张白纸"，而是可以跨会话记住关键信息、实体关系和上下文。

Cognee 的记忆架构结合了向量检索（语义搜索）+ 知识图谱（关系推理）+ 认知科学启发的本体生成，文档不仅能被"按意思找到"，还能被"按关系连接"。底层默认用单节点 PostgreSQL（pgvector）跑通全部记忆层，无需运维一整套 Neo4j + Redis + 向量数据库的组合。

解决什么问题

当前主流 Agent 架构有一个根本缺陷：每次新的对话上下文，Agent 从零理解，无法利用历史交互中积累的知识。

现有解决方案的痛点： - 纯 RAG：只能做相似文档检索，无法表达"用户之前拒绝了哪个方案，为什么"这类关系信息。 - 手工知识图谱：需要人工定义 Schema，维护成本极高，实时性差。 - 长上下文窗口：贵（Token 费用）、慢（推理延迟）、有上限（模型 context window）。

Cognee 的思路是：让 LLM 自动从非结构化数据中抽取实体和关系，构建成可推理的知识图谱，同时保留向量检索的速度优势。

快速安装

前置要求

  • Python 3.10 ~ 3.14
  • Docker（运行本地 UI 或 MCP 服务器时需要）
  • LLM API Key（OpenAI 或兼容 OpenAI API 的 provider）

pip 安装（推荐）

uv pip install cognee
# 或
pip install cognee

环境变量配置

# 方法一：环境变量
export LLM_API_KEY="sk-your-openai-key"

# 方法二：.env 文件（项目根目录下）
cp .env.template .env
# 编辑 .env，填入 LLM_API_KEY

⚠️ Cognee 默认使用 OpenAI API，LLM_API_KEY 支持 OpenAI 格式密钥。如需其他 LLM 提供商，参考 LLM Provider 文档。

核心用法

四步记忆 API

Cognee 的核心 API 只有四个操作：remember（记忆）、recall（回忆）、forget（遗忘）、improve（改进）。

import cognee
import asyncio

async def main():
    # 永久存入知识图谱（内部自动执行 add + cognify + improve）
    await cognee.remember("Cognee turns documents into AI memory.")

    # 存入会话缓存（快速访问，后台同步到图谱）
    await cognee.remember(
        "User prefers detailed explanations.",
        session_id="chat_1"
    )

    # 自动路由检索（根据查询选择最优搜索策略）
    results = await cognee.recall("What does Cognee do?")
    for result in results:
        print(result)

    # 会话优先查询，找不到再查图谱
    results = await cognee.recall(
        "What does the user prefer?",
        session_id="chat_1"
    )

    # 删除数据集
    await cognee.forget(dataset="main_dataset")

asyncio.run(main())

CLI 工具

不想写代码？Cognee 提供开箱即用的命令行界面：

# 记忆一条信息
cognee-cli remember "Cognee turns documents into AI memory."

# 检索
cognee-cli recall "What does Cognee do?"

# 删除所有记忆
cognee-cli forget --all

# 打开本地 UI（http://localhost:3000）
cognee-cli -ui

⚠️ 注意：cognee-cli -ui 启动的 MCP 服务器运行在 Docker 容器内。需要 Docker Desktop、Colima 或任何 OCI 兼容的容器运行时。

Docker 部署（完整服务）

git clone https://github.com/topoteretes/cognee.git
cd cognee

# 创建 .env
cp .env.template .env
# 编辑 .env 填入 LLM_API_KEY

# 启动全部服务
docker compose up

# 按需启动特定 profile
docker compose --profile ui up          # + 前端 UI
docker compose --profile mcp up        # + MCP 服务器
docker compose --profile postgres up   # + PostgreSQL/PGVector
docker compose --profile neo4j up       # + Neo4j（图谱后端）

MCP 服务器（AI Agent 集成）

Cognee 提供 MCP（Model Context Protocol）服务器，可以接入任何兼容 MCP 的 AI 客户端：

# 方式一：Docker 运行 MCP 服务器（HTTP 传输）
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 传输
# 参考：https://github.com/topoteretes/cognee/blob/main/cognee-mcp/README.md

Claude Code 插件

Cognee 提供官方 Claude Code 插件，让 Claude Code 有持久化记忆：

# 添加插件市场并安装（一次性操作）
claude plugin marketplace add topoteretes/cognee-integrations
claude plugin install cognee-memory@cognee

# 设置环境变量后启动
export LLM_API_KEY="sk-..."          # 本地模式
# 或
export COGNEE_BASE_URL="https://your-instance.cognee.ai"
export COGNEE_API_KEY="ck_..."       # 云端/远程模式

claude

插件在 Claude Code 生命周期中自动工作： - SessionStart：初始化身份，设置模式 - UserPromptSubmit：注入数据集范围上下文 - PostToolUse：捕获工具调用记录 - Stop：保存助手回答 - PreCompact：上下文压缩时保留记忆 - SessionEnd：最终同步到永久知识图谱

核心概念：Postgres 一站式记忆层

Cognee 1.0 的重大创新：一套 Postgres 同时承担图谱 + 向量 + 会话缓存 + 元数据，无需运维多套系统。

能力 传统架构 Cognee on Postgres
关系/图谱 Neo4j / Neptune ✅ Postgres 图谱后端
向量检索 pgvector / Qdrant / Milvus ✅ pgvector
会话缓存 Redis ✅ Postgres 缓存后端
元数据存储 独立关系库 ✅ 同一 Postgres

Cognee 仍然支持热插拔专用后端： - 图谱：Neo4j、Amazon Neptune - 向量：pgvector、LanceDB、Qdrant、ChromaDB、Weaviate、Milvus - 缓存：Redis - 本地开发：SQLite、LanceDB、KuzuDB（零服务依赖）

配置 Postgres 后端

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

典型适用场景

  1. 客服 Agent 记忆：记住用户历史问题、已解决/未解决的问题风格，新对话时主动参考。
  2. 领域知识蒸馏：将专家的 SQL 查询、工作流模式抽象后，让初级用户复用专家级推理路径。
  3. 跨 Agent 知识共享：多个 Agent 共享同一知识图谱，避免重复学习同一份文档。
  4. 复杂对话追踪（BEAM 基准）：超过 10 万 Token 的长对话中保持实体关系一致性。

性能基准

Cognee 在 BEAM（Long-Context Memory Benchmark）上测试结果：

设置 Cognee Previous SOTA RAG 基线
100K tokens 0.79 0.735 ~0.33
10M tokens 0.67 0.641 ~0.33

⚠️ 以上数据来自 Cognee 官方，在 100K tokens 档领先 SOTA，10M tokens 档追平。数字仅作方向参考，不代表所有场景表现，实际效果请自行验证。

坑与注意

  1. Python 版本限制：仅支持 Python 3.10~3.14，不支持 3.9 及以下版本。

  2. LLM API 费用：所有记忆的认知化（cognify）过程都调用 LLM，每次 remember 都有 Token 消耗，生产环境注意监控用量。

  3. Docker UI 依赖：CLI 的 -ui 功能依赖 Docker，轻量环境（如无 Docker 的服务器）无法使用本地 UI，但仍可通过 API 调用核心功能。

  4. pgvector 需要 PG 扩展：如果用 Postgres 后端，确认数据库启用了 pgvector 扩展。

  5. 冷启动延迟：首次 remember 一个新数据集时，Cognee 需要完成分块 → 向量化 → 图谱抽取，首次调用可能较慢。

  6. 中文支持：README 文档和 API 示例以英文为主，中文资料较少，实际使用时注意 Prompt 工程的语言一致性。

与同类对比

维度 Cognee Mem0 LangChain Memory
知识图谱 ✅ 原生 ❌ 纯向量 部分支持
Postgres 单节点 ✅ ❌ ❌
多 Agent 共享 ✅ ✅ ❌
会话隔离 ✅ ✅ 需手动
MCP 支持 ✅ ❌ ❌
Claude Code 插件 ✅ ❌ ❌

Cognee 的核心优势：知识图谱 + 向量双轨检索、原生 Postgres 零运维、多语言 SDK（Python/Rust/TypeScript）。不适合：需要完全云托管（而非自托管）的场景（Mem0 Cloud 更省心）。

一句话推荐结论

如果你的 AI Agent 需要"活"的记忆——不只是文档检索，而是能记住关系、追踪变化、跨会话积累——Cognee 是目前开源方案中架构最完整、上手最平滑的选择。

来源

  • GitHub README：https://github.com/topoteretes/cognee
  • 官方文档：https://docs.cognee.ai
  • Colab 快速体验：https://colab.research.google.com/drive/12Vi9zID-M3fpKpKiaqDBvkk98ElkRPWy
  • 研究论文：arXiv 2505.24478