cognee

Cognee

このスキルは、Cognee 固有の Python API に関するサポートや、ユーザーの目的に適した Cognee ワークフローへの案内に使用します。

このスキルを適用するタイミング

ユーザーが Cognee を使って次のいずれかを行いたい場合は、このスキルを適用します。

• テキスト、ファイル、URL、リポジトリ、データセットを取り込む
• ナレッジグラフを構築または再構築する
• ドキュメント、チャンク、要約、トリプレット、グラフコンテキストを検索する
• SearchType を選択する
• improve で既存のグラフを拡充する
• カスタムのグラフ抽出モデルや DataPoint 型を定義する
• カスタムのタスクパイプラインを実行する
• LLM、グラフ DB、ベクトル DB、ストレージの設定を行う
• node_set / NodeSets でメモリにタグを付け、スコープを設定する
• セッションをまたいでエージェントが利用できる永続メモリを構築する
• フィードバックループや自己改善型エージェントのワークフローを作成する
• 時間的な情報の抽出、オントロジー、Cypher、自然言語によるグラフクエリを扱う
• データセット、セッション、フィードバック、削除、更新、可視化を管理する

ユーザーの意図が「情報をメモリに保存して、後からクエリする」である場合は、Cognee の メモリ API、つまり remember -> recall を優先してください（拡充には improve、 削除には forget も使用します）。

基本的なワークフロー

import cognee

# Store: ingest + build the graph (+ improve, because self_improvement=True by default)
await cognee.remember(
    "Your text, file path, URL, or list of inputs",
    dataset_name="main",
)

# Query: recall picks a search strategy automatically (rule-based, no LLM call)
results = await cognee.recall("What are the key insights?", datasets=["main"])
for r in results:
    print(r.source, r)  # each result is tagged "graph" / "session" / ...

remember() は内部で add() + cognify() を実行し、その後 improve() を実行します。recall() は search() をラップし、ルーティング、ソースとしてのセッションメモリ、source タグ付きの結果を追加します。

基本的な指針

Cognee を使った支援では、次のようにします。

1. ユーザーが高度な設定を明示的に求めていない限り、最もシンプルに動作する方法から始めます。
2. メモリ API を優先します。
   • 保存（取り込み + グラフ構築）には remember(...)
   • クエリには recall(...)
   • 既存のグラフの拡充やインデックス作成、セッションのグラフへの橋渡しには improve(...)
   • 削除には forget(...)
3. Cognee API は非同期として扱います。
4. 複数のソースがある場合は、dataset_name / datasets を使って作業を整理します。
5. 軽量なタグ付け、プロジェクトのスコープ設定、ユーザーごとのメモリバケット、サブグラフのフィルタリングには node_set を使います。
6. 特定の戦略が必要な場合に限り、recall() に query_type=SearchType.X を渡します。それ以外の場合はルーティングに任せます。
7. タスクに合う場合に限り、高度な機能を推奨します。
   • 高速な短期メモリと会話の継続性には session_id
   • スキーマに沿った抽出には graph_model=、直接挿入には DataPoint 型
   • LLM を使わないグラフ抽出には extractor="gliner_demo"
   • デフォルト以外のタスクオーケストレーションにはカスタムパイプライン
   • 検索の改善にはフィードバックループ
   • グラフの確認には可視化ツール

低レベルの操作に切り替える場合

add()、cognify()、search() は引き続き提供されており、メモリ API から呼び出されます。remember / recall では 実現できない場合に限り、次の操作を使用してください。

• cognify(datasets=["a", "b"]) または datasets=None は、複数のデータセットを一度に処理します。 remember() は常に単一のデータセットを対象とします。
• DB 内の既存データに対するグラフの再構築（forget(memory_only=True) の後や、新しい graph_model / オントロジーを使う場合）は cognify() でのみ行えます。remember() は常に最初に add() を実行します。
• search() はエージェント向けの追加パラメーター（skills、tools、max_iter、 code_query、node_type）を第一級パラメーターとして受け取り、タグ付きの辞書ではなく、生の SearchResult オブジェクトを返します。
• add() はステージング領域です。今すぐデータを取り込み、後で cognify() を実行する場合に使います。
• prune.prune_system(metadata=True) はリレーショナル DB（ユーザー、ACL、データセットレジストリ）も削除しますが、forget() はこれらに触れません。テスト環境を完全に破棄する場合に限り、prune を使ってください。

cognee.delete() は非推奨であり、代わりに forget() を使用します。2 つのクエリ関数の詳しい比較については、docs/recall-vs-search.md を参照してください。

よくあるタスク

データを保存する

remember() は、テキスト、ファイルパス、URL、ディレクトリ、Git リポジトリの URL、バイナリストリーム、 またはこれらのリストを受け付けます。

await cognee.remember("notes.md", dataset_name="research")
await cognee.remember("https://example.com", dataset_name="research")
await cognee.remember(["paper.pdf", "summary.txt"], dataset_name="research")

データを論理的なメモリバケットにまとめる場合は、node_set を使います。

await cognee.remember(
    "Customer prefers concise weekly summaries and Slack delivery.",
    dataset_name="customer_success",
    node_set=["preferences", "customer_123", "weekly_reports"],
)

便利なオプション：

await cognee.remember(
    "...",
    dataset_name="research",
    self_improvement=False,  # skip the improve() stage (faster)
    run_in_background=True,  # return immediately; poll the pipeline status
    chunk_size=1024,
    custom_prompt="Extract companies, products, and partnerships.",
    extractor="gliner_demo",  # LLM-free extraction; needs cognee[gliner]
    dry_run=True,  # estimate LLM tokens/cost without ingesting
)
await cognee.remember("./my_repo", dataset_name="code")  # code graph, no LLM
await cognee.remember("./skills", dataset_name="ops", content_type="skills")  # SKILL.md playbooks

メモリをクエリする

from cognee import SearchType

results = await cognee.recall("What changed in Q1 2024?", datasets=["research"], top_k=10)

# Pin a strategy when the user needs one
results = await cognee.recall(
    "What changed in Q1 2024?",
    query_type=SearchType.TEMPORAL,
    datasets=["research"],
)

# Answers with evidence, or validated into a Pydantic model
results = await cognee.recall("...", include_references=True)
results = await cognee.recall("...", response_model=MyAnswerModel)

# Retrieval context only, no LLM completion (pin query_type here)
context = await cognee.recall("...", query_type=SearchType.GRAPH_COMPLETION, only_context=True)

NodeSets による検索範囲の指定

ユーザーが、1 つのプロジェクト、顧客、ユーザー、またはワークフローなど、メモリの一部だけを検索したい場合は、NodeSets を使用します。

results = await cognee.recall(
    "What are this customer's reporting preferences?",
    datasets=["customer_success"],
    node_name=["preferences", "customer_123"],
)

既存のグラフを拡充する

ユーザーが、すでに構築済みのグラフを再取り込みせずに改善または拡張したい場合は、improve() を使用します。session_ids を指定しない場合は、グラフ全体に適用されるステージ（オプトインによる競合のレビューとグローバルコンテキストのインデックス作成）のみが実行されます。指定すると、それらに加えてフィードバックの重み付け、セッションの Q&A の永続化、セッションの教訓のグラフへの抽出も行われます。

await cognee.improve(dataset="research")
await cognee.improve(dataset="research", session_ids=["chat_1"])
await cognee.improve(dataset="research", build_global_context_index=True)

データを削除する

forget() は、削除処理の単一のエントリーポイントです。

await cognee.forget(data_id=data_id, dataset_id=dataset_id)  # one document
await cognee.forget(dataset="research")  # a dataset: raw data + graph + vectors
await cognee.forget(dataset="research", memory_only=True)  # graph + vectors only, keep raw files
await cognee.forget(everything=True)  # everything the current user owns

ドキュメントをその場で更新する

await cognee.update(data_id=data_id, data="Updated content", dataset_id=dataset_id)

ドキュメントの data_id は維持され、編集が影響したチャンクのみが再抽出されます。

ドメイン固有の構造を作成する

DataPoint を継承した Pydantic モデルを graph_model として渡すと、LLM は汎用ナレッジグラフの代わりに、そのモデルを埋めます。

from cognee.infrastructure.engine import DataPoint


class Person(DataPoint):
    name: str
    role: str
    metadata: dict = {"index_fields": ["name"], "identity_fields": ["name"]}


class Company(DataPoint):
    name: str
    employs: list[Person] = []  # a DataPoint field becomes an edge named after the field
    metadata: dict = {"index_fields": ["name"], "identity_fields": ["name"]}


await cognee.remember("...", dataset_name="org", graph_model=Company)

テキスト抽出を介さず、構造化された Python オブジェクトを直接挿入します。

from cognee.tasks.storage import add_data_points

await add_data_points([Person(name="Ada", role="Engineer")])

examples/guides/custom_graph_model.py と examples/guides/custom_data_models.py を参照してください。

カスタムパイプラインを実行する

ユーザーがタスクの実行順序を明示的に制御する必要がある場合は、run_custom_pipeline(...) を使用します。

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


async def my_task(data):
    return data


await cognee.run_custom_pipeline(
    tasks=[Task(my_task)],
    data="input",
    dataset="research",
)

DataPoints

DataPoint は、Cognee における知識の最小単位です。

Cognee が内部で構造化データをどのように表現するか、またはグラフオブジェクトを直接挿入する方法についてユーザーから尋ねられた場合は、この概念を使用します。

主なポイント：

• DataPoint は、意味のある情報単位を表す Pydantic モデルです。
• 挿入すると、DataPoints はグラフノードになり、他の DataPoints を保持するフィールドはエッジになります。
• metadata = {"index_fields": [...]} は、セマンティック検索用に埋め込むフィールドを制御します。
• metadata = {"identity_fields": [...]} を指定すると、ノード ID が決定的になり、繰り返し挿入しても重複せずに統合されます。

次のような場合は DataPoint を使用します。

• スキーマに沿ったメモリ
• グラフ構造の正確な制御
• プログラムによる関係の作成
• 論文、顧客、インシデント、ポリシー、製品、ワークフローなどのカスタムドメインエンティティ

非構造化ドキュメントには、通常の remember(...) を優先してください。テキストをスキーマに沿って抽出する場合は、graph_model= を優先してください。ユーザーがすでに構造化された Python オブジェクトを持っている場合は、DataPoint モデルと add_data_points(...) を優先してください。

NodeSets

メモリにタグ付け、グループ化、検索範囲の指定を手軽に行いたい場合は、NodeSets を使用します。

NodeSet は、remember(...) に node_set=[...] を渡すタグのリストから始まります。グラフの構築後、それらのタグは第一級のグラフノードとなり、recall(node_name=[...]) によって検索対象をそれらに限定できます。

NodeSet の適切なパターン

• 顧客ごと：["customer_123"]
• ワークフローごと：["support_bot", "refund_flow"]
• トピックごと：["contracts", "vendor_risk"]
• 環境ごと：["prod", "staging"]
• ユーザーメモリごと：["user_42", "preferences"]

例

await cognee.remember(
    [
        "Alice prefers terse answers and email follow-ups.",
        "Alice escalates billing issues to finance first.",
        "Bob prefers detailed technical explanations.",
    ],
    dataset_name="agent_memory",
    node_set=["crm", "user_profiles"],
)

results = await cognee.recall(
    "How should I respond to Alice?",
    datasets=["agent_memory"],
    node_name=["crm", "user_profiles"],
)

ユーザーが次のような要望を伝えた場合は、デフォルトで NodeSets を使用します。

• 「メモリの検索範囲を顧客ごとに指定する」
• 「データベースを分けずにプロジェクトを分離する」
• 「エージェントが自身のメモリだけを検索できるようにする」
• 「事実をワークフローまたはチームごとにグループ化する」

SearchType 選択ガイド

query_type を省略すると、recall() が自動的にルーティングします。特定の戦略が必要な場合は、cognee.SearchType（全 20 種類）から選択してください。

回答生成タイプ（LLM が回答を生成します）：

• HYBRID_COMPLETION：ドキュメントのパッセージとエンティティの近傍情報を使用します。ルーティングが無効な場合のデフォルトです
• GRAPH_COMPLETION：グラフの走査と回答生成を組み合わせます。グラフを活用した汎用的な Q&A に最適です
• GRAPH_COMPLETION_COT：グラフのコンテキストを用いた、より深い思考の連鎖による推論を行います
• GRAPH_COMPLETION_CONTEXT_EXTENSION：より広範なグラフコンテキストを取得します
• GRAPH_COMPLETION_DECOMPOSITION：最初に質問をサブクエリに分割します
• GRAPH_SUMMARY_COMPLETION：グラフコンテキストと事前計算済みの要約を使用します
• RAG_COMPLETION：ドキュメントチャンクを対象とした従来型の RAG を行います
• TEMPORAL：時間を考慮したグラフ検索を行います
• AGENTIC_COMPLETION：skills を読み込み、tools を呼び出せる複数ステップのループを実行します

検索専用タイプ（LLM の呼び出しなし）：

• CHUNKS：チャンクを対象にセマンティック検索を行います
• CHUNKS_LEXICAL：正確な語句／キーワード（BM25）の照合を行います
• SUMMARIES：事前計算済みのドキュメント要約を使用します
• SKILLS：SKILL.md のプレイブックを検出します（メタデータのみ。データセットは 1 つのみ）
• CODE：code_query を介して、決定的なコードグラフ操作を行います（呼び出し元、パス、影響分析）

その他：

• CYPHER：生の Cypher を実行します。デフォルトでは無効です（ALLOW_CYPHER_QUERY=true で有効になります。Postgres のデモグラフでは利用できません）
• NATURAL_LANGUAGE：自然言語からグラフクエリを生成します。デフォルトでは無効です（同じ ALLOW_CYPHER_QUERY=true フラグで有効になります）
• CODING_RULES：保存済みのコーディングルールを取得します
• GRAPH_REPORT：グラフのインサイトレポートを生成します（ハブ、ソース間リンク、提案された質問）
• FEELING_LUCKY：Cognee に選択を任せます

CLI で公開されているのはこのうち 10 種類です（cognee-cli recall --query-type）。残りは SDK でのみ使用できます。

セッション、フィードバック、自己改善

Cognee には 2 つのメモリ層があります。

• 永続メモリ：session_id を指定せずに remember(...) を呼び出します。ナレッジグラフが使用されます。
• セッションメモリ：session_id を指定して remember(..., session_id=...) を呼び出します。LLM を呼び出さずに書き込まれる、高速なセッションキャッシュです。recall(..., session_id=...) は最初にこのキャッシュを検索し、見つからない場合はグラフを検索します。CACHING=true が必要です（デフォルト）。

# Short-term: store a turn in the session cache, recall it instantly
await cognee.remember("User wants weekly summaries on Fridays.", session_id="chat_1")
results = await cognee.recall("when does the user want summaries?", session_id="chat_1")

# Long-term: bridge the session into the permanent graph
await cognee.improve(dataset="main_dataset", session_ids=["chat_1"])

self_improvement=True（デフォルト）を指定した remember(..., session_id=...) は、バックグラウンドでグラフと連携するため、タイミングを制御する必要がある場合を除き、明示的な improve() の呼び出しは不要です。

フィードバック

フィードバックはセッションの Q&A エントリに紐付けられ、後から improve() によって検索の重みに反映されます。

from cognee import FeedbackEntry

# Rate an earlier answer (qa_id is the entry_id returned by the remember() that stored it)
await cognee.remember(
    FeedbackEntry(qa_id=qa_id, feedback_score=5, feedback_text="Captured the key themes."),
    session_id="chat_1",
)
# Equivalent helper API
await cognee.session.add_feedback(session_id="chat_1", qa_id=qa_id, feedback_score=5)
history = await cognee.session.get_session(session_id="chat_1")

AUTO_FEEDBACK=true（デフォルト）の場合、回答した各ターンについても、構造化出力を行う LLM 呼び出し 1 回で暗黙的なフィードバックを分析します。低レイテンシで読み取る場合は、AUTO_FEEDBACK=false を設定してください。

エージェントをラップする

@cognee.agent_memory は、エージェント関数の呼び出しをセッショントレースとして記録し、各呼び出しの前にコンテキストを取得します。examples/guides/agent_memory_quickstart.py を参照してください。

エージェント型ワークフローとフィードバック駆動の改善

より優れた想起、過去の作業のより有効な再利用、過去に成功した行動のより適切な検索を通じて、時間とともに改善していく必要のあるエージェントシステムのメモリレイヤーとして Cognee を使用します。

基本的な考え方はシンプルです。

• エージェントのワークフロー自体は一定に保ちます
• プロンプトとツールは一定に保ちます
• エージェントが記憶し、検索できる内容だけを変更します

「改善」はモデルの変更ではなく、メモリの再利用と検索品質によって実現します。

一般的なエージェントループ

1. Observe（観察） — 入力、イベント、好み、結果、エラー、判断を取得します。
2. Store（保存） — remember(...) で保存します。アクティブな実行には session_id を付け、長期的に残すべき事実には付けないでください。
3. Organize（整理） — データセットと NodeSet を使って、顧客、ワークフロー、チーム、エージェント、トピックごとにメモリを分けます。
4. Recall before acting（行動前に想起） — 計画、ツール使用、統合、応答生成の前に recall(...) を実行します。
5. Capture feedback（フィードバックの記録） — うまくいったことと、うまくいかなかったことを FeedbackEntry / session.add_feedback で記録します。
6. Consolidate（統合） — improve(dataset, session_ids=[...]) を実行し、セッション履歴と学んだ教訓を長期的なグラフメモリに変換します。
7. Reuse（再利用） — 将来の実行では、より豊富なコンテキストとより的確な検索の恩恵を受けられます。

最小限の例のパターン

import cognee

# 1) Store a durable observation
await cognee.remember(
    "Customer 123 prefers concise status updates and Slack notifications.",
    dataset_name="agent_memory",
    node_set=["customer_123", "preferences", "support_agent"],
)

# 2) Recall before acting, inside a session
context = await cognee.recall(
    "What should I know before replying to customer 123?",
    datasets=["agent_memory"],
    session_id="support-session-123",
)

# 3) Continue work in the same session
answer = await cognee.recall(
    "Draft the best reply for customer 123.",
    datasets=["agent_memory"],
    session_id="support-session-123",
)

# 4) Consolidate the session into long-term memory later
await cognee.improve(dataset="agent_memory", session_ids=["support-session-123"])

最も適した説明

ユーザーが Cognee がエージェントの継続的な改善にどう役立つかを尋ねた場合は、次のように答えてください。

Cognee を使うと、エージェントは有用な情報をより多く記憶し、それを検索可能なグラフメモリに整理し、過去の成功した作業を将来の実行で再利用できるようになるため、時間とともに改善できます。

設定に関するヘルプ

ユーザーがプロバイダーやバックエンドの設定を必要とする場合は、Cognee の設定ヘルパーまたは環境変数を使用してください。

cognee.config.set_llm_provider("openai")
cognee.config.set_llm_model("gpt-5-mini")
cognee.config.set_llm_api_key("sk-...")

環境変数（.env）: LLM_API_KEY、LLM_MODEL、LLM_PROVIDER、EMBEDDING_*、 GRAPH_DATABASE_PROVIDER（既定は ladybug、neo4j、neptune、postgres_demo）、VECTOR_DB_PROVIDER （既定は lancedb、pgvector、turso）、DB_PROVIDER（既定は sqlite、postgres）、CACHE_BACKEND。 LLM だけ、または埋め込みだけが設定されている場合、もう一方の既定値は OpenAI になります。

データセットとライフサイクルの操作

datasets = await cognee.datasets.list_datasets()
data = await cognee.datasets.list_data(dataset_id)
await cognee.forget(dataset="research")  # preferred over datasets.empty_dataset / delete_all

可視化

visualize_graph は、既定ではグラフ全体ではなく、限定されたサブグラフ（シードノードと k ホップの近傍、max_nodes で上限を設定）を描画します。

# Default: bounded subgraph. Seed by a query, explicit ids, or a recall result;
# with none of those, the highest-degree nodes seed a representative view.
await cognee.visualize_graph("/path/to/output.html")
await cognee.visualize_graph("/path/to/output.html", query="What relates to Python?")
await cognee.visualize_graph("/path/to/output.html", seed_node_ids=["node-id-1"])
await cognee.visualize_graph("/path/to/output.html", recall_result=recall_output)

# Legacy whole-graph render.
await cognee.visualize_graph("/path/to/output.html", full=True)

await cognee.start_visualization_server(port=8080)
await cognee.start_ui()

上限のデフォルト値: neighborhood_depth=2、neighborhood_seed_top_k=10、max_nodes=500。 詳細は examples/guides/graph_visualization.py を参照してください。

完全リセット（テスト専用）

forget(everything=True) はユーザーのデータとメモリを削除します。ユーザー、ACL、データセットレジストリも削除する場合（テストの完全な後片付け）は、prune を使用します。

await cognee.prune.prune_data()
await cognee.prune.prune_system(graph=True, vector=True, metadata=True, cache=True)

重要な動作上の注意

• Cognee の API は 非同期 です。
• ユーザーが低レベルのステージを 1 つだけ必要とする場合を除き、remember -> recall（+ improve、forget）を優先してください。
• 後でスコープ付きの検索が必要になるかもしれない場合は、早めに node_set を使用してください。
• 短期メモリと会話の継続性には session_id を使用し、improve(session_ids=...) で永続化してください。
• graph_model= や DataPoint 型は、スキーマに沿った抽出が必要な場合にのみ使用してください。
• CYPHER は、設定で Cypher クエリが有効になっている場合にのみ使用してください。
• 例は最小限に保ち、そのまま実行できるようにしてください。

複雑にしすぎない

ユーザーから要求されたり、問題が明らかに必要としたりしない限り、高度なバックエンド、オントロジー設定、カスタムパイプラインにいきなり踏み込まないでください。まずは最小限の正しい Cognee のソリューションを優先し、そこから拡張してください。