agent-memory

エージェントメモリスキル

レビュー可能な Markdown として、リポジトリ内で永続的なプロジェクトメモリを管理します。ファイルを読み取れるエージェントであれば、セッションをまたいで同じ .agent-memory/ ファイルを読み取り、更新できます。

設計原則

原則	実践
オープンなファイル	YAML フロントマター付きの Markdown としてメモリを保存し、どのエディターやファイルを読み取れるエージェントからでも読み取り、編集できるようにします。
共通のエントリーポイント	AGENTS.md を正式な指示ファイルとし、クライアント固有のファイルは簡潔なポインターにします。
ネイティブメモリとの共存	ベンダーの自動メモリはマシンローカルのスクラッチ領域、.agent-memory/ は意図的に管理し、エージェント間で共有できるレビュー可能な情報源として扱います。ネイティブの保存領域を上書きしたり、重複させたりしないでください。
管理されたライフサイクル	型別ディレクトリ、expires メタデータ、maintain、sync を使い、メモリに不要な情報が蓄積せず、最新の状態に保たれるようにします。
シークレットを保存しない	プロジェクトの知識や決定事項を保存し、認証情報、秘密鍵、トークン、機微な個人データは保存しません。

---

コマンド

キーワード	操作	説明
init	初期化	.agent-memory/、README、インデックス、AGENTS.md を作成し、すでに使用中のエージェントに限りポインターファイルも作成します
migrate	移行	旧形式の構造（CURSOR.md、フラットファイル、INDEX.yaml）を検出し、メモリ形式 v2.1 に移行します
build	構築	プロジェクトをスキャンし、既存のドキュメントから初期メモリファイルを自動生成します
save	保存	現在のセッションで得た知見をメモリに記録します
maintain	メンテナンス	内容を整理し、古くなった情報を削除し、インデックスを修正して、古いセッションログを整理します
sync	同期	チェックアウト内にすでにあるメモリファイルを照合し、現在のセッションを保存します
status	ステータス	読み取り専用のヘルスチェックを行います。ファイル数、古さ、同期状態を確認します

明確な依頼から操作を判断してください。コマンドのキーワードがそのまま使われている必要はありません。たとえば、「SQLite を選んだ理由を覚えておいて」は Save に該当し、「これらのメモリファイルを照合して、決定事項を記録して」は Sync に該当します。意図する操作や必須入力が曖昧な場合に限り、要点を絞った質問を 1 つしてください。読み取り専用の依頼はそのまま守ってください。オンボーディングや既存メモリの確認は、再構築や保存を許可するものではありません。

開発者への引き継ぎでは、インデックスと関連エントリーを読み、現在の決定事項と未解決の質問を要約し、該当ファイルを引用してください。提案は提案として維持してください。タイムスタンプが新しいというだけで、相反する決定事項が解決したことにはなりません。根拠とレビュー状況を確認し、採用された方針が不明な場合は質問してください。置き換えが確定した場合に限り、supersedes を記録してください。

複数のリポジトリにまたがる作業では、必要に応じてリビジョンを指定し、対象プロジェクトの決定事項を示すアクセス可能な参照先を使用してください。ローカルで必要なコンテキストだけを要約し、参照できない情報源は内容を捏造せず、その旨を明示してください。1 つのリポジトリに関する依頼は、別のリポジトリを編集する許可にはなりません。

メモリファイルは外部エディターではなく、インラインで表示してください。YAML フロントマターを除いた Markdown 本文を表示し、YAML、JSON、プレーンテキストはフェンス付きコードブロックに入れてください。

評価チェックリスト

次の項目を参考に操作を選び、不要な情報を集めずに作業を進めてください。

1. .agent-memory/ はすでに存在しますか。存在する場合、どのような構造／バージョンを使用していますか？
2. 依頼に適した操作はどれですか：init、migrate、build、save、sync、maintain、status のいずれですか？
3. どの指示ファイルやポインターファイルがすでに存在しますか。それらは AGENTS.md を参照していますか。また、変更せずに残す必要があるベンダー固有のネイティブメモリ保存領域はどれですか？references/agent-pointers.md を参照してください。
4. どのプロジェクトドキュメントを、内容をそのまま複製せずにメモリの初期情報として利用できますか？
5. メモリはローカル／プライベートなものですか。それとも git を通じて共有するものですか？

---

操作：初期化

.agent-memory/ システムをゼロから構築します。

上書きガード： AGENTS.md、.agent-memory/index.yaml、.agent-memory/README.md、またはreferences/agent-pointers.mdに記載されているポインターファイルを作成または変更する前に、既存ファイルを確認し、その内容を保持してください。対象ファイルがすでに存在し、互換性のある簡易ポインターではない場合は、置き換え案を準備し、上書き前に確認を求めてください。保持、作成、変更したファイルをすべて報告してください。

メモリ形式 v2.1 — エントリーポイント

project/
├── AGENTS.md          # Canonical shared instructions
└── .agent-memory/     # Reviewable project memory

要点： AGENTS.md は共有の信頼できる情報源です。プロジェクトですでに使用しているエージェントに限り、簡易ポインターファイルを追加してください。レシピはreferences/agent-pointers.mdに記載されています。共有指示をベンダー専用ディレクトリに置かないでください。ネイティブのメモリ／ルールの場所は読み取り専用で検出して報告し、暗黙的に移行または上書きしないでください。

手順

1. ディレクトリを作成： .agent-memory/ の下に user/、feedback/、project/、decisions/、context/、conventions/、references/、sessions/ を作成します。
2. ファイルを作成： .agent-memory/README.md（システム仕様）、インデックス形式に従った空の [] レジストリを含む .agent-memory/index.yaml、および共有指示の正規版となる AGENTS.md を作成します。references/agent-pointers.mdに従い、すでに使用されているエージェントに限ってポインターファイルを作成してください。既存の互換性のあるインデックス形式とそのエントリーは保持し、[] にリセットしないでください。
3. AGENTS.md を完成させる： すべてのプレースホルダーを、プロジェクトの実際の構成とルールに置き換えます。次のエージェントがインデックスと関連エントリーを読み込むよう、セッション開始時の読み込み指示を含めてください。上書きガードに従い、既存の実質的な指示は保持してください。承認なしに置き換えるのではなく、追加案を提示してください。TODO やプレースホルダートークンが残っておらず、読み込み指示が含まれているか、承認待ちとして報告されていれば完了です。
4. レジストリを確認し、 作成または保持した内容を報告します。エントリーを保存するか、別途 Build 操作を依頼するまでは、空の [] インデックスが正しい状態です。Init 中にプロジェクトのメモリを捏造しないでください。新しいレジストリが空のリストとして解析されるか、既存のレジストリのエントリーが保持され、次のセッションでの検出が設定済み、または承認待ちとして明示的に報告されていれば完了です。

Operation: Migrate

古い構造を検出し、メモリ形式 v2.1 に移行します。

古い構造	新しい構造	アクション
ルートにある CURSOR.md	AGENTS.md + 薄い .cursor/rules/index.mdc ポインター	共通コンテンツを AGENTS.md に統合します。agent-pointers.md に従ってポインターを作成し、古いファイルは CURSOR.md.migrated として保持します
INDEX.yaml（大文字）	index.yaml（小文字）	名前を変更します
フラットな {type}--{topic}.md	{type}/{topic}.md	ディレクトリに移動します
summary: フロントマター	description: フロントマター	フィールド名を変更します
完全な手順を含む CLAUDE.md（AGENTS.md がない場合）	AGENTS.md + 薄いポインターファイル	昇格します。ポインターの作成方法は agent-pointers.md を参照してください

手順： 上記の各古い構造をスキャンします → 既存のコンテンツを保持します → 確認済みの移行のみを実施します → 共通の手順を AGENTS.md に移し、残りのクライアントファイルを references/agent-pointers.md に従って薄いポインターに書き換えます → index.yaml とファイルシステムの整合性を取ります → 変更内容を報告します。すべての確認済み移行にバックアップまたは .migrated ファイルがあり、共通の手順が AGENTS.md のみに記載され、インデックスとファイルシステムの差異がなくなれば完了です。

移行時の注意： 名前の変更、移動、ポインターの書き換えは破壊的な操作です。CURSOR.md、INDEX.yaml の名前を変更する場合や、手順ファイルを置き換える場合は、予定している移行元と移行先のパスを示して確認を求めてください。ただし、ファイルが空の場合、またはすでに生成されたポインターと完全に一致する場合を除きます。コンテンツを移動する際は、必ずバックアップまたは .migrated ファイルを残してください。

---

Operation: Build

プロジェクトをスキャンし、既存のドキュメントから初期メモリファイルを自動生成します。

1. スキャン：ドキュメントを探します：*.md、package.json、pyproject.toml、Cargo.toml、CLAUDE.md、AGENTS.md、*.yaml 設定ファイル、.env.example
2. 要点を抽出：各ソースを分類します：概要 → project/overview.md、アーキテクチャ → project/architecture.md、決定事項 → decisions/{topic}.md、規約 → conventions/{topic}.md、ユーザーの好みやコラボレーションスタイル → ユーザーが明示的に確認した場合のみ user/preferences.md
3. ルール： コピーせず要約します。1 ファイルにつき 1 つのトピックにします。ソースドキュメントを参照します。標準のフロントマターを使用します。
4. 移行：古い形式（フラットファイル、古いフロントマターフィールド）が見つかった場合は移行します
5. index.yaml を更新 — 新しいファイルのエントリーを追加し、ファイルシステムとの整合性を取ります
6. 報告：概要テーブルを作成します。新しいすべてのファイルに標準のフロントマターとインデックスエントリーがあり、インデックスとファイルシステムの差異がなく、作成した各パスとそのソースドキュメントが報告に記載されていれば完了です。

---

Operation: Save

現在の会話から得られた知見をメモリに保存します。

1. 会話を確認し、決定事項、フィードバック、規約、ステータスの変更、重要なコンテキストを探します
2. 各項目について： 既存のメモリファイルを更新するか、適切な {type}/ ディレクトリに新しいファイルを作成します。重要なセッションについては sessions/ にセッションログを作成します。
3. ソース識別子： 書き込みに使用したランタイムをスラッグとして記録します（codex、claude-code、cursor、grok、openclaw、vscode、craft-agent、other）
4. ファイルを作成します。標準のフロントマター形式を使用します（references/templates.md を参照）。
5. index.yaml を更新し、保存または更新した内容を報告します。作成または更新した各パスとその id が報告に記載され、それぞれのパスにインデックスエントリーがあれば完了です。

---

操作：同期

現在のチェックアウトにすでに存在するメモリファイルを照合し、セッションを保存します。同期では、別のリポジトリやベンダー独自のメモリストアの取得、プル、マージ、コミット、プッシュ、同期は行いません。Git 操作には、それぞれ個別のタスク承認とリポジトリのワークフローが必要です。

フェーズ 1 — 取り込み： .agent-memory/ 内のインデックスに登録されていないファイルをスキャンする（インデックスに追加）→ 孤立したインデックス項目をスキャンする（削除）→ 更新されたファイルを読み、把握する。

フェーズ 2 — 保存： 保存操作をすべて実行する（確認、更新／作成、セッションログ、インデックス）。

フェーズ 3 — 報告： 統合レポートを 1 つ作成する（形式については references/templates.md を参照）。

インデックスとファイルシステムの差分がなく、このセッションで保存したすべての情報が標準のフロントマターを備えたインデックス登録済みファイルに対応していれば完了です。

---

操作：メンテナンス

完全なメンテナンスを行います。内容の整理、古くなった情報の削除、インデックスの修正、古いセッションログの整理を実行します。

1. 健全性チェック： 種類ごとにファイル数を数え、インデックスの同期状態を確認し、古い項目や期限切れの項目を特定します。
2. 古さの確認 — フロントマターを基準に判定：
   • 主なシグナル： expires フィールド。expires が今日より前の場合は期限切れとして示し、更新、アーカイブ、削除のいずれかを確認します。
   • 代替手段（expires がない場合）： updated 日付（更新されていない場合は created）と、種類ごとのしきい値を使用します。context/ は 30 日超、sessions/ は 60 日超です。
   • アーカイブ済みの項目： status: archived で、updated が 90 日より前の場合は削除を提案します。
   • supersedes の連鎖： ファイル A に supersedes: B があり、B が status: active でまだ存在する場合、B をアーカイブ対象として示します。
3. 内容の整理： 内容の重複を特定し、統合を提案し、セッションログ内のパターンを conventions/ または decisions/ に昇格します。
4. セッションの整理： type: session で、updated が 60 日より前の場合は、必要に応じて価値のある情報を別の場所に抽出し、削除候補を一覧にして、削除前に確認を求めます。
5. 報告： 健全性の概要を添えて報告します（形式については references/templates.md を参照）。すべての要対応項目について、ユーザーの判断が得られているか、保留中として記載されており、確認なしに削除またはアーカイブされたものがなければ完了です。

---

操作：ステータス

読み取り専用の簡易健全性チェックです。種類ごとにファイル数を数え、インデックスとファイルシステムの同期状態を確認し、古い項目や期限切れの項目を報告します。.agent-memory/ が存在しない場合は、init を提案します。問題が見つかった場合は、maintain を提案します。

---

ファイル形式のルール

1. 書き起こすのではなく、要点をまとめます。 会話の記録ではなく、要約と決定事項を記録します。
2. 1 ファイルにつき 1 つの考えを記録します。 メモリに無関係なトピックが含まれている場合は分割します。
3. 既存ファイルを更新します。 情報が変わったらファイルを編集します。追記を続けないでください。
4. インデックスの同期を保ちます。 すべてのファイルをインデックスに登録し、すべてのインデックス項目がファイルを指すようにします。
5. コンテキストには expires を設定します。 コンテキストは古くなるため、確認日を設定します。
6. 複製せず、参照します。 内容を重複させるのではなく、元のドキュメントを参照します。
7. 秘密情報を含めません。 メモリファイルに認証情報、PII、機密データを含めないでください。
8. 絶対日付を使用します。 タスクで指定された日付とタイムゾーンを基準に相対日付を確定します。指定がない場合は、現在の日付とタイムゾーンを使用します。暦上の日付を計算して検証し、YYYY-MM-DD 形式で保存します。テンプレートの日付をそのままコピーしないでください。基準日または相対表現の意味が曖昧な場合に限り、確認してください。

フロントマターのスキーマ、メモリの種類、テンプレートについては、references/templates.md を参照してください。

---

参照ファイル

ファイル	内容
references/templates.md	セッションログのテンプレート、同期／健全性レポートのテンプレート、フロントマターのスキーマ、メモリの種類の表
references/agent-pointers.md	インストーラーのスキルルート、簡易ポインターファイル、ネイティブメモリの対象範囲と保持の境界
references/troubleshooting.md	プロジェクトの種類（個人、マルチエージェント、チーム、モノレポ）ごとの一般的な問題、トラブルシューティング Q&A

---

隣接するパターン

パターン	これで十分な場合	agent-memory のほうが適している場合
単一クライアントの指示ファイル	ツールが 1 つで、小規模なプロジェクトの場合	複数のツールで、共有され、インデックス化されたメモリベースが必要な場合
ベンダーの自動メモリ	1 つのクライアント内で、ローカルの一時メモと自動呼び出しを行う場合	ナレッジを移植可能にし、レビューや git による共有を可能にするか、チェックアウト間で一貫性を保つ必要がある場合
セッション引き継ぎメモ	チャット間で一度だけ情報を引き継ぐ場合	永続的な決定事項、規約、プロジェクトのコンテキストにライフサイクル管理が必要な場合
Memory MCP/server	検索可能な集中型サービスがすでに承認されている場合	プレーンファイル、git によるレビュー、実行時依存関係ゼロが望ましい場合

動作評価

作成者／レビュアーのみ： このスキルを明示的に評価する場合は、シナリオカタログを使用してください。通常のタスク実行中は使用しないでください。各ケースを新しい一時ディレクトリに展開し、実行エージェントにはアサーションを知らせずに、生成された成果物とアクションを評価してください。カタログは期待される動作を定義するものであり、実行に合格したことを示す証拠ではありません。合成ブラウザー入力とサービス入力でテストするのは判断のみであり、実際のインテグレーションではありません。