Memory システム設計 — ユーザー・プロジェクト・参照メモリの設計指針

読了 10分＋実践 25分

Claude Code の基本操作を理解しており、会話をまたいで Claude の振る舞いをカスタマイズしたい方。

Claude Code のセッション概念（会話が終わると状態がリセットされること）を理解していること
Markdown の frontmatter（三重ハイフンで囲んだ YAML 形式）を読み書きできること

Claude Code のメモリシステムを使うと、ユーザーの好み・プロジェクトの決定事項・外部リソースへの参照を会話をまたいで保持できます。このページでは、4 種類のメモリの使い分けから MEMORY.md インデックスの設計・実際の運用まで順番に学びます。

Memory システムとは何か

メモリシステムとは、Claude Code が会話をまたいで情報を保持するためのファイルベースの仕組みです。通常、Claude Code はセッションが終了すると状態をリセットします。メモリファイルを使うことで、次のセッションでも Claude が前回の文脈を参照できるようになります。

メモリは ~/.claude/projects/<project-path>/memory/ ディレクトリに保存されます。<project-path> はプロジェクトのルートディレクトリのパスから / を - に変換した文字列です。

~/.claude/projects/
└── -Users-yourname-github-myproject/
    └── memory/
        ├── MEMORY.md          # インデックスファイル
        ├── user-background.md
        ├── feedback-response-style.md
        └── project-current-sprint.md

MEMORY.md はインデックスファイルです。Claude Code はメモリディレクトリを参照するとき、まずこのファイルを読みます。200 行・1 行あたり 150 字以内という上限があり、これを超えると切り捨てられます。

4 種類のメモリと使い分け

メモリファイルは frontmatter の metadata.type フィールドで 4 種類に分類します。

種別	何を記録するか	記録の例
`user`	ユーザーの役割・スキル・好み	「React が得意、Go は初心者」
`feedback`	Claude への指示・修正	「レスポンスの末尾にサマリーを書かない」
`project`	進行中の作業・決定事項・期限	「マージフリーズは 2026-05-30 まで」
`reference`	外部リソースへのポインタ	「バグ管理は Linear の INGEST プロジェクトで行う」

それぞれの種別を適切に使い分けることで、Claude がどの情報をどのコンテキストで参照すべきかを判断しやすくなります。

仕組み: メモリファイルの構造

frontmatter フォーマット

---
name: short-kebab-case-slug
description: メモリの内容を一行で説明する文
metadata:
  type: user | feedback | project | reference
---

name: ファイルを識別するスラッグ。ファイル名と一致させます
description: MEMORY.md インデックスに掲載される 1 行の説明
metadata.type: 4 種別のいずれかを指定します

メモリファイルの本文

frontmatter の後に、Claude への情報をそのまま Markdown で記述します。「なぜこの情報が必要か（Why）」と「どう適用するか（How to apply）」を必ず書きます。

---
name: user-background
description: ユーザーの技術バックグラウンドと好み
metadata:
  type: user
---

フロントエンドエンジニア。React/TypeScript が得意。Go は書いたことがない。

**Why:** 技術レベルに合わせた説明をするため。
**How to apply:** 説明は実装寄りで、React の例を積極的に使う。Go の知識が必要な場合は丁寧に基礎から説明する。

MEMORY.md インデックスの形式

MEMORY.md の各行は次の形式で書きます。

- [title](file.md) — 1行フック（何が書いてあるかを一言で）

実際の MEMORY.md の例:

# Memory Index

- [user-background](user-background.md) — React/TypeScript が得意なフロントエンドエンジニア
- [feedback-response-style](feedback-response-style.md) — レスポンス末尾にサマリーを書かない
- [project-current-sprint](project-current-sprint.md) — マージフリーズ 2026-05-30 まで
- [reference-linear](reference-linear.md) — バグ管理は Linear の INGEST プロジェクト

ベストプラクティス

コードパターンや git 履歴は保存しない

git log・grep・cat で取得できる情報はメモリに書きません。メモリは Claude が「知っておくべきコンテキスト」を保存する場所であり、リポジトリから取得できる情報を二重管理する場所ではありません。コンテキストウィンドウを無駄に消費するだけです。

Why を必ず書く

メモリは時間が経つと古くなります。なぜその情報を保存したのかを書いておくと、更新・削除の判断がしやすくなります。

// 避けるべき記述: Why がない
末尾にサマリーを書かない。

// 推奨: Why がある
末尾にサマリーを書かない。
**Why:** ユーザーは diff を直接読めるため、繰り返し説明は不要。

feedback は成功も失敗も保存する

「やり直しを求められたアプローチ」だけでなく、「明示的に確認された良いアプローチ」も記録します。失敗だけを保存すると、Claude はどのアプローチが有効かを判断する材料が不足します。

project メモリには絶対日付を使う

「木曜日」「来週」のような相対的な表現は、メモリを後から読んだときに意味をなさなくなります。2026-05-30 のように絶対日付で記述します。

// 避けるべき記述: 相対日付
マージフリーズは来週まで。

// 推奨: 絶対日付
マージフリーズは 2026-05-30 まで。

古いメモリは更新・削除する

状況が変わったのに古い情報が残っていると、Claude が誤った前提で動作するリスクがあります。スプリント終了時・プロジェクト完了時など、定期的なタイミングでメモリを見直します。

実践演習

Step 1: プロジェクトのメモリディレクトリを確認する

ターミナルで次のコマンドを実行し、メモリディレクトリの一覧を確認します。

ls ~/.claude/projects/

出力例:

-Users-yourname-github-ai-learning-playground
-Users-yourname-github-another-project

プロジェクトのパスに対応するディレクトリが存在することを確認します。

✅ 確認: 現在作業しているプロジェクトに対応するディレクトリが表示されれば、メモリシステムが有効です。ディレクトリが存在しない場合は、Claude Code でそのプロジェクトを一度開くと自動的に作成されます。

Step 2: MEMORY.md インデックスを確認する

プロジェクトのメモリディレクトリにある MEMORY.md を確認します。<path> を実際のパスに置き換えてください。

cat ~/.claude/projects/<path>/memory/MEMORY.md

インデックスに記録されているメモリファイルの一覧と、それぞれの説明を読み取ります。

✅ 確認: ファイルが表示されればインデックスの確認完了です。ファイルが空または存在しない場合は、次のステップでフィードバックメモリを作成してインデックスに追加します。

Step 3: フィードバックメモリを新規作成する

Claude へのフィードバックを記録するメモリファイルを作成します。<path> を実際のパスに置き換えてください。

作成するファイルの内容:

---
name: feedback-response-style
description: Claude のレスポンスに関するフィードバック
metadata:
  type: feedback
---

レスポンスの末尾にサマリーを書かない。

**Why:** ユーザーは diff を直接読めるため、繰り返し説明が不要。
**How to apply:** 作業が完了したら次のステップのみを簡潔に伝える。確認のための箇条書きまとめは省略する。

ターミナルでファイルを保存した後、次のコマンドでファイルが作成されたことを確認します。

ls ~/.claude/projects/<path>/memory/

✅ 確認: feedback-response-style.md が一覧に表示されれば作成成功です。

Step 4: MEMORY.md にエントリを追加する

MEMORY.md を編集し、作成したメモリファイルをインデックスに追加します。

- [feedback-response-style](feedback-response-style.md) — レスポンス末尾にサマリーを書かない

追加後の MEMORY.md の例:

# Memory Index

- [feedback-response-style](feedback-response-style.md) — レスポンス末尾にサマリーを書かない

次のセッションで Claude Code を起動し、Claude が「末尾にサマリーを書かない」という指示を参照して動作することを確認します。

✅ 確認: MEMORY.md を cat で確認して、エントリが追加されていれば完了です。次のセッションで Claude が自動的にメモリを参照するかどうかは /memory コマンドでメモリの読み込み状態を確認できます。

まとめ

メモリシステムは ~/.claude/projects/<path>/memory/ にファイルとして保存されるセッション横断の記憶
MEMORY.md はインデックスファイルで、200 行・1 行 150 字以内の上限がある
メモリは user・feedback・project・reference の 4 種別で分類する
Why と How to apply を必ず記述することで、古くなったときの更新判断がしやすくなる
コードや git 履歴はメモリに保存せず、project メモリには絶対日付を使う
定期的に古いメモリを見直して更新・削除することでコンテキストの鮮度を保つ

次のステップ

ハーネスのテストと検証 — メモリを含む設定全体が意図通りに機能するかを体系的に検証する方法へ進む
Settings JSON 設計 — メモリと組み合わせて使う権限・環境変数の設定方法を復習する

よくある質問

Q: メモリファイルは何個まで作れますか？

A: ファイル数に上限はありません。ただし、Claude Code がセッション開始時に参照できる情報量はコンテキストウィンドウの制限に依存します。MEMORY.md インデックスの 200 行上限を超えると切り捨てられるため、重要度の高いメモリを上部に配置することを推奨します。

Q: 複数のプロジェクトでメモリを共有できますか？

A: 現時点では、メモリはプロジェクトごとのディレクトリに保存されるため、プロジェクトをまたいだ自動共有はできません。複数プロジェクトに共通する情報（ユーザーの技術バックグラウンドなど）は、各プロジェクトのメモリに手動でコピーするか、グローバルな CLAUDE.md に記述することで対応できます。

Q: Claude が自動的にメモリを更新することはありますか？

A: Claude Code の自動メモリ機能が有効な場合、Claude は会話の内容をもとにメモリファイルを自動生成・更新することがあります。自動更新されたメモリは定期的に内容を確認し、意図しない情報が保存されていないかチェックすることを推奨します。

Q: メモリファイルを削除するとどうなりますか？

A: ファイルを削除すると、次のセッションから Claude はその情報を参照しなくなります。MEMORY.md のインデックスエントリも合わせて削除してください。インデックスに記載されたファイルが存在しない場合、Claude Code がエラーを報告することがあります。

Q: /memory コマンドと手動でファイルを作成する方法の違いは何ですか？

A: /memory コマンドは Claude に口頭で情報を伝え、Claude が自動的にメモリファイルを生成します。手動でファイルを作成する方法は、frontmatter の type や本文の Why・How to apply セクションを自分でコントロールできます。重要な設計上の決定や詳細なコンテキストを保存する場合は手動作成を推奨します。

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]

参考文献

Anthropic, Claude Code documentation
Anthropic, Claude API documentation

クイズ

ハーネスのテストと検証 — drift 検出・CI バリデーション

MCP Plugins 統合 — ローカル・リモート MCP サーバーの設定