Claude CodeのCogneeプラグインでナレッジグラフ型メモリを使う

cognee-memoryは、Claude Codeのやり取りをCogneeのナレッジグラフに貯め、次のセッションで引き出すプラグインです。マーケットプレイスのページには「Anthropic verified」の表示があり、説明文は「セッション単位の保存、自動ルーティングの想起、セッションをまたぐ永続的な学習」を掲げています。ローカルモードとCognee Cloudの両方に対応します。

入れたあとにやることは、LLMのキーを1回設定するだけです。記録も想起も自動で走ります。必要なときだけ、スキルで明示的に呼び出します。

cognee-memoryは何を記録し、どこへ送るのか

記録されるのは、プロンプト、Claudeのツール呼び出し(名前・引数・出力)、Claudeの回答です。コンパクション前には短い「記憶のアンカー」も残します。認証情報、秘密鍵、データベースURLは保存や送信の前に伏せられます。.envや認証情報・鍵のファイルは、そもそも記録しません。

仕組みは2層です。

• セッションキャッシュ: セッション単位の軽い置き場で、記録時にグラフの抽出はしない
• 永続ナレッジグラフ: セッションをまたいで残る記憶。同期のときにキャッシュから昇格する

1プロンプトごとに起きることは、フックの表で追えます。

送信先は、設定したCogneeサーバーだけです。ローカルモードではプラグインがlocalhost:8011でサーバーを起動し、メモリはそのマシンに保存されます。ただしグラフを組み立てるとき、そのサーバーが記録テキストを設定したLLMと埋め込みの提供元へ送ります。クラウドモードではHTTPSでCOGNEE_BASE_URLのインスタンスへ送ります。READMEは、テレメトリや分析は送らず、上記以外の送信先はないと明記しています。

自動メモリとの関係

クラウドモードでは、Claude Code標準の自動メモリを、利用者が明示的に有効にしていない限り無効化します。元の値は復元用に保持され、COGNEE_DISABLE_AUTO_MEMORY=falseで無効化を避けられます。既存のメモリファイルは残ります。標準側の仕組みはClaude Code memoryの三層構造にあります。

導入手順とLLMキーの設定

必要なのは、フックを動かすpython3(3.9以上)です。フックは標準ライブラリだけのHTTPクライアントなので、macOSのXcode Command Line Toolsに付くPythonで足ります。ローカルモードはさらに、Python 3.10〜3.14がどこかに入っている必要があります。プラグインがそれを見つけて~/.cognee-plugin/venvに専用の仮想環境を作り、固定バージョンのcogneeを入れます。インタプリタのダウンロードはしません。見つからなければ、セッション開始時にそう表示されます。

READMEが勧める導入は、Claude Codeを起動する前にシェルから行う方法です。最初の起動でプラグインの初期化がそのまま走ります。

claude plugin marketplace add topoteretes/cognee-integrations
claude plugin install cognee-memory@cognee

チャット内の/pluginコマンドでも入りますが、その場合はClaude Codeを再起動するまで接続されません。/reload-pluginsではスキルが使えるようになるだけで、SessionStartは走らないためです。

次にLLMキーを~/.cognee/.envへ書きます。ローカルモードではCogneeが知識の抽出にLLMを使うので、一度だけ設定します。

mkdir -p ~/.cognee
cat >> ~/.cognee/.env <<'EOF'
LLM_API_KEY="sk-..."
EOF
chmod 600 ~/.cognee/.env

シェルのexportは、このファイルより優先されます。貼り直しても最後の値が勝つので、やり直しは安全です。起動後に「Cognee Memory Connected」のメッセージが出れば接続できています。

ローカルとクラウドをどう切り替えるか

Cognee Cloudやリモートサーバーを使うなら、同じ.envにCOGNEE_BASE_URLとCOGNEE_API_KEYを書きます。両モードの変数を同居させてもかまいません。どちらになるかは、端末ごとに次の順で決まります。

両方を設定した状態で、1回だけローカルにするなら次のように起動します。

claude                        # URLがあるのでクラウド
COGNEE_BACKEND=local claude   # この起動だけローカル

unset COGNEE_BASE_URLではローカルに戻りません。次の起動で.envがURLを再び注入するためです。COGNEE_BACKEND=cloudのままURLがない場合も、黙ってローカルへ落ちることはなく、ステータス行にmissing_cognee_base_urlが出ます。

記憶はいつ、どうやってグラフになるのか

記録した直後のデータはセッションキャッシュにあります。グラフへの昇格は、セッション対応のimproveで行われます。条件は3つあります。

• セッション終了時に最終同期が走る
• 保存したツール呼び出しと停止がCOGNEE_AUTO_IMPROVE_EVERY(既定150)に達すると自動同期が走る
• /cognee-memory:cognee-syncで手動実行する

自動同期には、同じセッションでCOGNEE_IMPROVE_COOLDOWN(既定86400秒、24時間)のクールダウンがあります。手動のcognee-syncと最終同期はクールダウンを無視します。「さっきの作業をすぐ検索可能にしたい」ときは、手動の同期が早道です。

書き込みもバックグラウンドで動きます。cognee-rememberと自動記録は、グラフの構築を待たずに返ります。直後の想起に新しい項目が出ないことがあるのはこのためです。同期的に書きたいならCOGNEE_REMEMBER_BACKGROUND=falseにします。

同梱スキルの呼び分け

スキルは、普通の言葉で頼めばClaudeが説明文から選びます。/cognee-memory:cognee-search <クエリ>のようにスラッシュコマンドでも呼べます。

このほかにアーキテクチャ解説のcognee-architectureと、仕組みの質問に答えるcognee-how-it-worksもあります。Claude Code 2.1.287以降(Desktopアプリでは2.1.286以降)では、hooksモジュールが/cognee-dataset、/cognee-tourと、search・rememberの2つのツールを加えます。ステータス行の表示も、このモジュールが担います。

忘れさせたいときの挙動

cognee-forgetは、まず現在のセッションを同期して未同期の内容を削除可能な文書にし、候補の中身を読み、利用者に確認してから削除します。消えるのは生データ、そこから派生したグラフ上の知識、可能な範囲でその知識を引用したセッションのQ&Aです。削除は取り消せません。データセット全体の削除は、明確な依頼がある場合に限られます。

コードグラフは何を注入するのか

フック表のPreToolUse(Read)が出すのは、リポジトリを索引化したコードグラフの情報です。記憶のグラフとは別物で、シンボル、呼び出し、インポート、エンドポイント、依存を決定的に取り出します。索引化はLLMも埋め込みも呼ばないので、トークンはかかりません。Cogneeサーバーは1.5.3以上が必要です。

gitリポジトリの中でセッションを始めると、バックグラウンドで自動的に索引化されます。最初のプロンプトは待たされません。作業ツリーが変わったターンの後には再索引化が走ります。別のリポジトリやgitのURLを索引化したいときは、cognee-codeスキルに頼むか、プラグイン同梱のcognee-index-repo.shを使います。

ソースファイルをReadする直前には、そのファイルのクラス・関数の行番号、呼び出し先、インポートが短い地図として差し込まれます。モデルは全体を流し読みせず、目的の行へ飛べます。同じファイルは1セッションに1回だけ(COGNEE_FILE_CONTEXT_TTLの既定は1800秒)で、.envや鍵のような機微なパス、コード以外のファイル、索引化されていないリポジトリでは何も出しません。止めたいときはCOGNEE_FILE_CONTEXT=falseです。

注意点は、サーバーの置き場所で鮮度が変わることです。

リモートサーバーはディスクを読めないため、手元の編集はpushするまで見えません。クラウドで作業中のコードについて尋ねるときは、先にpushするか、ブランチを編集している間はローカルサーバーを使います。自動索引化は、COGNEE_CODE_AUTOINDEXの既定(auto)ではサーバーがローカルのときだけ走ります。コードがマシンの外へ出ないようにするための既定です。

索引化は、リポジトリ内の.enola/にスナップショットを書き出します。追跡されないディレクトリなので、.gitignoreに.enola/を足しておくと誤コミットを避けられます。

ステータス行で接続状態を読む

ステータス行は、プロンプトの上に● cognee manual · cloud · 3 memories usedのような1行を出します。先頭の丸が接続状態で、緑の●はサーバーが生きていて認証も通っている印です。確認がまだなら薄い○が出ます。

失敗すると、行頭が赤い✕ (理由)に変わります。理由は次のとおりです。

この表示はローカルに残した状態ファイルを読むだけで、更新のたびにネットワークへは出ません。そのため、フックが失敗を観測するまでは緑のままです。想起の遅延が続いても、サーバーダウンとは判定されません。

Claude Code 2.1.287以降では、hooksモジュールがこの行をプロンプトの上に描きます。モジュールが読み込まれない環境では、セッション開始時に設定ファイルのstatusLineへ登録され、プロンプトの下に同じ内容が出ます。両方が同時に出ることはありません。更新のお知らせは琥珀色で、淡色の端末テーマにはCOGNEE_STATUSLINE_THEME=lightが使えます。

プラグインを更新する

更新は、マーケットプレイスの目録を更新してから、プラグイン本体を更新する2段です。

/plugin marketplace update cognee
/plugin update cognee-memory@cognee

Claude Codeは、プラグインのversionが変わったときだけ更新を案内します。同じバージョンを入れ直しても、キャッシュが再利用されます。更新が見えないときは、アンインストールしてマーケットプレイスを外し、追加と導入をやり直します。

自動更新は、公式のマーケットプレイスでは既定で有効ですが、サードパーティのcogneeマーケットプレイスでは自分で有効にする必要があります。設定すると、起動後にバックグラウンドで更新され、/reload-pluginsの実行を促されます。

新しい版が出ると、ステータス行に琥珀色の更新表示が出て、セッション開始時にも1バージョンにつき1回メッセージが出ます。裏で動く確認は1日に最大1回で、マーケットプレイスのマニフェストを1ファイル取得するだけです。データやテレメトリは送らず、止めるにはCOGNEE_UPDATE_CHECK=falseにします。

記録の範囲を絞る設定

プロンプトに秘匿したい内容が混じるリポジトリでは、記録の範囲を先に決めておきます。~/.cognee/.envか環境変数に書くと、新しいフックのプロセスから反映されます。

許可と除外は、Claude Codeの権限指定に似たBash(git:*)の書き方が使えます。たとえば検索系のBash呼び出しだけを除きたいなら、こう書きます。

COGNEE_CAPTURE_DENY_TOOLS="Bash(rg:*)|Bash(grep:*)|Bash(cat:*)"

この指定は最初の単語の前方一致で、シェルの構文解析ではありません。cd x && git statusはcdとして扱われます。解釈できない書き方は、黙って何も一致しないのではなく、自動記録を止めて次のプロンプトで知らせます。伏せ字処理はベストエフォートで、記録がそぐわないリポジトリにはCOGNEE_CAPTURE=falseが確実な手段です。止めても既存のメモリは消えないため、消したいときは前節のforgetを使います。

データセットは、既定ではagent_sessionsで、Claude CodeとCodexのプラグインが共有します。プロジェクトごとに分けたいなら、起動前にCOGNEE_PLUGIN_DATASETを設定します。同じCOGNEE_SESSION_IDを指定した2つの端末は、1つのセッションを共有します。

うまく動かないとき

READMEの切り分けは、症状ごとに次のとおりです。

• 想起が空: 想起は有効なデータセット内に限られます。SDKで書いたデータは、データセットを指定しないとdefault_datasetに入ります
• 意図と違うモードに接続した: 端末に残ったCOGNEE_BACKENDやCOGNEE_CLAUDE_BACKENDを疑います。プラグイン固有の名前が共有名より優先されます
• 認証エラー: ~/.cognee-plugin/api_key.jsonを削除すると再発行されます
• 原因が不明: ~/.cognee-plugin/claude-code/hook.logを読みます

外すときは/plugin uninstall cognee-memory@cogneeです。

cognee-memoryとrememberはどちらの引き継ぎに向くか

同じ「セッションをまたぐ引き継ぎ」を狙うプラグインでも、仕組みは違います。rememberプラグインはセッションをHaikuで日次ログに畳むファイル型です。cognee-memoryはグラフとして貯め、プロンプトごとに検索して差し込みます。

違いが出るのは、記憶の量と導入の手間です。昨日の続きを再開するだけなら、rememberのように起動時に読み込む方式で足ります。過去の判断を横断して検索したい、コードの構造も一緒に引きたいといった要求は、cognee-memoryの領分です。そのぶんPythonの環境とLLMキーが前提になり、内容はCogneeのサーバーとLLM提供元へ流れます。

どちらもコンテキストを消費するので、入れる前に記録したい範囲を決めておくと扱いやすくなります。どのプラグインを同時に読み込むかの切り分けには、CLAUDE_CODE_PLUGIN_DIRSが使えます。