cognee

概览

Cognee v0.5.5 —— 开源 Python AI 记忆引擎，可将原始数据转换为可搜索的知识图谱，并结合向量搜索与图数据库。

• 源码： topoteretes/cognee @ main
• 语言： Python（全程使用 async/await）
• Forge 层级： Deep（AST + gh + QMD）
• 公共 API 导出项： 22 | 提取总数： 837（302 个函数，535 个类）
• 置信度： 837 个 T1（经 AST 验证），14 个 T2（经 QMD 丰富），T3（文档补充）

快速开始

import cognee
import asyncio

async def main():
    # Reset state
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

    # 1. Ingest data
    await cognee.add("Cognee turns documents into AI memory.")  # [AST:cognee/api/v1/add/add.py:L22]

    # 2. Build knowledge graph
    await cognee.cognify()  # [AST:cognee/api/v1/cognify/cognify.py:L47]

    # 3. Search
    results = await cognee.search(  # [AST:cognee/api/v1/search/search.py:L26]
        query_text="What does Cognee do?"
    )
    for r in results:
        print(r)

asyncio.run(main())

所有核心函数都是异步的——必须在异步上下文中使用 await。[EXT:docs.cognee.ai/getting-started/quickstart]

环境设置要求

Python： >=3.10, <3.14。推荐的安装工具：uv。

uv pip install -e "."                    # minimal (SQLite + LanceDB + Kuzu)
uv pip install -e ".[postgres,neo4j]"    # with PostgreSQL + Neo4j

主要安装 extras： postgres / postgres-binary、neo4j、neptune、chromadb、qdrant、redis、ollama、anthropic、gemini、mistral、groq、huggingface、llama-cpp、aws（S3）、langchain、llama-index、graphiti、baml、dlt、docling、codegraph、scraping、docs、monitoring（Sentry+Langfuse）、distributed（Modal）、dev、debug。

最小 .env：

LLM_API_KEY="your_openai_api_key"
LLM_MODEL="openai/gpt-4o-mini"

默认值（无需额外设置）：SQLite（关系型）、LanceDB（向量）、Kuzu（图）。默认情况下，所有数据都存储在 .venv 中——可通过 DATA_ROOT_DIRECTORY 和 SYSTEM_ROOT_DIRECTORY 覆盖。

重要： 如果只配置 LLM 或只配置 embeddings，另一项将默认使用 OpenAI。请务必同时配置两者，或确保提供有效的 OpenAI API 密钥。

常见工作流

添加并处理数据： await cognee.add(data) → await cognee.cognify() → await cognee.search(query_text)

多格式摄取： await cognee.add(["/path/to/file.pdf", "raw text", open("doc.txt","rb")], dataset_name="my_data")

基于本体的 cognify： config = {"ontology_config": {"ontology_resolver": RDFLibOntologyResolver(ontology_file=path)}} → await cognee.cognify(config=config) [EXT:docs.cognee.ai/guides/ontology-support]

支持会话的搜索： await cognee.search(query_text="Q1", session_id="conv_1") → await cognee.search(query_text="Follow-up", session_id="conv_1") [EXT:docs.cognee.ai/guides/sessions]

自定义数据模型： class MyEntity(DataPoint): name: str; metadata = {"index_fields": ["name"]} → await add_data_points([entity]) [EXT:docs.cognee.ai/guides/custom-data-models]

API 关键摘要

函数	用途	关键参数
add()	摄取文本、文件和二进制数据	data、dataset_name、user
cognify()	根据摄取的数据构建知识图谱	datasets、graph_model、chunker、temporal_cognify
search()	查询知识图谱	query_text、query_type、top_k、session_id
memify()	使用自定义任务丰富现有图谱	extraction_tasks、enrichment_tasks、data
config.*	运行时配置（LLM、数据库、向量）	静态方法
datasets.*	列出、检查和删除数据集	静态方法
prune.*	清理数据和系统资源	prune_data()、prune_system()
update()	更新现有数据项	data_id、data、dataset_id
session.*	会话历史和反馈	get_session()、add_feedback()
run_custom_pipeline()	执行自定义任务流水线	tasks、data、dataset
SearchType	包含 14 种搜索模式的枚举	GRAPH_COMPLETION（默认）
visualize_graph()	将知识图谱渲染为 HTML	destination_file_path
enable_tracing()	启用 OpenTelemetry 跟踪	console_output
run_migrations()	运行 Alembic 数据库迁移	—
start_ui()	启动本地 Cognee UI（前端 + 后端 + MCP 服务）	pid_callback、port、start_backend、start_mcp
cognee_network_visualization()	将知识图谱渲染为交互式 HTML	graph_data、destination_file_path
pipelines	模块重新导出：Task、run_tasks、run_tasks_parallel、run_pipeline	—

LLM 提供商配置

通过 .env 配置 — 各提供商示例：

# Azure OpenAI
LLM_PROVIDER="azure"
LLM_MODEL="azure/gpt-4o-mini"
LLM_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com/openai/deployments/gpt-4o-mini"
LLM_API_KEY="your_key"
LLM_API_VERSION="2024-12-01-preview"

# Anthropic (requires: pip install cognee[anthropic])
LLM_PROVIDER="anthropic"
LLM_MODEL="claude-3-5-sonnet-20241022"
LLM_API_KEY="your_key"

# Ollama (requires: pip install cognee[ollama])
LLM_PROVIDER="ollama"
LLM_MODEL="llama3.1:8b"
LLM_ENDPOINT="http://localhost:11434/v1"
LLM_API_KEY="ollama"
EMBEDDING_PROVIDER="ollama"
EMBEDDING_MODEL="nomic-embed-text:latest"
EMBEDDING_ENDPOINT="http://localhost:11434/api/embed"
HUGGINGFACE_TOKENIZER="nomic-ai/nomic-embed-text-v1.5"

# AWS Bedrock (requires: pip install cognee[aws])
LLM_PROVIDER="bedrock"
LLM_MODEL="anthropic.claude-3-sonnet-20240229-v1:0"
AWS_REGION="us-east-1"

# Custom / OpenRouter / vLLM
LLM_PROVIDER="custom"
LLM_MODEL="openrouter/google/gemini-2.0-flash-lite-preview-02-05:free"
LLM_ENDPOINT="https://openrouter.ai/api/v1"

速率限制： LLM_RATE_LIMIT_ENABLED=true、LLM_RATE_LIMIT_REQUESTS=60、LLM_RATE_LIMIT_INTERVAL=60

结构化输出： STRUCTURED_OUTPUT_FRAMEWORK="instructor"（默认）或 "baml"（需要 cognee[baml]）。覆盖 instructor 模式：LLM_INSTRUCTOR_MODE="json_schema_mode"。

切换数据库

# PostgreSQL (requires: pip install cognee[postgres])
DB_PROVIDER=postgres
DB_HOST=localhost  DB_PORT=5432  DB_USERNAME=cognee  DB_PASSWORD=cognee  DB_NAME=cognee_db

# PGVector (requires: pip install cognee[postgres])
VECTOR_DB_PROVIDER=pgvector
VECTOR_DB_URL=postgresql://cognee:cognee@localhost:5432/cognee_db

# Neo4j (requires: pip install cognee[neo4j])
GRAPH_DATABASE_PROVIDER=neo4j
GRAPH_DATABASE_URL=bolt://localhost:7687
GRAPH_DATABASE_USERNAME=neo4j  GRAPH_DATABASE_PASSWORD=yourpassword

# S3 storage (requires: pip install cognee[aws])
STORAGE_BACKEND="s3"
STORAGE_BUCKET_NAME="your-bucket"
DATA_ROOT_DIRECTORY="s3://your-bucket/cognee/data"

安全环境变量

ACCEPT_LOCAL_FILE_PATH=True     # Allow local file paths in add()
ALLOW_HTTP_REQUESTS=True        # Allow HTTP fetches
ALLOW_CYPHER_QUERY=True         # Allow raw Cypher in SearchType.CYPHER
REQUIRE_AUTHENTICATION=False    # Enable API auth
ENABLE_BACKEND_ACCESS_CONTROL=True  # Multi-tenant dataset isolation

扩展模式

自定义流水线任务：

from cognee.modules.pipelines.tasks.Task import Task

async def my_task(data):
    return process(data)

task = Task(my_task)

直接访问数据库：

from cognee.infrastructure.databases.graph import get_graph_engine
from cognee.infrastructure.databases.vector import get_vector_engine

graph_engine = await get_graph_engine()
vector_engine = await get_vector_engine()

LLM 网关（结构化输出）：

from cognee.infrastructure.llm.get_llm_client import get_llm_client

llm_client = get_llm_client()
response = await llm_client.acreate_structured_output(
    text_input="prompt", system_prompt="instructions", response_model=YourPydanticModel
)

MCP 服务传输模式

python src/server.py                    # stdio (default)
python src/server.py --transport sse    # SSE
python src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp
# API mode (connect to running Cognee API):
python src/server.py --transport sse --api-url http://localhost:8000 --api-token TOKEN

Docker：docker run -e TRANSPORT_MODE=sse --env-file .env -p 8000:8000 cognee/cognee-mcp:main

常见故障排查

• Ollama + OpenAI 嵌入导致 NoDataError — 将 LLM 和嵌入配置为使用同一提供商，或设置 HUGGINGFACE_TOKENIZER
• LM Studio 结构化输出 — 设置 LLM_INSTRUCTOR_MODE="json_schema_mode"
• 默认提供商回退 — 仅配置 LLM 或仅配置嵌入时，另一项默认使用 OpenAI
• 搜索时权限被拒绝 — 为防止信息泄露，会返回空列表（而非错误）；请检查数据集权限
• Docker 数据库连接 — 对于本地数据库，请使用 DB_HOST=host.docker.internal
• 调试日志记录 — LITELLM_LOG="DEBUG"、ENV="development"、TELEMETRY_DISABLED=1

迁移与弃用警告

• delete() 自 v0.3.9 起已弃用——请改用 datasets.delete_data() [SRC:cognee/api/v1/delete/__init__.py:L13]
• memify() 默认流水线已更改——编码规则已替换为三元组嵌入（2026 年 3 月）[QMD:cognee-temporal:prs.md]
• update() 错误——PATCH 会更新时间戳，但 GET raw 可能返回旧数据 [QMD:cognee-temporal:issues.md]
• visualize_graph() 前端——未解决的错误 #2442：UI 模式下缺少组件 [QMD:cognee-temporal:issues.md]
• start_ui() v0.5.5 错误——通过 pip 安装的前端因缺少 npm 依赖项（react-markdown、ngraph.graph）而出现 500 错误 [QMD:cognee-temporal:issues.md]

迁移详情请参阅完整 API 参考。

关键类型

SearchType（14 种模式）[AST:cognee/modules/search/types/SearchType.py:L4]： GRAPH_COMPLETION（默认）、RAG_COMPLETION、CHUNKS、SUMMARIES、TRIPLET_COMPLETION、GRAPH_SUMMARY_COMPLETION、CYPHER、NATURAL_LANGUAGE、GRAPH_COMPLETION_COT、GRAPH_COMPLETION_CONTEXT_EXTENSION、FEELING_LUCKY、TEMPORAL、CODING_RULES、CHUNKS_LEXICAL

Task — 封装任意可调用对象（异步/同步/生成器），用于流水线执行 [AST:cognee/modules/pipelines/tasks/task.py]

DataPoint — 自定义图节点的基类；继承此类并添加类型化字段 [EXT:docs.cognee.ai/guides/custom-data-models]

ChunkStrategy — PARAGRAPH、SENTENCE、LANGCHAIN_CHARACTER [AST:cognee/shared/data_models.py:L83]

架构概览

• **存储：**关系型（SQLite/Postgres）+ 向量（LanceDB/PGVector/Qdrant/Redis/ChromaDB/FalkorDB）+ 图（Kuzu/Neo4j/Neptune/Memgraph）
• **大模型提供方：**OpenAI、Azure OpenAI、Gemini、Anthropic、Ollama、自定义（vLLM）
• **嵌入：**OpenAI、Azure、Gemini、Mistral、Ollama、Fastembed
• **流水线：**Tasks → Pipelines → run_pipeline（使用异步生成器进行编排）
• **可观测性：**通过 enable_tracing() / disable_tracing() 使用 OpenTelemetry 追踪
• **MCP 服务：**7 个工具（cognify、search、list_data、delete、prune、cognify_status、save_interaction）[AST:cognee-mcp/src/server.py]

命令行界面

cognee --add "data"          # Ingest data
cognee --cognify             # Build knowledge graph
cognee --search "query"      # Search
cognee --debug               # Enable debug logging
cognee --ui                  # Launch local UI

[AST:cognee/cli/_cognee.py:L32]

完整 API 参考

所有 22 个导出的完整签名（包含参数、返回类型和 T2 注释）请参阅 references/full-api-reference.md。

完整类型定义

SearchType [AST:cognee/modules/search/types/SearchType.py:L4]

class SearchType(str, Enum):
    SUMMARIES = "SUMMARIES"               # Vector similarity on TextSummary nodes
    CHUNKS = "CHUNKS"                     # Vector similarity on DocumentChunk nodes
    RAG_COMPLETION = "RAG_COMPLETION"     # LLM-backed with chunk context
    TRIPLET_COMPLETION = "TRIPLET_COMPLETION"  # Graph triplet-based retrieval
    GRAPH_COMPLETION = "GRAPH_COMPLETION" # Default — LLM + graph traversal
    GRAPH_SUMMARY_COMPLETION = "GRAPH_SUMMARY_COMPLETION"
    CYPHER = "CYPHER"                     # Raw Cypher query
    NATURAL_LANGUAGE = "NATURAL_LANGUAGE" # NL → Cypher translation
    GRAPH_COMPLETION_COT = "GRAPH_COMPLETION_COT"  # Chain-of-thought graph
    GRAPH_COMPLETION_CONTEXT_EXTENSION = "GRAPH_COMPLETION_CONTEXT_EXTENSION"
    FEELING_LUCKY = "FEELING_LUCKY"       # Single best result
    TEMPORAL = "TEMPORAL"                 # Time-aware search
    CODING_RULES = "CODING_RULES"         # Code rule retrieval
    CHUNKS_LEXICAL = "CHUNKS_LEXICAL"     # BM25 keyword search on chunks

DataPoint [EXT:docs.cognee.ai/guides/custom-data-models]

所有图节点的基类，继承自 Pydantic BaseModel。设置 metadata = {"index_fields": ["field"]} 以进行向量索引。加权关系请使用 Edge(weight, relationship_type)。

值得关注的子类：DocumentChunk、TextSummary、CodeSummary、DatabaseSchema、SchemaTable、TranslatedContent、GraphitiNode、WebPage。

Task [AST:cognee/modules/pipelines/tasks/task.py]

class Task:
    def __init__(self, executable, *args, task_config=None, **kwargs)

封装任意可调用对象（异步/同步函数、生成器、异步生成器）。使用 task_config={"batch_size": N} 进行并行处理。使用 @task_summary("Processed {n} items") 装饰，以便生成流水线报告。

流水线导出项 [SRC:cognee/modules/pipelines/__init__.py:L1]

Task、run_tasks、run_tasks_parallel、run_pipeline

完整集成模式

联合导入模式

• pydantic — 用 BaseModel 定义图模型，用 BaseSettings 配置
• sqlalchemy — 关系型存储层（异步会话）
• fastapi — 用于部署的 HTTP API 服务
• uuid — 数据集和数据项标识符
• asyncio — 所有核心操作均为异步

MCP 服务集成 [AST:cognee-mcp/src/server.py]

7 个 MCP 工具：cognify(data, graph_model_file, graph_model_name, custom_prompt)、search(search_query, search_type, top_k)、save_interaction(...)、list_data(dataset_id)、delete(data_id, dataset_id, mode)、prune()、cognify_status()。

通过 FastMCP("Cognee") 运行。支持 SSE 和可流式传输的 HTTP 传输，并支持 CORS。

Provider Configuration [EXT:docs.cognee.ai/setup-configuration/overview]

通过 .env 或 cognee.config.* 方法进行配置：

• LLM： LLM_API_KEY、LLM_MODEL、LLM_PROVIDER（openai/azure/gemini/anthropic/ollama/custom）
• Embedding： EMBEDDING_PROVIDER、EMBEDDING_MODEL
• Vector： VECTOR_DB_PROVIDER（lancedb/pgvector/qdrant/redis/chromadb/falkordb）
• Graph： GRAPH_DB_PROVIDER（kuzu/neo4j/neptune/memgraph）
• 调试： LOG_LEVEL=DEBUG、TELEMETRY_DISABLED=true