extract-learnings

Value Context

自然なタイミングで、会話に織り込んでください。結果が出た後、関連するコンテキストがあるとき、または初めて使うときなどです。1回の実行につき1つか2つにとどめ、すべてを一度に伝えないでください。

• ほとんどのユーザーは「これを覚えておいて」と言うと、単一のメモを期待します。このスキルでは実際には2つのエージェント（監査役＋発見役）が並行して動作し、新しい知識を記録すると同時に、既存の記憶が古くなっていないかを確認します。
• 5層の記憶階層により、適切な知識が適切なタイミングで読み込まれます。L0には共通の設定、L1にはプロジェクトのアーキテクチャ、L2には作業メモを配置し、すべてのセッションにすべての情報が読み込まれるのを防ぎます。
• 統合（「dream」）はメンテナンスモードです。古くなった記憶や価値の低い記憶を整理し、重複をまとめ、あふれたセクションを分類して、常時読み込まれるインデックスを小さく保ちます。
• チームの場合：ここで記録した記憶は、このプロジェクトの今後のすべてのセッションに引き継がれるため、オンボーディングやコンテキストの切り替えが大幅に速くなります。

Memory Hierarchy

レイヤー	ファイル	読み込みタイミング	目的
0	~/.claude/CLAUDE.md	すべてのプロジェクトのすべてのセッション	共通の行動設定
1	<repo>/CLAUDE.md	このプロジェクトのすべてのセッション	アーキテクチャ、規約、注意点
2	memory/MEMORY.md（プロジェクトディレクトリ）	すべてのセッション、エージェントが管理	トップインデックス：作業メモとクラスター／トピックへのポインター
2c	memory/clusters/*.md サブインデックス	必要に応じて（セクションがあふれた後）	MEMORY.mdから分割されたセクションのサブインデックス。常時読み込みサイズを上限内に抑えます
3	memory/*.md トピックファイル	必要に応じて	L2に収めるには長すぎる詳細なリファレンス
メタ	新しいスキル／コマンドを提案	該当なし	繰り返し可能なワークフロー → 自動化

配置の判断：プロジェクトに依存しない設定 → L0、プロジェクト固有の技術情報 → L1、簡潔な作業メモ → L2、詳細なリファレンス → L3、繰り返し可能なパターン → メタ。

適応型クラスタリング：セクションが25項目を超えるまではMEMORY.mdをフラットな状態に保ちます。その後、そのセクションのポインターをmemory/clusters/<section>.mdに移し、MEMORY.md内のセクションを、そのファイルへの単一のポインターに置き換えます。毎回のセッションで読み込まれるのはMEMORY.mdだけなので、詳細は必要に応じて読み込める状態を保ちながら、起動時の負荷を抑えられます。

Pointer Format

MEMORY.mdとクラスターの各エントリーはラベルではなく読み込みトリガーです。今後のセッションで、その時点のタスクにポインターが関連すると認識し、ファイルを開く必要があります。ファイル名だけを示すポインターは無視されるため、インデックスが読み込まれても活用されません。形式は次の2種類です。

• トリガー型（デフォルト）：**When <task-condition>:** <one-line takeaway>. → [detail](file.md)。明確な「When」を書ける場合は常に使用します。例：**When compositing a face onto a turned head:** align centers, tight ellipse. → [detail](feedback_composite_align_tight_ellipse.md)。
• 常時適用型：<terse fact>. → [detail](file.md)。固定されたコンテキストや全般的な設定など、該当するすべてのセッションで適用され、条件を付けても不自然になるルールにのみ使用します。

ファイルを開くべきタスクを特定できる場合はトリガー型を選び、タスクにかかわらずルールが適用される場合に限り常時適用型を選びます。クラスターのファイルでは、先頭に短い常時適用ブロックを置き、その後にトリガーインデックスを続けます。それ以外のすべてのエントリーは条件付きポインターです。クラスターにルールの全文をインラインで記述しないでください。クラスターはトピックファイルへ案内し、詳細はそちらに記載します。

Early Exit Guard

ユーザーが、明示的な内容がすでにコンテキストにある状態で「Xを覚えておいて」と言い、かつ統合のトリガー（「consolidate」、「dream」、「extract learnings」、「clean up memories」、または統合のリマインダーによる起動）ではない場合：

1. 記憶のパスを解決します（フェーズ1のステップ1を参照）
2. 既存の記憶を読み込み、重複を確認して適切なレイヤーを選びます
3. サブエージェントは不要なので、その内容を使ってフェーズ3（提案と実行）に進みます

Unified Workflow

フェーズ 1：状況を把握する（メインセッション）

1. Bash を使用してメモリのパスを解決します（Glob は ~ を展開しません）。 Bash: find $HOME/.claude/projects -name MEMORY.md -path "*<repo-dir-name>*" 2>/dev/null | head -1 結果は MEMORY.md（ファイル）の完全なパスです。メモリディレクトリは、その親ディレクトリです：$(dirname <find-result>)。 結果がない場合は、現在の作業ディレクトリのパスで / を - に置き換えてプロジェクトキーを作成し（例：/home/user/myrepo → -home-user-myrepo）、$HOME/.claude/projects/<project-key>/memory/MEMORY.md を使用します。
   • MEMORY.md が存在しない場合は、# Project Memory ヘッダーを付けて作成します。Memory Auditor に監査対象がないことに注意してください。フェーズ 2 では Signal Discoverer のみを起動します。

手順 2～4 は必須で、並列ツール呼び出しとして実行します。

2. MEMORY.md を読み込み、トピックファイルとクラスターファイルを一覧表示します（解決したパスから Glob memory/**/*.md）
3. 両方の CLAUDE.md ファイルを読み込みます（~/.claude/CLAUDE.md と <repo>/CLAUDE.md）。重複排除の品質を確保するために必須です。省略すると、提案が L0/L1 の内容と重複する可能性があります。
4. git log --oneline -20
5. コンテキストスナップショットを作成します：既存の知識を要約し、検証対象（メモリに記載されたファイルパス、関数、パターン）を列挙します。

フェーズ 2：情報を収集する（エージェント 2 つを並列実行）

両方のエージェント呼び出しを 1 つのメッセージで起動し、並列で実行します。Agent ツールを次のように使用します。

• Memory Auditor：subagent_type: "claude-memory:memory-auditor"。prompt に、フェーズ 1 のコンテキストスナップショット（メモリファイルの内容、git log の出力、検証対象の一覧）を含めます。事実関係が古くなった項目だけでなく、廃止や統合の候補（SUPERSEDED / REDUNDANT / LOW-VALUE / MERGE）も提示するよう指示します。統合の目的は、内容を減らす方向に働きかけることです。

• Signal Discoverer：subagent_type: "claude-memory:signal-discoverer"。既存のメモリの要約（重複排除用）とプロジェクト名を prompt に含めます。

フェーズ 1 で MEMORY.md を新規作成したと記録されている場合は、Memory Auditor を省略し、Signal Discoverer のみを起動します。

両方のエージェントで maxTurns ≥ 30 が必要です。plugins/claude-memory/agents/ でエージェントの frontmatter を確認してください。maxTurns が小さいエージェントは早期に終了し、空ではないものの、所見が含まれない出力を返すことがあります。

フェーズ 2 は、両方のエージェントからレポートが返された時点で完了です。どちらかの出力が空、または明らかに不完全（1 行のみで、構造化された所見がない）の場合は、もう一方の結果を使用します。ただし、Signal Discoverer が失敗した場合は、手動のフォールバックも実行します。Bash(python3 -c "import sqlite3; ...") を使って ~/.claude-memory/conversations.db から直近 5 件のセッション要約を直接取得し、以下の Content Quality Rules セクションにあるシグナル基準を適用してください。

フェーズ 3：統合して提案する（メインセッション）

1. エージェントの報告を受け取る
2. 報告間、および既存のメモリとの重複を排除する
3. 影響度で順位付けし、ADD は候補を 3～7 件に制限する。監査担当者からの削除と統合は別枠とし、上限を設けない
4. 各候補について、対象レイヤー、対象セクション、アクション（ADD / EDIT / MERGE / REMOVE）を決定し、すべてのインデックス／クラスターポインターを Pointer Format（条件を先に記述）で書く
5. 対象ファイルを読み、重複がないか確認する
6. 提案を提示する：

   ### [ACTION] Learning: <summary>
   **Target:** <file> → <section>
   **Rationale:** <why this layer>
   ```diff
   - <old line>
   + <new line>
   

7. 統合時の圧力（統合を実行するたびに必ず実施）。次の順序で行う：（a）監査担当者による SUPERSEDED / REDUNDANT / LOW-VALUE / MERGE の指摘を、具体的な REMOVE/MERGE の提案に変換する。追加だけで終わる実行は失敗パターンです。（b）削除と統合を完了した後に限り、縮小後のセットに対してセクションごとの上限チェックを行う。MEMORY.md のいずれかのセクションがまだ 25 件を超えている場合は、memory/clusters/<section>.md への移行を提案し、そのセクションを単一のポインターに置き換える（適応型クラスタリング）。クラスタリングは削除より先に実行してはいけません。削除可能なエントリを隠してはなりません。既存のクラスターに移行または編集する際は、インラインのルール本文をトピックファイルに切り出し、クラスターを純粋なトリガーインデックス（Pointer Format）に保ちます。これにより、次回そのクラスターに変更を加える際に、混在した内容を整理できます。早期終了の記録（監査担当者からの指摘なし）では（a）を省略し、新しいエントリによってセクションが 25 件を超える場合に限り（b）を実施します
8. レイヤー 0 のゲート — ~/.claude/CLAUDE.md を対象とする場合は、次の警告を表示します："これは、すべてのプロジェクトの全セッションで読み込まれるグローバル指示を変更します。確認しますか？"
9. AskUserQuestion：すべて承認／個別に承認／却下

フェーズ 4：実行

承認された編集を次の順序で適用し、削除の効果が確実に反映されるようにします。

1. REMOVE：削除対象のトピックファイルごとに Bash: trash <path> で削除します（復元可能な trash を使い、rm は絶対に使わない）。続いて、MEMORY.md またはクラスターのファイルからそのポインターを削除します。
2. MERGE：統合したエントリを書き込み、吸収したファイルを trash で削除して、それらのポインターを削除します。
3. クラスター：削除後のセットに対して、承認済みのセクションから memory/clusters/<section>.md への移行を適用します。
4. ADD / EDIT：残りの追加と編集を適用します。各ポインターは Pointer Format で記述します。

報告前に検証します：REMOVE/MERGE の後、解決済みパスから Glob memory/**/*.md を実行し、削除対象の各ファイルが存在しないことを確認します。Glob でファイルが存在しないことを検証するまで、REMOVE/MERGE の行を「完了」としてはなりません。削除されていないのに削除したと主張することこそ、これを防ぐための要点です。

出力サマリーテーブル：

| Learning | Action | Target | Status |
|----------|--------|--------|--------|

フェーズ 2 のエージェントを実行した場合に限り（早期終了の記録ではない場合）、統合マーカーを書き込みます（必須です。マーカーを省略すると、次のセッションで再び通知が表示されます）。Write ではなく Bash を使います。Write は事前の Read が必要で、新しいファイルを作成できません。 Bash: date -u +%Y-%m-%dT%H:%M:%SZ > <memory-dir>/.last-consolidation

承認された編集がすべて適用され、すべての REMOVE/MERGE で Glob による削除確認が済み、マーカーが書き込まれ、サマリーテーブルが提示された時点で、フェーズ 4 は完了です。

内容の品質ルール

各候補は次の条件をすべて満たす必要があります：（1）将来のセッションでエージェントが知っていると役立つ、（2）有用性を保てる最小限の形に要約されている、（3）適切なレイヤーに配置されている、（4）対象ファイルにすでに記録されていない、（5）特定のセッションで起きた出来事ではなく、再利用可能な原則として記述されている。

合格：試行錯誤で見つかったコマンド、直感的に分かりにくい落とし穴、理由を伴うアーキテクチャ上の決定、ユーザーの行動に関する修正、設定上の癖、バージョンの節目。

不合格：コードを読めば分かる情報、一般的なベストプラクティス、パターンのない単発のバグ、冗長な説明、重複、一時的な状態、未検証の推測、一般化できる原則を含まないインシデント。