codex-memory-curator

Codex Memory Curator

目標

Codex のメモリをユーザーが所有する永続的な状態として監査し、古くなった主張、安全でない主張、重複した主張、または配置場所が適切でない主張を分類して、レビュー、計画、保存、クリーンアップへ振り分けます。Cursor から呼び出された場合でも、調査対象は Codex のメモリと設定に限り、Cursor の状態は調べません。

基本原則

メモリはコンテキストであり、真実ではありません。最新のユーザーリクエスト、現在のリポジトリファイル、AGENTS.md、パッケージファイル、ADR、実際に確認できる最新の証拠は、保存されたメモリより優先されます。

使用する場面

• Codex のメモリと、その永続的な設定のレビュー、配置、設定、計画、またはクリーンアップに使用します。
• メモリが古くなっている、矛盾している、機密情報を含んでいる、ノイズが多い、複数のリポジトリにまたがっている、または動作を劣化させている場合に使用します。

使用しない場面

• 通常のドキュメント、一般的なプロンプト作成、または Cursor の状態には使用しません。ただし、Codex のメモリや設定が明示的に関係する場合を除きます。
• レビューの依頼は読み取り専用のままにし、Codex のメモリと設定、および矛盾を確認するために必要最小限のリポジトリ情報以外の個人ファイルは調べません。

ワークフローの選択

次の 8 つのワークフローを、安定した順序で簡潔に提示します。意図が明確な場合は簡潔に提示してください。依頼された結果と成果物に合うルートを推奨し、単独で呼び出された場合は review-chat を推奨しながら、ユーザーに選択を求めます。

ワークフロー	成果物と結果
plan-run-cleanup-file	1 件の記録：レビュー、承認済み計画、バックアップ、クリーンアップ、検証。
review-chat	チャット：読み取り専用のレビューと推奨事項。
review-file	1 件の記録：読み取り専用のレビューと推奨事項。
cleanup-chat	チャットとバックアップ：レビュー、確度の高いアトミックなクリーンアップ、検証。
cleanup-file	1 件の記録とバックアップ：レビュー、確度の高いアトミックなクリーンアップ、検証。
plan-cleanup-chat	チャット：レビューと承認済み計画。クリーンアップは行いません。
plan-cleanup-file	1 件の記録：レビューと承認済み計画。クリーンアップは行いません。
plan-run-cleanup-chat	チャットとバックアップ：レビュー、承認済み計画、クリーンアップ、検証。

auto ワークフローを追加せず、意図に基づいて振り分けます。

• 直接的なレビュー依頼では、既定で review-chat を選択します。保存が明示されている場合は review-file を選択します。
• 明示的なクリーンアップ依頼で成果物の希望が示されていない場合は、plan-run-cleanup-file を選択します。
• 成果物と実行の意図が明確な場合は、明確な直接依頼に応じて、他の適切なルートを選択できます。
• エージェントが開始する場合は、関連する読み取り専用のルートのみを選択できます。既存のタスクで保存がすでに依頼されている場合に限り、review-file を使用します。クリーンアップを推測してはなりません。
• 単独での呼び出し、手がかりの矛盾、またはレビューとクリーンアップ、チャットとファイル、実行、Codex のホーム、変更権限のいずれかが曖昧な場合は、表を提示してユーザーに選択を求めます。
• 変更を伴うルートを選択できるのは、ユーザーが対象の Codex メモリのクリーンアップをすでに依頼している場合のみです。

詳細な調査を始める前に、選択可能なすべての選択肢を一度提示し、Selected、Reason、Codex のホーム／リポジトリの対象、書き込み範囲、想定される成果物、保護対象の状態、Plan モードの利用可否、未解決の承認事項を明示します。タスク内ですでに確定している事実と正確な権限を再利用し、判明している項目を簡潔な案内にまとめます。選択が明確であれば、その旨を伝えて作業を続行します。曖昧であれば、一覧確認の前に停止し、未解決の選択肢だけを尋ねます。同じ選択肢を再提示したり、変更のない選択について再度尋ねたりしてはなりません。

ワークフローの選択によって、ファイル全体の削除、破壊的な復旧、設定変更、有料または外部の操作、デプロイ、公開、範囲の拡大が許可されるわけではありません。

調査する入力

• ユーザーが指定した Codex ホーム、または ${CODEX_HOME:-$HOME/.codex} を特定し、要求された memories の対象を調査します。設定が要求されている場合、または対象範囲内の競合を解決するために必要な場合に限り、config.toml を調査します。
• 争点となっている主張を検証する必要がある場合に限り、現在のリポジトリの証拠を調査します。
• 以下の分類、競合、設定モード、ストア構造、安全な編集に関するリファレンスは、それらに関する判断が必要な場合に限り読み込みます。レポートまたは計画の成果物を作成する場合は、該当するアセットを読み込みます。

安全ルール

• 経路が確定していない場合は調査しないでください。また、選択された経路とユーザーの依頼によって、対象範囲が明確に指定されたクリーンアップが許可されていない限り、変更を加えないでください。
• メモリファイルを、通知なしに削除、書き換え、切り詰め、移動しないでください。
• 承認された編集の前に、対象となる各ファイルのバックアップを作成し、バックアップのパスを報告してください。
• シークレット、トークン、認証情報、顧客データ、個人を特定できる情報、機微な個人情報を全文表示しないでください。
• シークレットらしきデータが見つかった場合は、出力では値をマスキングし、可能であればファイルと行を示して、削除と、実際の認証情報であればローテーションを推奨してください。
• メモリのスキーマが不明確な場合は、直接編集しないでください。現在の記録またはチャットの結果に保留事項として記載してください。
• ローカルの指示で証明されていない限り、メモリファイルは生成された状態として扱ってください。古くなった整理済みの主張を修正するために、追記専用の証拠を書き換えないでください。
• リポジトリ固有の前提を全体に適用しないでください。リポジトリのルールには、AGENTS.md またはリポジトリのドキュメントを優先してください。
• 広範囲に破壊的なコマンドを実行しないでください。

ワークフロー

すべてのルートで、計画やクリーンアップの前に、明示的に指定された範囲へ同じレビュー品質を適用します。1つのファイルや主張についての依頼は、ストア全体を調査する許可を意味しません。ストア全体を対象とするインベントリ作成／スキャナーコマンドではなく、対象を絞った読み取りを使用し、範囲内の矛盾を解決する場合に限り、ほかの証拠を参照してください。納品方法によってレビュー品質が低下することはありません。

1. 選択されたルート、Codex のホーム、リポジトリの対象、該当する場合は永続化パス、保護された状態を特定します。Codex のホームは次のように特定します。

   ${CODEX_HOME} が設定されている場合はそれを使用し、設定されていない場合はユーザーのホームディレクトリに .codex を加えたパスを使用します。

2. メモリストア全体を明示的に対象とする依頼では、内容を出力せずにすべてのメモリファイルを一覧表示します。

   node scripts/inventory-memories.mjs
   

   より狭い範囲の依頼では、このストア全体を対象とするコマンドは省略し、対象を絞った読み取りで、明示的に指定されたパスのみを一覧表示します。

3. ストア全体を対象とする依頼で、機密性の高い項目、古い項目、範囲が広すぎる項目、ローカル項目、リポジトリ固有の項目、または設定に関する項目を探す場合は、リスクスキャナーを実行し、結果を秘匿化します。

   node scripts/scan-memory-risks.mjs --json
   

   1つのファイルまたは主張のレビューでは、依頼された範囲を対象とした読み取りを使用します。ファイルを選択する機能がないため、このストア全体を対象とするスキャナーは実行しないでください。終了コード 1 は検出項目が見つかったことを示し、スキャンの失敗を意味するものではありません。スキャナーは返される検出項目数に上限を設け、デフォルトでは生成された証拠を除外します。必要な場合に限り、--max-findings の値を増やすか、--include-generated-evidence を追加してください。 スキャナーの JSON を証拠として使用し、ペイロード全体を貼り付けるのではなく、件数と、秘匿化された中で最も重要度の高い検出項目を報告します。

4. 設定が依頼されている場合、または範囲内の矛盾を解決するために必要な場合は、node scripts/locate-memory-config.mjs --json を使って <codex-home>/config.toml 全体からメモリ／設定のシグナルを探します。ロケーターは行番号と固定のシグナル名を出力し、値は出力しません。テーブル／プロファイルのコンテキストも含め、関連する限定された範囲だけを確認し、機密性の高い値は秘匿化します。候補の一致は、TOML の解析結果でも、有効な設定の証明でもありません。

5. メモリモードを、無効、有効だが注入されていない、有効かつ注入済み、外部コンテキスト生成が無効、不明のいずれかに分類します。正確なモードのシグナルについては、references/config-modes.md を読み込みます。

6. 複数のメモリファイル形式が存在する場合は、安全に編集できる内容を判断する前に、references/memory-store-anatomy.md を読み込みます。

7. メモリファイルは小さなチャンク単位で読み取り、大量の内容を一度に出力しないようにし、機密性の高い値は秘匿化します。

8. 原子的な主張を1行に1つずつ抽出します。分類の前に、複合的な項目を分割します。

9. 矛盾を確認する際は、異議のある主張に必要な現在のリポジトリファイルのみを確認します。優先順位が不明確な場合は、references/conflict-resolution.md を読み込みます。

10. 原子的な主張ごとに、主分類を必ず1つ割り当てます。分類は KEEP、KEEP BUT REWRITE、MOVE TO AGENTS.md、MOVE TO REPO DOCS、MOVE TO SKILL、MOVE TO CONFIG、DELETE、ASK USER のいずれかです。

11. リスクの高い項目には、有用なコンテキストとしてのみ次のタグを付けます。stale、duplicated、too-broad、too-specific、repo-specific、workflow、config、sensitive、conflicting、useful。

12. すべての項目に信頼度（high、medium、low のいずれか）と、提案するアクションを付けます。

13. 計画や編集の前に、レビューを最後まで完了します。ルートの納品方法によってレビュー品質を低下させたり、依頼された範囲を拡大したりしてはいけません。

ルートの実行

• review-chat：レビュー結果をチャットで返し、永続的なキュレーションレポートは作成しません。
• review-file：単一のキュレーション記録を永続化し、メモリや設定は変更しません。
• cleanup-chat：完了したレビューから確信度の高い個別のアクションのみを導き出し、変更対象となる各ファイルの正確なバックアップを作成してから適用し、変更したセクションを再読み込みして、検証結果をチャットで報告します。永続的なキュレーションレポートは作成しません。
• cleanup-file：変更前にキュレーション記録を作成し、永続化に失敗した場合は停止します。その後、対象ファイルの正確なバックアップを作成し、確信度の高い個別のアクションのみを適用して、実行結果と検証結果を同じ記録に記載します。
• plan-cleanup-chat と plan-cleanup-file：Plan ライフサイクルに入り、ユーザーとクリーンアップ計画を確定した後、承認を得た時点で停止します。Codex の状態は変更しません。
• plan-run-cleanup-chat と plan-run-cleanup-file：Plan ライフサイクルに入り、クリーンアップ計画全体を確定して承認を得ます。状態を再確認して Plan モードを終了し、対象ファイルの正確なバックアップを作成してから、変更されていない計画のみを実行し、検証します。計画承認後に、一般的なクリーンアップについて再度質問してはいけません。

直接クリーンアップ（cleanup-chat または cleanup-file）で許可されるのは、既存の編集可能なランタイム所有の Codex メモリに対する、確信度の高い個別の編集、移動、またはエントリ削除に限られます。ファイル全体の削除、新しいコンテキストファイル、設定、AGENTS.md、リポジトリのドキュメント、スキル、追記専用の生成証跡、不確かなスキーマ、確信度が中または低い変更、範囲の拡大は対象外とします。plan-run ルートでは、承認済みの計画に各変更先、書き込みパス、バックアップ、ロールバック、個別の承認境界が明記されている場合に限り、より広範なキュレーション変更を実行できます。

Plan ライフサイクル

どのルートでも、ネイティブの Plan モードが有効または要求されているか、および実際の書き込み権限を確認してください。Plan モードが有効な場合、または権限が不明な場合は、レポート、バックアップ、クリーンアップの書き込みを行わないでください。手動でモードを切り替えなくても、読み取り専用で計画を続行できます。plan-* ルート、または重要な質問が未解決の場合は、references/plan-lifecycle.md を読み込んでください。変更のない承認は再利用できます。モードを終了しただけでは承認とみなされず、未回答の質問によって権限が与えられることもありません。書き込み前に状態を再確認し、重要な変更がある場合にのみ再確認してください。Plan のみのルートでは、クリーンアップは許可されません。

このキュレーションワークフロー内で codex-spec-interviewer を呼び出さないでください。調査結果から、より広範で永続的なルール、リポジトリの仕様、または未解決の製品上の決定が必要になった場合は、選択されたキュレーションルートを完了してから、別のフォローアップとしてインタビュアーの利用を提案してください。

ファイル納品の契約

ファイルルートでは、編集済みのキュレーション記録を正確に 1 件だけ永続化します。既存のリポジトリ標準のレポート保存先を優先してください。該当する場所がない場合は、<repo>/.agent-reports/codex-memory-curation/<UTC timestamp>-<selection-id>.md を使用します。新しいパスを作成し、上書きせず、ルートの出力はすべてその記録に含めてください。

記録には Review、Plan、Execution Receipt、Deferred Work、Backup、Verification を含めます。実施しないフェーズには、その理由を添えて not applicable と記載してください。cleanup-file と plan-run-cleanup-file では、変更前に記録を作成します。永続化に失敗した場合、クリーンアップは実行できません。チャットルートではレポートファイルを作成しません。バックアップディレクトリは安全確保に必須の成果物であり、キュレーションレポートには数えません。

--backup-root を明示する場合は、機密情報を含まない安定した --backup-root-alias も必須です。ファイルルートでは、スクリプトが報告したポータブルな保存先ロケーターと <storage-locator>/backup-manifest.json を永続化します。正確な絶対パスであるバックアップ先とマニフェストのパスは、永続化されないチャットにのみ報告し、リポジトリ内の成果物には記載しないでください。

分類チェック

個々の主張ごとに、安定性、適用範囲、可搬性、強さ、重複、古さ、機密性、優先順位が上位の規則との衝突、簡潔な表現、そして AGENTS.md、リポジトリのドキュメント、スキル、設定、削除のほうがより適切かどうかを確認してください。詳細な規則と例については、references/classification-rubric.md を読み込んでください。

参考資料

必要な場合にのみ読みます。

• 分類と競合：references/classification-rubric.md、references/conflict-resolution.md。
• 設定とストアの境界：references/config-modes.md、references/memory-store-anatomy.md。
• 安全な変更と例：references/safe-editing-procedure.md、references/example-review-report.md。
• 出力成果物：assets/review-report-template.md、assets/cleanup-plan-template.md。

スクリプト

必要な場合にのみ使用します。すべてのスクリプトは非対話型で、Node.js の標準ライブラリのみを使用し、--help を受け付けます。

node scripts/inventory-memories.mjs [--codex-home PATH] [--json]
node scripts/locate-memory-config.mjs [--codex-home PATH] [--json]
node scripts/scan-memory-risks.mjs [--codex-home PATH] [--json] [--max-findings N] [--include-generated-evidence]
node scripts/backup-memories.mjs [--repo PATH] [--codex-home PATH] [--backup-root PATH --backup-root-alias NAME] [--include PATH ...]

• 設定ロケーターは読み取り専用で、後半の表やドット付き／引用符付きキーも含め、ドキュメント全体をスキャンします。これは検出を補助するツールです。コメントや文字列も一致することがあるため、モードを分類する前に TOML のスコープ、有効なプロファイル、オーバーライドを確認してください。
• インベントリ作成は読み取り専用です。スキャナーは読み取り専用で、デフォルトで値を秘匿し、検出結果に上限を設け、明示的に要求されない限り生成された証跡をスキップします。また、実行失敗ではなく検出があった場合に終了コード 1 を返します。
• backup-memories.mjs は、ソースを編集せずに、上書きしないバックアップと backup-manifest.json を作成します。秘匿されていないバックアップの内容とマニフェストは、物理的な別名も含め、Git 作業ツリーの外部かつ解決済みの Codex メモリーツリーの外部に保管してください。事前チェックでは安全でないルートとシンボリックリンクのすべてのパス要素を拒否し、トラバーサルエラーが発生した場合はルートの作成前に処理を失敗させます。編集には正確な --include パスを使用してください。include がゼロの場合は、従来の検出方法が維持されます。実行前に references/safe-editing-procedure.md を読み、ルートの安全性、事前チェック、マニフェストとの照合、復旧を確認してください。

出力形式

上記のワークフロー告知を使用します。そこで報告するのは、未解決の承認ゲートのみです。選択したルートの結果では、以下のルート実行契約とファイル納品契約に従って、必要な成果物と検証結果を報告してください。

レポートを作成する前に、assets/review-report-template.md を読み込み、正規の見出しおよびフィールドの契約として従ってください。ファイルを作成するルートでは、このテンプレート全体を1件のキュレーション記録にコピーします。チャットルートでは、該当するセクションのみをチャットに表示し、レポートファイルは作成しません。該当するすべてのフィールドに入力し、フェーズを省略した場合は理由とともに not applicable と記載して、機微な値を秘匿してください。

編集前に、レビュー表と判断表を完成させてください。編集後は、同じ記録の受領内容を完成させてください。これには、マニフェストとの照合と未照合のパス、新しいパス（created-no-preimage）とロールバック、バックアップモードとマニフェストのパス、バックアップの整合性検証結果、および行スキーマ | Changed path | Backup destination | Bytes | SHA-256 | Verification | が含まれます。

完了条件

• 8つの正規ワークフローのうち1つが、明確な権限または解消済みの曖昧さに基づいて選択されていること。エージェントの有効化からクリーンアップを推測していないこと。
• 該当するメモリー／設定がインベントリ化されているか、見つからない旨が報告されていること。生成された証跡に変更を加えるのは、機微情報のクリーンアップが明示的に許可されている場合のみであること。
• すべての原子的な主張に、分類、リスクタグ、確信度、アクションが1つずつ割り当てられ、該当する場合は優先順位がより高い競合証拠が示されていること。
• 計画／直接クリーンアップと保存先の境界が守られていること。
• 納品物が正規テンプレートに準拠していること。すべての編集に対して、正確なバックアップ、マニフェストとの照合、再読み込み、整合性の証明があること。

失敗要因

• メモリー／設定が見つからない場合：利用できない内容と、有効化、アプリのデフォルト設定、または別の Codex ホームが原因として考えられるかどうかを報告します。
• スキーマが不明な場合：編集したり、同階層の状態を作成したりせず、保留します。
• 機微な内容や競合する内容がある場合：値を秘匿し、場所と優先順位がより高い情報源を示し、削除／ローテーションを推奨するか、書き換え、移動、削除のいずれかに分類します。
• 永続化、バックアップ、または承認済み状態の再確認に失敗した場合：変更前（または追加変更の前）に停止し、失敗を報告して、ドリフト発生後の計画に戻ります。