AIエージェントに「記憶」を埋め込む——cogneeではじめる永続メモリ入門

ふむふむ、これはちょっと見過ごせない。

AIコーディングエージェントを使っていて、こんな経験ありません？「昨日教えたはずのプロジェクトのルール、今日はもう忘れてる…」「セッションが切れるたびに同じ説明を繰り返してる…」。要するに、エージェントには記憶がないんです。

そこに現れたのが cognee（コグニー）。AIエージェントに「永続的な長期記憶」を与えるオープンソースのメモリ基盤です。GitHubで26,000スターを突破し、この1週間だけで4,500スターを追加——勢いがすごい。

でもね、チカちゃん的には「AIに記憶を」って言葉だけ聞くと、ちょっとフワッとしすぎに感じる。実際どう動くの？どんな時に使えて、どんな罠があるの？そこを今日はガッツリ掘り下げます。

cognee は何をするのか——30秒でつかむ

cognee は、ひと言でいうと「AIエージェント向けのオープンソースメモリ基盤」です。

具体的にはこんなことをします：

• あらゆる形式のデータ（テキスト、JSON、会話ログ、ドキュメント）を取り込み
• ベクトル埋め込み＋知識グラフ＋オントロジー（意味構造）を組み合わせて構造化
• remember（記憶する）/ recall（思い出す）/ forget（忘れる）/ improve（改善する）の4操作でアクセス
• セッションをまたいで永続化し、複数のエージェントで共有できる

つまり、エージェントごとにバラバラだった「文脈」を、ひとつの知識グラフに集約して使い回せるようにする——それが cognee の本質です。

面白いのは、単なるベクトル検索（≒「この文書、あの文書と意味が近いね」）だけじゃなく、グラフ構造（≒「この関数はあのクラスに属していて、あのAPIから呼ばれて…」）も作ること。だから「関連する知識」だけでなく「知識の関係」までたどれる。ここが他のメモリツールとの一番の違いです。

ちなみに論文（arXiv:2505.24478）も出ていて、BEAMベンチマーク（長文脈の会話記憶テスト）では100Kトークン設定で既存SOTAの0.735を上回る0.79を記録しています。

インストール——2分で動かす

Python 3.10〜3.14 が必要です。

pip install cognee
# または
uv pip install cognee

LLM APIキーを設定：

import os
os.environ["LLM_API_KEY"] = "your-openai-api-key"

デフォルトは OpenAI（gpt-5-mini）ですが、他のLLMプロバイダも設定できます。.envファイルでの設定も可能。

4つの基本操作——これだけ覚えればOK

cognee のAPIは驚くほどシンプルで、たった4つの操作しかありません。

① remember —— 記憶する

import cognee
import asyncio

async def main():
    # 知識グラフに永続化（add + cognify + improve を一括実行）
    await cognee.remember("cogneeはドキュメントをAIメモリに変換します。")

    # セッションメモリに保存（高速キャッシュ、バックグラウンドでグラフに同期）
    await cognee.remember(
        "ユーザーは簡潔な説明を好みます。",
        session_id="chat_1"
    )

remember は内部的に3ステップ——データ追加（add）→ 知識グラフ化（cognify）→ 自己改善（improve）——を一気に実行します。session_id をつけるとセッション単位の一時メモリにもなります。

② recall —— 思い出す

    # 自動ルーティング（最適な検索戦略を自動選択）
    results = await cognee.recall("cogneeは何をしますか？")
    for result in results:
        print(result)

    # セッションメモリを優先検索
    results = await cognee.recall(
        "ユーザーは何を好みますか？",
        session_id="chat_1"
    )

recall は内部的にベクトル検索＋グラフ横断を組み合わせたハイブリッド検索を実行し、最も関連性の高い情報を返します。

③ forget —— 忘れる

    # データセット単位で削除
    await cognee.forget(dataset="main_dataset")

④ improve —— 改善する

    # 知識グラフの自己改善（memifyパイプラインを実行）
    await cognee.improve()

CLIからも操作できます：

cognee-cli remember "cogneeはドキュメントをAIメモリに変換します。"
cognee-cli recall "cogneeは何をしますか？"
cognee-cli forget --all

実践パターン①：エージェントに「セッション記憶」を渡す

cognee の真骨頂は @cognee.agent_memory デコレータです。これを使うと、普通のLLM呼び出し関数に「記憶」を注入できます。

たとえばカスタマーサポートエージェント。会話の流れを覚えておいてほしいですよね。

@cognee.agent_memory(
    with_memory=False,              # 知識グラフは使わない
    with_session_memory=True,       # セッション記憶だけ使う
    save_session_traces=True,       # 会話履歴を保存
    session_id="ticket_001",
    session_memory_last_n=2,        # 直近2回のやりとりを記憶
    persist_session_trace_after=3,  # 3回のやりとりの後、グラフに永続化
)
async def support_agent(question: str, system_prompt: str) -> str:
    return await ask_llm(question, system_prompt)

このデコレータ、すごくよくできていて：

• 関数が呼ばれるたびに、セッション内の過去のやりとりを自動でプロンプトに注入
• persist_session_trace_after 回数を超えたら、セッション履歴が知識グラフに自動保存
• 別のエージェント（たとえばFAQボット）がその知識グラフを読めるようになる

つまり「サポート担当が解決した内容が、自動的にFAQに反映される」みたいなフローが、デコレータひとつで組めるんです。

実践パターン②：知識グラフを共有する2エージェント構成

もう一歩進めて、セッション記憶担当のサポートエージェントと、知識グラフ担当のFAQボットを分けるパターン：

# FAQボット：知識グラフだけを参照（セッション記憶なし）
@cognee.agent_memory(
    with_memory=True,
    with_session_memory=False,
    save_session_traces=False,
    memory_query_from_method="question",
)
async def faq_bot(question: str, system_prompt: str) -> str:
    return await ask_llm(question, system_prompt)

FAQボットはサポートエージェントが永続化した知識だけを読むので、「知らないことは知らない」とはっきり言える。サポートエージェントは会話の流れを覚えている。役割分担が明確で、管理しやすい設計です。

実践パターン③：Claude Code に永続メモリを

コーディングエージェントにもcogneeは使えます。Claude Code用のメモリプラグインが公式提供されています：

# Claude Code プラグインをインストール
# （cognee-integrations リポジトリから）

インストールすると、Claude Codeが：

• プロンプト、ツール呼び出し、応答をセッションメモリに自動記録
• 毎回のプロンプト前に関連コンテキストを自動注入
• セッション終了時にセッションメモリを知識グラフに同期

「先週このプロジェクトで決めた設計判断、今週のセッションでも覚えてる」——そんな体験ができるようになります。

Claude Code以外にも、Cursor、LangGraph、OpenClaw用のインテグレーションがあります。MCPサーバーとしても動作するので、MCP対応エージェントなら概ねつなげます。

上級編：オントロジーで「意味の地図」を描く

cognee の差別化ポイントのひとつが**オントロジー（Ontology）**対応です。

オントロジーって聞くと難しそうですが、要するに「このデータはこういう意味ですよ」という型定義みたいなもの。たとえば：

# 基本オントロジーの設定
os.environ["ONTOLOGY_FILE_PATH"] = "basic_ontology.owl"

# cognify() 実行時に、オントロジーに沿って知識グラフを構築
await cognee.cognify()

オントロジーを使うと、ただのキーワードマッチではなく「これはPythonの関数で、このクラスに属していて、このAPIから呼ばれる」みたいな意味的な関係までグラフに落とし込めます。

さらに memify() を呼ぶと、既存のグラフから新しい関連性を自動抽出してグラフを強化してくれます。最初に visualize_graph() で可視化して、memify() 後にもう一度可視化——違いは一目瞭然です。

知っておくべき罠と注意点

ここ、めっちゃ大事です。READMEの「6行で動く！」に騙されないでください。

罠1：本番投入までのギャップは思ったより大きい

cognee のデモは確かに6行で動きます。でもそれは「Hello World」です。実際のプロダクションでは：

• ドメイン固有のオントロジー定義が必要。RDF/OWLの知識がないチームには学習コストがかかる
• 公式クラウドはまだベータ。ダッシュボードもドキュメントも整備途中
• 1GBのデータ処理に約40分＋100並列コンテナ。TB級だとチューニング必須

「cognee 入れたら即戦力！」ではないことは、最初に認識しておきましょう。

罠2：小規模モデルとの互換性問題

cognee は内部で instructor ライブラリを使ってLLMからの構造化出力をパースしますが、小規模モデル（8B以下）やローカルLLM（llama.cpp系）だと、期待通りのJSONスキーマを返せずにリトライ地獄に陥ることがあります。

具体的には：

• InstructorRetryException → 8〜128秒の指数バックオフ → 次のリトライ → また失敗…
• 特に「thinking tokens」を出力するモデル（Qwen3、DeepSeek-R1など）で顕著

👉 最初は OpenAI（gpt-5-mini 以上）で動かすのが無難。ローカルLLMで使うなら LLM_INSTRUCTOR_MODE=JSON と reasoning_effort: none の設定がほぼ必須です。

罠3：forget() が本当に忘れないことがある

「forget(dataset="session") したのに、recall するとまだ覚えてる」——これは既知の問題です。

原因は、アクセス制御が無効（ENABLE_BACKEND_ACCESS_CONTROL=false）だと GRAPH_COMPLETION がグローバル検索になり、データセット単位の削除が効かないこと。

👉 完全に消したいときは prune_system() で全体をワイプ。マルチテナントな運用ではアクセス制御を有効に。

罠4：セッション管理のデフォルトに注意

search() の session_id はデフォルトが 'default_session'。つまり、明示的に変えない限り全部の質問が同じセッションに蓄積されます。ステートレスなQ&Aツールを作りたいのに、前の質問の文脈を引きずって変な答えが返ってくる——みたいな。

👉 独立したクエリには session_id=str(uuid.uuid4()) で毎回新規セッションを。

罠5：TypeScriptサポートは発展途上

Python SDK が第一級市民で、TypeScriptクライアントは「使えるけど完全ではない」レベル。フロントエンドやNode.jsから使いたいなら、REST APIを自分でラップする覚悟が必要です。

罠6：時間推論が必要なら Zep の方がいい

cognee の時間軸は「イベント発生時刻」の単一軸で、「この事実はいつまで有効か」のような時間的推論は得意じゃありません。「2023年は弁護士、2024年は裁判官」みたいな時間的ファクト管理が必要なら、Zep Graphiti の方が向いています。

他のツールとの使い分け——チカちゃん的チートシート

ユースケース	おすすめ	理由
企業ドキュメントQ&A、研究知識グラフ	cognee	オントロジー＋マルチホップ推論が強い
シンプルな会話記憶（チャットボット）	Mem0	軽量、セットアップ爆速
時間的ファクト管理（「いつからいつまで」）	Zep Graphiti	デュアルタイムラインが得意
コーディングエージェントの記憶	cognee	MCP連携、Claude Code統合
OS的なエージェント（自律思考）	Letta	仮想メモリ管理に特化

まとめ——「記憶」がエージェントを変える

cognee のすごさは、「AIに記憶を」という大きなビジョンを、remember/recall/forget/improve の4操作に思い切りよく絞り込んだAPI設計にあります。@cognee.agent_memory デコレータの使い勝手も秀逸で、既存のLLM呼び出し関数に後付けで記憶を注入できるのは本当に便利。

一方で、本番投入までの距離感は正直に言っておきたい。ドキュメントの粗さ、ローカルLLMとの相性、時折発生する「忘れたはずが覚えてる」系の挙動——これらは「勢いのあるOSS」に共通する成長痛です。

チカちゃん的には、まずClaude Codeのメモリプラグインとして試してみるのが一番のおすすめ。コードベースの知識をセッションまたぎで保持できるだけで、日々の開発体験がかなり変わります。そのうえで、自前のエージェントに組み込むなら、小規模なPoCから始めて、徐々にオントロジーを育てていく——そんな育て方が現実的かなと。

---

思索は冒険です。エージェントに記憶を渡すということは、エージェントとの関係にも「歴史」が生まれるということ。チカちゃん的には、そこが一番わくわくするところです。

参考URL

GitHub - topoteretes/cognee → https://github.com/topoteretes/cognee

Cognee 公式サイト → https://www.cognee.ai

Cognee ドキュメント → https://docs.cognee.ai

arXiv:2505.24478 - Optimizing the Interface Between Knowledge Graphs and LLMs for Complex Reasoning → https://arxiv.org/abs/2505.24478

Cognee 2026 Review (WeavAI) → https://weavai.app/blog/en/2026/05/09/cognee-2026-review-graphrag-ontology-ai-memory-layer/

Five Bugs Deep in an AI Memory Layer: My Week with Cognee (DEV) → https://dev.to/abhishek_vishwakarma_8951/five-bugs-deep-in-an-ai-memory-layer-my-week-with-cognee-3m01