メモリの管理

Claude Codeの永続的なメモリディレクトリをセッション間で正確、簡潔、有用な状態に保つ。MEMORY.mdはすべての会話でシステムプロンプトに読み込まれる — 200行以降は切り捨てられるため、このファイルは詳細についてトピックファイルを指す無駄のないインデックスでなければならない。

使用タイミング

• MEMORY.mdが200行の切り捨て閾値に近づいている場合
• セッションで保存すべき耐久性のある洞察が生まれた場合（新しいパターン、アーキテクチャの決定、デバッグ解決策）
• MEMORY.mdのトピックセクションが10〜15行を超えて抽出すべき場合
• プロジェクト状態が変化した（ファイルの名前変更、新しいドメイン、更新されたカウント）ためメモリエントリが古い可能性がある場合
• 新しい作業領域を始めて関連するメモリが既に存在するか確認する場合
• セッション間での定期的なメンテナンスでメモリディレクトリを健全に保つ場合

入力

• 必須: メモリディレクトリへのアクセス（通常 ~/.claude/projects/<project-path>/memory/）
• 任意: 具体的なトリガー（例：「MEMORY.mdが長すぎる」「大規模リファクタリングが完了した」）
• 任意: 追加、更新、または抽出するトピック

手順

ステップ1: 現状の評価

MEMORY.mdを読み、メモリディレクトリ内のすべてのファイルを一覧表示する:

wc -l <memory-dir>/MEMORY.md
ls -la <memory-dir>/

200行制限に対する行数を確認する。既存のトピックファイルを棚卸しする。

期待結果： 総行数、トピックファイルの数、MEMORY.mdに存在するセクションの明確な把握。

失敗時： メモリディレクトリが存在しない場合は作成する。MEMORY.mdが存在しない場合は、# Project Memory ヘッダーと ## Topic Files セクションを含む最小限のものを作成する。

ステップ2: 古くなったエントリの特定

メモリの主張を現在のプロジェクト状態と比較する。一般的な陳腐化パターン:

1. カウントのずれ: 追加/削除後に変化したファイル数、スキル数、ドメイン数
2. 名前変更されたパス: 移動、名前変更、削除されたファイルまたはディレクトリ
3. 不要になったパターン: 修正後に不要になった回避策
4. 矛盾: 同じトピックについて異なることを述べている2つのエントリ

Grepを使って主要な主張を確認する:

# 例: スキル数の主張を確認する
grep -c "^      - id:" skills/_registry.yml
# 例: ファイルがまだ存在するか確認する
ls path/claimed/in/memory.md

期待結果： 古くなったエントリの一覧と正しい現在値。

失敗時： 主張を確認できない場合（例: 確認できない外部状態を参照している）、潜在的に誤った情報を黙って保持するのではなく、(unverified) 注釈を追加する。

ステップ3: 追加すべき内容の決定

新しいエントリには、書き込む前にこれらのフィルターを適用する:

1. 耐久性: これは次のセッションでも真実か? セッション固有のコンテキスト（現在のタスク、進行中の作業、一時的な状態）は避ける。
2. 重複なし: CLAUDE.mdやプロジェクトドキュメントでは既にカバーされていないか? 重複させない — メモリは他の場所でキャプチャされていないことのためのもの。
3. 検証済み: 複数のインタラクションで確認されたか、単一の観察か? 単一の観察の場合、書き込む前にプロジェクトドキュメントに対して確認する。
4. 実行可能: これを知ることで動作が変わるか? 「空は青い」は有用ではない。「終了コード5はクォートエラーを意味する — 一時ファイルを使用する」は作業方法を変える。

例外: ユーザーが何かを覚えるよう明示的に求めた場合、すぐに保存する — 複数の確認を待つ必要はない。

期待結果： 耐久性 + 重複なし + 検証 + 実行可能性の基準を満たす、追加すべきエントリのフィルタリングされた一覧。

失敗時： エントリを保持する価値があるかどうか不明な場合、MEMORY.mdに簡単に保持する方向に誤る — 後で整理する方が再発見するよりも簡単だ。

ステップ4: サイズが大きすぎるトピックの抽出

MEMORY.mdのセクションが約10〜15行を超えた場合、専用のトピックファイルに抽出する:

1. <memory-dir>/<topic-name>.md を説明的なヘッダーで作成する
2. MEMORY.mdからトピックファイルに詳細なコンテンツを移動する
3. MEMORY.mdのセクションを1〜2行の要約とリンクに置き換える:

## Topic Files
- [topic-name.md](topic-name.md) — Brief description of contents

トピックファイルの命名規則:

• 小文字ケバブケースを使用する: viz-architecture.md（VizArchitecture.md ではなく）
• 時系列ではなくトピックで名前を付ける: patterns.md（session-2024-12.md ではなく）
• 関連するアイテムをグループ化する: 「Rデバッグ」と「WSLの特性」を別々のファイルではなく patterns.md にまとめる

期待結果： MEMORY.mdが200行未満に収まる。各トピックファイルはMEMORY.mdのコンテキストなしに単独で読める。

失敗時： トピックファイルが5行未満になる場合、おそらく抽出する価値はない — MEMORY.mdにインラインで残す。

ステップ5: MEMORY.mdを更新する

すべての変更を適用する: 古いエントリを削除し、新しいエントリを追加し、カウントを更新し、トピックファイルセクションにすべての専用ファイルが一覧されていることを確認する。

MEMORY.mdの構造はこのパターンに従う必要がある:

# Project Memory

## Section 1 — High-level context
- Bullet points, concise

## Section 2 — Another topic
- Key facts only

## Topic Files
- [file.md](file.md) — What it covers

ガイドライン:

• 各箇条書きは最大1〜2行に保つ
• スキャン性のためにインラインフォーマット（code、太字）を使用する
• 最も頻繁に必要なコンテキストを最初に置く
• トピックファイルセクションは常に最後にある

期待結果： MEMORY.mdが200行未満で、正確で、すべてのトピックファイルへの動作するリンクがある。

失敗時： 抽出後も200行以下にならない場合、最も使用頻度の低いセクションを特定して抽出する。すべてのセクションが候補だ — 必要に応じてプロジェクト構造の概要もトピックファイルに移動できる。

ステップ6: 整合性の検証

最終確認を実行する:

1. 行数: MEMORY.mdが200行未満であることを確認する
2. リンク: MEMORY.mdで参照されているすべてのトピックファイルが存在することを確認する
3. 孤立ファイル: MEMORY.mdで参照されていないトピックファイルを確認する
4. 正確性: 2〜3つの事実の主張をプロジェクト状態に対してスポットチェックする

wc -l <memory-dir>/MEMORY.md
# 壊れたリンクを確認する
for f in $(grep -oP '\[.*?\]\(\K[^)]+' <memory-dir>/MEMORY.md); do
  ls <memory-dir>/$f 2>/dev/null || echo "BROKEN: $f"
done
# 孤立したファイルを確認する
ls <memory-dir>/*.md | grep -v MEMORY.md

期待結果： 200行未満、壊れたリンクなし、孤立したファイルなし、スポットチェックした主張が正確。

失敗時： 壊れたリンクを修正する（更新または削除する）。孤立したファイルについては、MEMORY.mdに参照を追加するか、関連性がなくなっている場合は削除する。

バリデーション

• MEMORY.mdが200行未満である
• MEMORY.mdで参照されているすべてのトピックファイルがディスクに存在する
• メモリディレクトリに孤立した .md ファイルがない（すべてのファイルがMEMORY.mdからリンクされている）
• どのメモリファイルにも古いカウントや名前変更されたパスがない
• 新しいエントリが耐久性/重複なし/検証済み/実行可能性の基準を満たしている
• トピックファイルに説明的なヘッダーがあり、単独で読める
• MEMORY.mdが変更ログではなく有用なクイックリファレンスとして読める

よくある落とし穴

• メモリファイルの汚染: すべてのセッションの観察をメモリに書き込む。ほとんどの発見はセッション固有で永続化する必要はない。書き込む前に4つのフィルター（ステップ3）を適用する。
• 古くなったカウント: コードを更新したがメモリを更新しない。カウント（スキル、エージェント、ドメイン、ファイル）は静かにずれる。メモリを信頼する前に、常にカウントを真実のソースに対して確認する。
• 時系列による整理: 「学習した時期」ではなく「内容」で整理する。トピックベースの整理（patterns.md、viz-architecture.md）は日付ベースのファイルよりもはるかに取得に有用だ。
• CLAUDE.mdの複製: CLAUDE.mdは権威あるプロジェクト指示ファイルだ。メモリはCLAUDE.mdにないことをキャプチャする — デバッグの洞察、アーキテクチャの決定、ワークフローの好み、プロジェクト横断のパターン。
• 過剰な抽出: すべての3行のセクションにトピックファイルを作成する。セクションが約10〜15行を超えた場合にのみ抽出する。小さいセクションはインラインで問題ない。
• 200行制限を忘れる: MEMORY.mdはすべてのシステムプロンプトに読み込まれる。200行以降は静かに切り捨てられる。ファイルがこれを超えると、下部のコンテンツは実質的に見えなくなる。

関連スキル

• write-claude-md — CLAUDE.mdはプロジェクト指示をキャプチャし、メモリはセッション横断の学習をキャプチャする
• prune-agent-memory — manage-memoryの逆: 保存されたメモリの監査、分類、選択的な忘却
• write-continue-here — セッション引き継ぎのための構造化された継続ファイルを書く; 短期コンテキストブリッジとしてメモリを補完する
• read-continue-here — セッション開始時に継続ファイルを読み取り実行する; 引き継ぎの消費側
• create-skill — 新しいスキルはメモリ価値のあるパターンを生む可能性がある
• heal — セルフヒーリングは統合ステップの一部としてメモリを更新する場合がある
• meditate — 瞑想セッションは永続化する価値のある洞察を明らかにする場合がある