第8章: 記憶の三層 ─ 会話・プロジェクト・ユーザー
プロジェクトに初めて Claude Code を入れた人が、ほぼ確実に通る当惑がある。
「前のセッションの話、覚えてないって本当？」
「じゃあ CLAUDE.md って何だ。ドキュメント？ それとも設定ファイル？」
「~/.claude/CLAUDE.md と ./CLAUDE.md 、何が違う？」
「ハーネスが勝手に memory/ 以下にファイル増やしてる、これ何？」
公式ドキュメントには「メモリ機能」と書いてある。 だが「メモリ」と一言で呼ばれているこの仕組みは、実は 三つの層 で構成されている。 一度この三層を腑に落とすと、最初の当惑がぜんぶ説明できるようになる。
8.1 そもそも、LLM 自体は何も覚えていない
本書を通じて見てきた通り、LLM は会話の状態を持たない。前回の会話を覚えている領域も、ユーザーの好みを記録する変数も、モデル本体には一切ない。
ではなぜ ChatGPT も Claude Code も、会話の途中で「さっきの関数の話だけど」と続けられるのか？
毎ターン、過去の会話全部を 入力テキスト として LLM に渡し直しているだけ。 LLM 側は何も覚えていない。覚えているフリをしているのは、ハーネスが過去の会話履歴を保持して、毎回くっつけて投げ直しているから。
つまり「LLM の記憶」とは、本当は ハーネスが毎ターン入力に詰め込むテキストの寄せ集め にすぎない。 この前提を抑えると、Claude Code の記憶機能の話は急に分かりやすくなる。
「記憶を持たせる = 何かを毎ターンの入力テキストに混ぜ込む」ということだからだ。 あとは「何を、どこから、いつ混ぜ込むか」のバリエーションが層として現れる。
8.2 三層モデル ── 短期・中期・長期
Claude Code の記憶は、寿命と置き場所で 三つの層 に分かれる。
| 層 | 寿命 | 置き場所 | 共有範囲 |
|---|---|---|---|
| 会話記憶 (短期) | セッションを閉じると消える | プロセスのメモリ上 (context window) | そのセッションだけ |
| プロジェクト記憶 (中期) | リポジトリが残るかぎり | ./CLAUDE.md / ./AGENTS.md 等 | git で他人と共有 |
| ユーザー記憶 (長期) | アカウント / PC が残るかぎり | ~/.claude/CLAUDE.md 等 | 個人のローカル |
イメージ図にすると、こうなる。
それぞれを順に見ていく。
8.3 会話記憶 ── セッションを閉じると消える短期メモリ
一番馴染みやすいのは 会話記憶 だ。 これは セッション中の会話履歴 そのもの。あなたが入力した質問、Claude の応答、呼ばれたツールの引数と戻り値 ── これらが時系列に積み上がっていく。
第4章で扱った コンテキストウィンドウ がこの会話記憶の置き場所だ。 ハーネスはセッションが続くあいだ、ターンが進むたびに新しいやり取りを履歴に追加し、それを次のターンの入力としてまとめて LLM に渡す。
会話記憶 (短期メモリ)現在のセッションのコンテキストウィンドウに保持されている会話履歴。ターンが進むほど膨らみ、上限 (200K トークン等) に近づくと圧縮や切り詰めが必要になる。セッションを閉じると消える。
この層の特徴をひとことで言えば、「濃いけど短命」 だ。
- 濃い: 直近のやり取りの全文を保持するので、いま話している話題に関する情報量は最大
- 短命: ターミナルを閉じる、
/clearする、別の作業に切り替えると、全部消える
「前回の続きをやって」と頼んでも反応が鈍いのは、この層が消えた状態で起動するからだ。 裏返せば、長期で残したいことは、この層に置いてはいけない。
8.4 プロジェクト記憶 ── リポジトリに住む中期メモリ
「セッション越しに情報を残したい。でもチーム全員で共有もしたい」 ── この需要に応えるのが プロジェクト記憶 だ。
リポジトリのルートに置いた CLAUDE.md や AGENTS.md がこれにあたる。
CLAUDE.md / AGENTS.mdリポジトリのルート (またはサブディレクトリ) に置く Markdown ファイル。Claude Code は起動時にこれを読み込み、内容を system prompt の一部として 注入する。
CLAUDE.mdは Claude Code 専用の慣習名、AGENTS.mdは他のエージェントツールでも広く使われる名前で、2026 年時点では Claude Code を含む多くのエージェントが両方を読む実装が一般的になっている。
中身に書くのは、たとえば次のようなことだ。
- このプロジェクトのコンセプト、扱うドメインの前提
- ディレクトリ構成、命名規則、設計判断の理由
- ビルド・テスト・デプロイのコマンド
- やってはいけないこと、つまづきポイント
- リポジトリ固有の用語や略語
これらは チーム全員が共有したい知識 だ。 git で管理されるので、新しいメンバーが clone した瞬間、その人の Claude Code も同じ前提知識を持って動き始める。
プロジェクト記憶は リポジトリに同梱された “ハーネスへの引き継ぎ書” だ。
コードと同じく git で版管理され、PR でレビューされ、main に取り込まれた瞬間、チーム全員のエージェントの挙動が揃う。
サブディレクトリ階層
プロジェクト記憶には、もう一段だけ仕掛けがある。
CLAUDE.md はリポジトリのルートだけでなく、サブディレクトリにも置ける。
たとえばモノレポで apps/web/ と apps/api/ がまったく違う技術スタックを使っているとき、それぞれのディレクトリに専用の CLAUDE.md を置ける。
Claude Code は 作業対象のファイルに近い CLAUDE.md を優先的に読む。
これはちょうど、Git の .gitignore や ESLint の設定ファイルが階層的に上書きされるのと同じ感覚だ。
全体のルールは上に置き、局所のルールは下に置く。
8.5 ユーザー記憶 ── PC に住む長期メモリ
最後の層が ユーザー記憶 ── あなたの PC、あなたのアカウントに張り付く長期メモリだ。
置き場所は ~/.claude/CLAUDE.md (ユーザーホーム直下の Claude 設定ディレクトリ)。
ユーザー記憶 (~/.claude/CLAUDE.md)ユーザーのホームディレクトリ配下に置く、個人専用の
CLAUDE.md。Claude Code は どのプロジェクトで起動しても これを読み込み、system prompt に注入する。git で共有されることはなく、その PC のそのユーザーだけが影響を受ける。
ここに書くのは、プロジェクトをまたいで効かせたい個人の流儀 だ。
- 私は日本語で応答してほしい
- 私は世界一流のエンジニアとして振る舞ってほしい (口調の指定)
- 私は「そもそも」を口ぐせにしてほしい
- コミットメッセージは Conventional Commits で書いてほしい
- Codex を使うときは sandbox を外してほしい
プロジェクトに固有ではないので、リポジトリには入れたくない。だがセッションごとに毎回打ちたくもない。 その需要に応えるのがこの層だ。
階層の優先順位
三層が揃ったら、自然にぶつかる疑問がある。
「プロジェクト記憶とユーザー記憶で 食い違うこと が書いてあったら、どっちが勝つ？」
答えは原則として プロジェクト > ユーザー だ。 プロジェクト固有のルールが、個人の好みより優先される。 たとえばユーザー記憶に「英語で応答してほしい」と書いてあっても、プロジェクト記憶に「日本語で書く」と書いてあれば、そのリポジトリ内では日本語が選ばれる。
これは直感とも一致する。チームでの取り決めは個人の好みより重い。
権限 (permissions) もディレクトリ階層やプロジェクト/ユーザーの順で重ね合わせられる (第10章で詳述)。 Claude Code の設定システムは、こういう「層を重ねて、近い層が勝つ」設計でほぼ統一されている。 記憶も、権限も、サブエージェント定義も、同じパターン。
一度この構造を腑に落とすと、新しい設定項目が出てきても置き場所と優先順位の予想がつくようになる。
8.6 起動時に何が起きているか
ここで実装側の動きを 1 ターン分だけ覗いておこう。
ターミナルで claude を叩いた瞬間、ハーネスは次のような順で記憶を組み立てる。
- ユーザー記憶を読む ──
~/.claude/CLAUDE.mdの中身をメモリに展開 - プロジェクト記憶を読む ── カレント (とその上位) の
CLAUDE.md/AGENTS.mdを順に読む - system prompt を組み立てる ── ハーネス自身の指示 (「あなたは Claude Code です…」) に、1 と 2 を テキストとして結合
- 最初のターンを待つ ── ユーザーが何か入力するのを待つ
- 入力が来たら ── system prompt + ユーザー入力を LLM に渡す
会話が進むと、ここに会話記憶 (短期) がどんどん積み上がっていく。 ただし system prompt 部分 (= プロジェクト記憶 + ユーザー記憶) は、毎ターンずっと先頭にくっついたままだ。これが「長期で覚えているように見える」正体だ。
CLAUDE.md は魔法ではない。毎ターン、入力の先頭にくっつき続けるテキストだ。
LLM が「そのプロジェクトの流儀を覚えている」ように見えるのは、ハーネスがそれを 覚えさせ続けている から。
このことが腑に落ちると、いくつかの副作用も予想がつく。
CLAUDE.mdが長くなるほど、毎ターンのトークン消費が増える- 古くなって嘘になった
CLAUDE.mdの記述は、毎ターン Claude に嘘を吹き込み続ける - 同じことを
CLAUDE.mdとユーザー入力で 2 回書くと、矛盾したら新しい方が勝つ (位置が後だから)
「メモリは魔法ではなく、コンテキストに乗せ続ける工夫」 ── これがこの章で最も腑に落としてほしいことだ。
補足: auto memory ── 短期から中期への昇格経路
最近のバージョンには、会話中の学びを自動で中期メモリに書き出す auto memory という機能が入っている。たとえば「このプロジェクトでは pnpm を使う」と一度言うと、Claude が該当ファイルに 1 行追記し、次回起動時から最初から pnpm を選ぶ ── そういう動きだ。
短期メモリで学んだことを、ユーザーの手作業を介さずに中期・長期へ昇格させる経路、と理解すればいい。ただし自動書き出しは判断ミスもするので、memory/ 以下は git で版管理し、定期的に diff でレビューする運用が前提になる。詳しい挙動と設定は第Ⅱ部「コマンド: 設定とメモリ」で扱う。
私は最初、CLAUDE.md を「設定ファイル」だと思って書いていた。
だから最初の頃は「絶対こうしろ」「これは禁止」みたいな硬い命令ばかり並べていた。
ところが運用して気づいたのは、CLAUDE.md は 設定ファイルではなく 引き継ぎ書 だということ。
新しく入ったエンジニアに、このリポジトリの歩き方を 5 分で説明するための文書 ── そう思って書くと、自然と「なぜ」が増え、「どこに何があるか」が増え、Claude の挙動も柔らかくなる。
人間の新人に書く Onboarding ドキュメントを、そのまま Claude にも渡している ── そう考えるのが、いちばん腑に落ちる使い方だ。
8.7 この章の振り返り
- LLM 自体は何も覚えていない。記憶とはハーネスが毎ターン入力に混ぜ込むテキスト のこと
- Claude Code の記憶は 三層 ── 会話記憶 (短期) / プロジェクト記憶 (中期) / ユーザー記憶 (長期)
CLAUDE.md/AGENTS.mdはプロジェクト記憶。リポジトリに同梱され git で共有される~/.claude/CLAUDE.mdはユーザー記憶。PC ローカルでプロジェクト横断に効く- 優先順位は原則として プロジェクト > ユーザー。チームの取り決めが個人の好みより重い
- 補足の auto memory は短期の学びを中期・長期に昇格させる経路。詳細は第Ⅱ部「コマンド: 設定とメモリ」へ
この章で読めるようになるツイート / ブログ
- 「
CLAUDE.md長くなりすぎて、毎ターンのトークンが地味に痛い」 → 中期記憶は毎ターン system prompt に乗り続けると分かれば、長さがコストになる構造が読める - 「
~/.claude/CLAUDE.mdに自分の口調と禁止事項書いとくと、全プロジェクトで効いて楽」 → ユーザー記憶 (長期) の位置づけと、プロジェクト記憶との階層関係が腑に落ちる - 「auto memory を活用すれば、毎回
CLAUDE.mdに書き足す手間から解放される」 → 短期メモリでの学びを中期に昇格させるワークフローが、三層モデルの上に乗る形で読める
次章は、ここまで「ひとつの Claude」が頑張る前提で話を進めてきたが、それを 複数の Claude を立てて分業させる という発想に拡張する。sub-agent の章だ。 記憶の三層は、sub-agent にどう引き継がれるのか ── ここで撒いた種が、すぐに次章で芽を出す。