コーディングエージェントのメモリ：Claude Code・Codex・Cursor

Claude Code、Codex、Cursorなどのコーディングエージェントでメモリを共有するなら、まずはバージョン管理した AGENTS.md と短いタスク引き継ぎメモを使います。記録と引き継ぎを自動化したければai-memory、セッションの記録を確認して再利用する知見を承認したければBeaconを追加します。どちらを選んでも、プロジェクトで必ず守るルールはリポジトリに残してください。

ツールを切り替えるときに何を残すか

長く有効な判断と、今のタスクの進捗は分けて保存します。新しいエージェントはコードを読めても、ある方法を採用しなかった理由、昨日伝えた修正、未完了の作業で次に進むべき手順までは把握できない場合があります。

必要なコンテキストには役割の異なる三つの種類があります。指示は作業方法を、引き継ぎメモは作業を止めた地点を示し、セッション履歴はその根拠を確認する材料になります。一つを共有しても、ほかの情報、実行中のプロセス、ツールの利用権限まで自動で移るわけではありません。

方法	引き継ぐ情報	選ぶ条件	別の方法に変える条件
リポジトリ内の指示と引き継ぎファイル	意識して更新するルール、判断、タスクの状態	少数のメモで十分で、Gitと一緒に管理したい	メモの更新忘れが続くならサービスの導入を検討する
ai-memory	記録した情報、検索できるMarkdownのWiki、エージェント間の引き継ぎ	頻繁にエージェントを切り替え、記録と取得を自動化したい	フック、認証情報、サーバーの管理負担が利点を上回るならファイルにとどめる
Beacon	形式をそろえたセッション記録と、明示的に承認したプロジェクトの知見	何が起きたかを調べ、繰り返す修正をレビュー済みの知識にしたい	記録や知見のレビューより自動引き継ぎを重視するならai-memoryを優先する

2026-10-21時点の比較対象は、ai-memory v3.1.2とBeacon v1.3.45です。違いはアーキテクチャにあります。ai-memoryはGitで管理するMarkdownのWikiに加え、サーバー、フック、MCPを備えています。一方、Beaconでは記録の収集とメモリの承認が別の処理になっています。

まずはAGENTS.mdと短い引き継ぎメモを用意する

AGENTS.md をプロジェクト共通の参照先にし、各ツールが実際に読み込むことを確認します。標準の読み込み規則はツールごとに異なります。

Codex： プロジェクトのルートから作業ディレクトリまでの経路にある指示を順に読み込みます。同じディレクトリでは AGENTS.override.md が AGENTS.md より優先されます。Codexの指示ファイル探索ルールを確認してください。
Cursor： ルートとサブディレクトリの AGENTS.md に対応しています。Cursor固有のルールを特定の範囲に適用する必要があれば、.cursor/rules/*.mdc に置きます。詳しくはCursorのルールのドキュメントを参照してください。
Claude Code： v2.1.277以降は AGENTS.md を直接読み込めます。ただし、標準では作業ディレクトリやその上位にある、読み込み条件を満たす CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md が優先されます。既存のClaude向け指示がある場合や直接読み込みに対応しないセッションでは、ルートの AGENTS.md と同じ場所にある CLAUDE.md に、@AGENTS.md という行を追加します。Claude Codeのメモリガイドには両方の方法が記載されています。

小さく試すには、次のルール案をルートの AGENTS.md に記述するか、既存の内容に統合します。

## Working context

- Before changing a dependency version, read its official release notes
  and run the tests for the affected component.
- When resuming work, read docs/agent-handoff.md if it exists.
- Treat handoffs as historical evidence. Check old commands, paths and
  conclusions against the current checkout before acting.

ここで追加するのは、依存関係の更新前に公式リリースノートと影響範囲のテストを確認すること、再開時に引き継ぎファイルを読むこと、過去の記述を現在の作業コピーと照合することです。引き継ぎを読むよう指示しておくことで、新しいエージェントにも参照先を明示できます。

実際のタスクを進めた後、エージェントに次のように引き継ぎメモの作成を依頼します。

Write docs/agent-handoff.md with the goal, current branch and commit,
confirmed decisions, commands actually run and their results,
remaining uncertainty, and the next concrete action.
Distinguish failed approaches from successful ones.
Do not include credentials or copy the full conversation.

このプロンプトでは、目標、現在のブランチとコミット、確認済みの判断、実行したコマンドと結果、残る不確実性、次の具体的な操作を記録させます。成功した方法と失敗した方法を区別し、認証情報や会話全文は含めません。

このファイルはコードの変更と一緒にレビューしてください。安定したルールは AGENTS.md に残し、引き継ぎメモは作業の進行に合わせて更新します。

各ツールで新しいセッションを開き、依存関係を更新する際の確認事項と、その指示を読み込んだファイルを尋ねます。Claude Codeでは /context からも読み込み済みのメモリファイルを確認できます。Codexがルールを認識しなければ、同じ内容のファイルを増やす前に、作業ディレクトリと指示を上書きするファイルを調べてください。

標準の自動メモリも、それぞれの環境内では役立ちます。Claude Codeのプロジェクトメモは ~/.claude/projects/<project>/memory/ に保存されます。Codexのローカルメモリは有効化が必要で、保存先は ~/.codex/memories/、操作には /memories を使います。これらは別々の保存領域であり、ツール間で共通の引き継ぎ形式ではありません。

自動記録と引き継ぎにはai-memoryを使う

エージェントにサービス経由でプロジェクトのコンテキストを記録・取得させたい場合は、ai-memoryを選びます。基準となるデータはGitで管理するMarkdownのWikiで、SQLiteはそこから作る検索インデックスです。MCPがメモリ操作ツールを提供し、セッションのイベントに応じて動くフックが、記録と開始・終了時の処理を担当します。

インストールしてエージェントを接続する

次の例は、macOSでBashを使い、ユーザー単位で新規インストールする場合を対象としています。Gitとコーディングエージェントがインストール済みで、各エージェントの認証も完了していることが前提です。ほかのプラットフォームについては、このリリースのインストールガイドを参照してください。

コマンドは、インストーラーの取得、内容の確認、指定バージョンのインストール、設定計画の表示、設定の適用、状態確認の順です。計画を表示した時点で変更内容を読み、納得してから設定を適用する行に進んでください。

curl -fsSLo /tmp/ai-memory-install-v3.1.2.sh \
  https://github.com/akitaonrails/ai-memory/releases/download/v3.1.2/install.sh
less /tmp/ai-memory-install-v3.1.2.sh
AI_MEMORY_VERSION=3.1.2 sh /tmp/ai-memory-install-v3.1.2.sh
export PATH="$HOME/.local/bin:$PATH"
ai-memory --version
ai-memory setup --plan --agent claude-code --agent codex --agent cursor
ai-memory setup --agent claude-code --agent codex --agent cursor
ai-memory status

想定するバージョンは 3.1.2 です。設定を適用する前に、セットアップの計画を確認してください。バックグラウンドサービスを作成し、ユーザー単位でMCP、フック、スキルの設定を変更するため、選択したエージェントで扱う別のプロジェクトも記録対象になり得ます。

このリリースのCodex設定を生成するコードは、ai-memoryのツールに default_tools_approval_mode = "approve" も設定します。メモリの変更に確認を必須としたい場合は、この権限も見直してください。

このリリースのCodex向けネイティブ登録では、生成されたbearerトークンを起動環境に読み込ませます。macOSの標準データディレクトリを使う場合、次のBashコマンドでトークンを表示せずに設定できます。

AI_MEMORY_AUTH_TOKEN="$(cat "$HOME/Library/Application Support/ai-memory/auth-tokens/default")"
export AI_MEMORY_AUTH_TOKEN
codex

最後の行で、トークンを読み込んだシェルからCodexを起動します。変数を設定したシェルとは別の起動環境を使うときも、その環境からトークンを参照できる必要があります。

登録設定は AI_MEMORY_AUTH_TOKEN を参照します。MCPのインストールガイドには、このCodex固有の要件が説明されています。保存先を変更している場合は、ai-memory status が示す実際のデータディレクトリを使ってください。

Codex内で /hooks を実行し、インストールされたai-memoryのフックを信頼済みに設定します。セットアップ後はClaude CodeとCursorを再起動してください。インストーラーの終了コードだけでは、まだ信頼されていないフックをCodexが実行するとは判断できません。

保存した知識と引き継ぎを別々に確認する

最初の確認では同じ作業コピーを使い、対象のプロジェクトを明示します。ルートで ai-memory project init を実行し、ワークスペースとプロジェクトの名前を確定または選択してください。.ai-memory.toml が作成されるので、どのエージェントでも両方の名前をそろえます。

Claude Codeには次のプロンプトを渡します。

Read .ai-memory.toml and use its workspace and project for ai-memory calls.
Call memory_status.
Use memory_write_page to save decisions/shared-memory-demo.md with:
"Memory trial: before a dependency upgrade, check the official release
notes and run the affected component's tests."
Read the page back with memory_read_page and report its stored path.

プロンプトは設定ファイルのワークスペースとプロジェクトを使い、メモリの状態を確認したうえで、試用の判断をページとして保存し、そのページを読み直すよう求めています。保存先は返された実際のパスで確認し、次のエージェントでも同じプロジェクトを指定します。

同じ作業コピーでCodexまたはCursorを開きます。memory_query で Memory trial を検索し、一致した結果に対して memory_read_page を呼び出すよう依頼してください。成功の条件は、実際のツール結果から保存済みのパスと判断を取得できることです。メモリを取得せずにもっともらしい回答を返すだけでは確認になりません。これらの操作はプログラムからメモリを扱うためのリファレンスに記載されています。

次に、小さな実タスクで自動引き継ぎを確認します。明確な未完了の操作を一つ残して通常の方法でセッションを終了し、同じディレクトリで次のエージェントを開いてください。起動時のコンテキストに、その保留中の操作が含まれることを確認します。永続的なページは後からも検索できますが、引き継ぎ情報は次のセッション向けで、一度だけ受け取れるものです。

取得に失敗したら、ai-memory doctor を実行し、MCPの接続状態とワークスペース・プロジェクトの組み合わせを調べます。Codexの認証エラーなら起動環境を、引き継ぎ情報がなければフックの信頼設定とセッションの記録を確認してください。認証失敗と引き継ぎ失敗は、切り分けて対処してください。

記録を検証し、知見を承認するならBeacon

再利用する知見の根拠まで確認したい場合は、Beaconを選びます。OpenTelemetry、フック、ローカルのセッションファイルからの復元などを組み合わせて記録しますが、取得できる内容はツールによって異なります。セッションを収集しただけで、その内容が承認済みメモリになるわけではありません。

ローカルのコレクターをインストールする

macOSでBashとHomebrewを使う新規インストールでは、この記事で扱う三つのエージェントだけを設定します。

brew update
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon
beacon version
BEACON_ONBOARDING=0 beacon endpoint install \
  --harness claude,codex,cursor --no-backfill
beacon endpoint status

確認日時点で、HomebrewのFormula（パッケージ定義）は 1.3.45 を提供しています。この例は過去のセッションの取り込みと、対話式の初期設定ウィザードを省略します。選択したエージェントの記録設定はユーザー単位に適用されるため、別のリポジトリで行った作業もログに入る可能性があります。

通常のウィザードではBeacon Cloudが事前選択されています。新規インストールでウィザードを省略し、--connect を指定しなければ、Cloudへの登録を避けられます。ただし、既存の接続は解除されません。切断するには beacon endpoint disconnect を使います。保存・転送先の選択肢は初期設定のドキュメントに記載されています。

設定後はエージェントを再起動し、Codexの /hooks でBeaconのフックを確認して信頼済みに設定します。試用するリポジトリで短いセッションを実行し、先ほどの依存関係レビューのルールを明示的に伝えてください。

知見を作成し、承認してから読み出す

知見を作る前に、記録されたセッションを確認します。リポジトリのルートで次を実行してください。

beacon endpoint traces list --limit 10
read -r -p "Trace ID from the trial session: " BEACON_TRACE_ID
beacon endpoint traces show "$BEACON_TRACE_ID" --limit 150

ここで確認するトレースは、試用セッションで実際に集まったイベントです。候補の根拠になるため、依存関係のルールを伝えたセッションを選び、何が記録されているかを読んでから先へ進みます。

一覧に実際に表示されたIDを選び、そのイベントに伝えたルールが含まれることを確認します。その後、メモリ候補を作成します。

beacon memory candidates create \
  --trace "$BEACON_TRACE_ID" \
  --kind convention \
  --title "Dependency upgrades require release-note review" \
  --applicability "Before changing a dependency version in this repository" \
  --body "Check the dependency's official release notes and run the affected component's tests before proposing the upgrade."
read -r -p "Candidate ID returned above: " BEACON_CANDIDATE_ID
beacon memory candidates show "$BEACON_CANDIDATE_ID"

候補には元のトレース、知見の種類、タイトル、適用条件、本文を指定しています。ここでは「このリポジトリで依存関係のバージョンを変える前」という範囲に限定し、リリースノートの確認と該当コンポーネントのテストを実行するルールを保存候補にします。

候補の内容と、根拠となる元の記録をレビューしてください。記述された知見を採用すると判断してから承認します。

beacon memory candidates approve "$BEACON_CANDIDATE_ID" \
  --reason "Reviewed against the source trace"

この方法では候補の本文を自分で指定し、評価器は呼び出しません。Beaconのオプションの評価器は、イベントの記録であるトレースを採点しますが、完成した知見の本文は作成しません。両方の方法はメモリコマンドのリファレンスに記載されています。

続いて、同じリポジトリで動作する別のエージェントに、次のコマンドを実行させます。

beacon memory list -q "dependency upgrades" --json

返されたメモリIDを beacon memory show に渡し、そのルールを適用する条件を説明するよう依頼します。期待する結果は、このプロジェクトに関連付けられた承認済みの知見です。結果が空なら、承認状態、対象プロジェクト、検索語を確認してください。Beaconのローカル検索では、すべての検索語が一致する必要があります。

確認したいのは、別のエージェントが承認済みの内容を取得でき、その内容をどの作業に適用するか説明できることです。単に元のセッションを検索できたことだけで、メモリとしての再利用が確認できたとはしません。

このCLIを使う手順にMCPは不要です。エージェントのツール経由で取得したい場合は、Beaconが別途提供するローカルMCPサーバーから search_memory、get_memory、get_memory_context を利用できます。対象は承認済みのローカルメモリです。Beacon Cloudは別の保存領域を使うため、デバイスを接続しても、この二つのメモリは同期されません。

誤った知見、非公開データ、コストを管理する

適用範囲を絞り、根拠を添えて結論を保存します。読み出した文章は、過去の状況を記録した情報として扱ってください。一度の失敗は、プロジェクトの恒久的なルールではなく、一時的な障害や間違ったブランチでの作業によるものかもしれません。適用条件、元のタスクやコミット、検証結果、レビュー日を記録し、前提となる動作が変わったらメモを修正または廃止します。

承認は作業手順であり、人間が内容を確認した証明ではありません。Beaconの候補を提案するエージェントとは別に、人間がレビューする形にしてください。また、保存した指示が現在の要件や権限を上書きしないようにします。

記録を収集すると、非公開の情報が残る場所も変わります。ai-memoryでは .ai-memory.toml の [capture] ignore_paths により、対応するパスベースのイベントを除外できます。ただし、利用方法のドキュメントは、これがプロンプトや出力全般の情報漏えいを防ぐフィルターではないと明記しています。再利用するメモに認証情報や顧客データを含めないでください。現在のMarkdownページを削除しても、Gitに古い版が残る場合があります。

作業セッションをBeacon Cloudへ転送する前に、現行のプライバシーポリシーを確認します。2026-10-21時点では、研究とモデル学習への利用が標準で有効になっており、オプトアウトできます。メタデータだけを転送する設定でも、パスやコマンドラインなどの情報は含まれます。保存先がローカルでも、利用するクラウドモデルまでローカルになるわけではありません。そのモデルのコンテキストに読み出した情報は、モデルへの入力になります。

費用は作業全体で見積もってください。ai-memoryの標準的なメモリ処理には生成モデルのAPIキーは不要ですが、標準のローカル埋め込みモデルが初回起動時にダウンロードされる場合があります。Beaconで知見の本文を自分で指定する方法なら、評価器の呼び出しを避けられます。

それでも、コーディングエージェントの通常の利用、読み出したメモリによる追加入力、オプションのクラウド処理、ストレージ、レビュー時間は費用に関わります。どちらも、アーキテクチャだけで総コストが下がると証明できるものではありません。

全プロジェクトにメモリ層を導入する前に、実際のタスクで一度ツールを切り替えてください。正しい判断を読み出し、未完了の操作を特定し、その根拠を確認したうえで、現在の作業コピーに沿って続行します。うまくいかなければ、さらにメモリを蓄積する前に、読み込み、対象範囲、記録の収集を修正してください。