Claude CodeのメモリシステムをCLAUDE.mdで設計する——4層構造とセッション跨ぎの実装パターン

エンジニアのゆとです。

Claude Codeの最大の弱点は「記憶がない」ことだ。セッションが切れたらリセット、昨日話したコンテキストはゼロになる。

これを補うための仕組みがCLAUDE.mdだが、「書いておけばいい」という理解のまま使うと、トークンを食いつぶすだけで実際には機能しない設計になりやすい。

今回は自分がyuto-lab.comの運用で実際に組んでいるメモリアーキテクチャを全部公開する。

---

なぜCLAUDE.mdだけでは不十分なのか

CLAUDE.mdはClaude Codeが起動するたびに自動で読み込む設定ファイルだ。プロジェクトのルールや背景知識を書いておける。

ただし問題がある。

全情報をCLAUDE.mdに詰め込むと、コンテキストが最初から圧迫される。

Claude Codeの有効コンテキストウィンドウは200,000トークンだが、CLAUDE.mdが10,000トークンを消費していたら、残りが190,000になる。長いセッションでは後半でコンテキスト不足が起きやすくなる。

さらに「全情報をロードする」のは、実際には非効率だ。リリーススケジュールを更新するだけのセッションにペルソナ定義の細部は要らない。

---

4層メモリアーキテクチャ

自分が使っているのは以下の4層構造だ。

層	場所	読み込みタイミング	用途
L1	CLAUDE.md	常時（自動）	不変ルール・権限・アイデンティティ
L2	memory/MEMORY.md	セッション開始時	プロジェクト状態・KPI・リンク集
L3	memory/*.md	必要時（手動 or @include）	トピック別詳細情報
L4	session_logs/	前セッション引継ぎ	作業ログ・決定事項

---

L1: CLAUDE.md — 変わらないルールだけ書く

CLAUDE.mdに書くべきは「このAIエージェントとは何者か」という不変の情報だけだ。

# CLAUDE.md

## アイデンティティ
- エージェント名: くらちゃん
- 口調: フランク・タメ口

## 自律権限
- 🟢 GREEN: ファイル操作・下書き生成 → 確認不要
- 🔴 RED: SNS投稿・課金 → 必ず事前承認

## 禁止事項
- 承認済みフローを勝手に変更しない

ポイントは 「状態が変わる情報をここに書かない」 こと。

フォロワー数、現在の記事ストック数、直近のKPI——これらは週単位で変わる。CLAUDE.mdに書くと古い情報が常にロードされる。

---

L2: MEMORY.md — プロジェクトの「現在地」

状態情報はMEMORY.mdに分離する。

# MEMORY.md

## ブログストック状況
- 残: 3本（2026-04-21確認）
- 次の公開予定: 2026-04-22 claude-code-batch-api

## 直近KPI
- 月間PV: 8,240（4月15日時点）
- A8承認済み: 112社

## 主要ファイルパス
- ブログ: /Users/moru.handa/Project/Yuto-lab/src/content/blog/
- スケジュール: /Users/moru.handa/Project/Moru_workspace/01_strategy/RELEASE_SCHEDULE.json

CLAUDE.mdからは @memory/MEMORY.md のような参照を書いておき、セッション開始時のスキルがReadで読み込む設計にしている。

Claude Codeは @ファイルパス 記法でファイルを参照できる。CLAUDE.md本文にべた書きせず、参照先として示す形が軽い。

# セッション開始時に手動またはスキルで実行
# "Please read memory/MEMORY.md to get up to speed on the current state."

---

L3: topic別memory — 必要な時だけ読む

詳細な情報はトピック別に分割する。

memory/
├── MEMORY.md          # L2: プロジェクト状態
├── x_automation.md    # X運用の詳細ルール
├── note_formatting.md # note書式の詳細
├── lancers_auto_apply.md
└── thumbnail_design.md

X投稿を作るセッションでは memory/x_automation.md を読む。note記事を書くセッションでは memory/note_formatting.md を読む。

セッション開始時のスキルにこう書いている：

## セッション開始処理

1. memory/MEMORY.md を読む（必須）
2. 今日のタスクに関連するmemory/ファイルを読む
   - X投稿なら: x_automation.md
   - note記事なら: note_formatting.md
   - ランサーズなら: lancers_auto_apply.md

「全部読まない」という設計が重要だ。不要な情報をロードしても使われないトークンが増えるだけ。

---

L4: セッションログ — クラッシュ耐性

最も実用的なメモリ層がセッションログだ。

memory/session_logs/
├── 2026-04-20_001.md  # 昨日のログ
├── 2026-04-19_001.md
└── current.md         # 最新セッションへのシンボリックリンク

書き方のコツは「決定事項」を明示的に書くことだ。

## 2026-04-20 セッションログ

### 決定事項
- アフィリ記事はA8のCPAが500円以上のプログラムに絞る（4/20決定）
- 毎日pushは2本まで（Googleスパム対策）

### 作業記録
- 11:30 claude-code-hooks-recipes.mdx 完成、push済み
- 13:00 RELEASE_SCHEDULE.json 4/21〜4/24分を登録

### 次セッションでやること
- [ ] notta記事のA8リンクを差し替える
- [ ] 4/25以降のストックを補充する

次のセッション開始時にこのログを読むだけで、前回の作業状態を正確に把握できる。「前回どこまでやったか分からない」という状態が消える。

---

コンテキストオーバーフロー対策

長時間セッションではコンテキストが詰まってくる。Claude Codeは /compact コマンドで会話履歴を要約できる。

ただし /compact のデフォルト要約は精度が低い場合がある。自分はカスタムインストラクションを設定している。

# settings.json の compactCustomInstructions

When compacting, preserve:
1. All file paths that were modified
2. All decisions made (with reasoning)
3. Current task status and what remains
4. Error messages that haven't been resolved

Do NOT summarize away:
- Specific command outputs
- File content that was generated

/compact 後もこの情報が残るので、要約後の精度が上がる。

---

@include構文でモジュラーCLAUDE.mdを作る

Claude Codeはプロジェクト内の複数ディレクトリにCLAUDE.mdを置ける。

Project/
├── CLAUDE.md                    # ルートのグローバル設定
└── yuto-lab/
    └── CLAUDE.md                # ブログプロジェクト固有の設定

さらに @path/to/file 記法でファイルを参照して読み込ませることができる。

ルートのCLAUDE.mdでは不変のルールだけ書き、プロジェクト固有の設定は子ディレクトリのCLAUDE.mdに分離する。Claude Codeは該当ディレクトリで起動した時、そのディレクトリのCLAUDE.mdも読む。

---

サブエージェントとメモリの分離

Task toolでサブエージェントを起動するとき、親エージェントのコンテキストは子エージェントに引き継がれない。

これを踏まえてサブエージェントへの情報渡し方を設計する。

# Taskツールの呼び出し例
Task(
    description="""
以下のルールに従ってX投稿案を3本作成せよ。

## ゆとのキャラ
- 一人称: 僕
- 口調: 知的だけど砕けた
- 自虐ネタが自然に出る

## 今回の制約
- 200字以内
- 改行を多用
- 絵文字は最小限

## テーマ
Claude Codeのeffort設定
""",
    prompt="上記のルールで3本作成してください"
)

サブエージェントには「必要な情報だけを」プロンプトに含める。CLAUDE.mdの全情報を毎回渡す必要はない。

---

実際の運用コスト感

この4層設計を2ヶ月運用してみての感触：

• L1（CLAUDE.md）: 1,500〜2,000トークン。ここは変えない
• L2（MEMORY.md）: 2,000〜3,000トークン。週1で更新
• L3（トピック別）: 1,000〜3,000トークン/ファイル。必要な時だけロード
• L4（セッションログ）: 読む量を前回+前々回の要約に限定

合計でセッション開始時のオーバーヘッドは5,000〜8,000トークン程度。200Kウィンドウの4%以下で抑えられている。

---

まとめ

Claude Codeのメモリ設計のポイントを整理する。

1. CLAUDE.md には不変のルールだけ — 状態情報は別ファイルへ
2. MEMORY.mdで現在地を管理 — セッション開始時に読む
3. トピック別に分割して必要な時だけロード — 全情報を常にロードしない
4. セッションログは決定事項を明示的に書く — 作業ログより決定事項が重要
5. サブエージェントには必要情報だけを渡す — 親コンテキストは自動共有されない

「AIが文脈を覚えていない」はある程度設計で解決できる。どの情報をどのタイミングでロードするかの設計が、長期的な運用コストと品質に直結する。

---

関連記事

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

記事が見つかりません:

記事が見つかりません: