cognee

概要

Cognee v0.5.5 — 生データを、ベクトル検索とグラフデータベースを組み合わせた検索可能なナレッジグラフに変換する、オープンソースの Python AI メモリエンジンです。

• ソース： topoteretes/cognee @ main
• 言語： Python（全体を通して async/await を使用）
• Forge 階層： Deep（AST + gh + QMD）
• 公開 API のエクスポート数： 22 | 抽出合計： 837（関数 302、クラス 535）
• 信頼度： T1 が 837 件（AST 検証済み）、T2 が 14 件（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())

すべてのコア関数は async です。async コンテキスト内で 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

主なインストール用追加機能： 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 または埋め込みのどちらか一方だけを設定すると、もう一方にはデフォルトで 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、DB、ベクトル）	静的メソッド
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 接続 — ローカルデータベースには 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 のバグ — npm 依存関係（react-markdown、ngraph.graph）が不足しているため、pip でインストールしたフロントエンドで 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）
• LLM プロバイダー： OpenAI、Azure OpenAI、Gemini、Anthropic、Ollama、カスタム（vLLM）
• 埋め込み： OpenAI、Azure、Gemini、Mistral、Ollama、Fastembed
• パイプライン： タスク → パイプライン → 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]

CLI

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") で実行します。CORS 対応の SSE およびストリーム可能な HTTP トランスポートをサポートします。

プロバイダーの設定 [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_PROVIDER、EMBEDDING_MODEL
• ベクトル： VECTOR_DB_PROVIDER（lancedb/pgvector/qdrant/redis/chromadb/falkordb）
• グラフ： GRAPH_DB_PROVIDER（kuzu/neo4j/neptune/memgraph）
• デバッグ： LOG_LEVEL=DEBUG、TELEMETRY_DISABLED=true