永続メモリ：Claude Code はどう記憶するか

学ぶこと

Claude Code の歴史の大半において、すべてのセッションはゼロから始まっていました。CLAUDE.md に恒常的なルールを書いておくことはできましたが、セッション中に学んだこと — 火曜日にあなたが行った訂正、先月発見したデプロイの落とし穴 — は、セッションが終わると蒸発していました。Fable 5（フェーブル 5）時代は、プロジェクトごとの永続的なファイルベースのメモリディレクトリでこれを変えます。

読み終える頃には、次のことが理解できます：

• メモリの保存場所と「1事実1ファイル」フォーマット
• 4つのメモリタイプ：user、feedback、project、reference
• MEMORY.md が常時ロードされるインデックスとして機能する仕組み
• メモリ間を結ぶ Wiki スタイルの [[links]]
• メモリをノイズにせず有用に保つ衛生ルール
• 想起（recall）の仕組み（そして想起されたメモリを再検証しなければならない理由）
• コンテキスト要約がハードな圧縮（compaction）を置き換えた経緯

課題

メモリを持たないエージェントは、あなた自身がそのメモリになることを強います。毎セッション、ステージングのデータベースは変な名前が付いている方だとか、squash マージを好むとか、あの不安定なテストは調査済みで原因は CI ランナーの時計だとか、同じ説明を繰り返すことになります。これはセッション開始のたびに支払う実コストです。

素朴な解決策は、どちらも失敗します：

• チャットログを再ロードする。 トランスクリプトは巨大で、大半はノイズです — ツール出力、行き止まり、放棄されたアプローチ。丸ごとロードすればコンテキストウィンドウをゴミで焼き尽くします。
• すべてを CLAUDE.md に詰め込む。 CLAUDE.md は恒常的なルールのためのものです — どうビルドするか、どの規約に従うか。一時的な発見（「auth リファクタリングは半分終わり」）を混ぜると、ルールファイルは陳腐化していくガラクタ入れと化します。

必要なのは第三のものです：セッションをまたいで蓄積され、安価にロードでき、間違っていれば訂正できる、キュレーションされた永続的な知識。

仕組み

1メモリ、1ファイル、1事実

各プロジェクトにはメモリディレクトリが与えられます：

~/.claude/projects/<project-slug>/memory/
├── MEMORY.md                          ← the index (always loaded)
├── user_prefers-squash-merges.md
├── feedback_use-pnpm-not-npm.md
├── project_auth-refactor-status.md
└── reference_staging-dashboard.md

ルールは厳格です：1メモリ = 1ファイル = 1事実。 各ファイルは YAML フロントマターを持ちます：

• name — 短い kebab-case のスラッグ
• description — 1行の要約。想起時の関連度判定に使われる
• metadata.type — user、feedback、project、reference のいずれか

なぜ1ファイルに1事実なのか？事実は互いに独立して変化するからです。auth リファクタリングが完了したら、削除するのはそのファイルだけ — モノリシックなメモ文書の中から、それが汚染した古い文をひとつずつ探し回る必要はありません。

4つのメモリタイプ

タイプ	記録する内容	例
user	ユーザーが誰か — 役割、専門性、好み	「squash マージを好む。シニアバックエンド開発者」
feedback	訂正と確認済みのアプローチ。Why と How to apply 付き	「npm ではなく pnpm を使う — npm はロックファイルを壊す」
project	進行中の作業、目標、コードや git 履歴から導けない制約	「auth リファクタリングはセキュリティレビュー待ちで一時停止」
reference	外部リソースへのポインタ — URL、ダッシュボード、チケット	「ステージングのメトリクスは Grafana ダッシュボードにある」

主力は feedback タイプです。その本文は2つの問いに答えるべきです：なぜ（Why）それが正しいアプローチなのか、そして次回どう適用するか（How to apply）。この2つを欠いた訂正は、少し違う状況でエージェントが誤って適用するだけのルールにすぎません。

タイプに含まれていないものにも注目してください：「コード構造」です。これは意図的です — 後述の衛生ルールを参照。

MEMORY.md：常時ロードされるインデックス

毎セッションすべてのメモリファイルをロードしていたら、チャットログ問題の再来です。そこでシステムは、セッション 5 のスキルで見たのと同じ遅延ロードの哲学を使います：名前は前もって、内容はオンデマンドで。

MEMORY.md がそのインデックスです — 1メモリにつき1行：

- [Use pnpm, not npm](feedback_use-pnpm-not-npm.md) — npm installs corrupt the lockfile
- [Auth refactor status](project_auth-refactor-status.md) — paused pending security review

インデックスは毎セッション、コンテキストにロードされます。メモリの内容は個々のファイルに留まり、インデックスに載るのはポインタだけです。エージェントは1事実につき1行をスキャンし、関連があるときだけファイル全体を取り込みます。

Wiki スタイルのリンク

メモリ同士は、スラッグによる [[wiki-style]] リンクで相互にリンクします：

The lockfile issue first surfaced during the [[project_auth-refactor-status]] work.

宙に浮いた（dangling）リンクがあっても問題ありません — まだ存在しないメモリへのリンクは、後で書く価値のあるものの目印になるだけです。事実を完全な形で書くために手を止めることなく、パンくずを残せる安価な方法です。

想起は背景コンテキストであって、絶対の真理ではない

セッション中にメモリが想起されると、それは <system-reminder> ブロックの中に現れます — ハーネスが注入するノートで、ツール可用性の変更やモード変更に使われるのと同じ仕組みです。重要な性質が2つあります：

1. それはコンテキストであって、ユーザーの指示ではない。 想起されたメモリは命令せず、情報を与えるだけです。
2. それは書かれた時点の真実を反映している。 コードベースはその後も動き続けています。想起されたメモリは、行動する前に現在のコードと突き合わせて再検証しなければなりません。

この2点目こそ、メモリが助けになるか害になるかの分かれ目です。「config ローダーは src/utils/ にある」という6週間前のメモは、確認すべき手がかりであって、その上に築いてよい事実ではありません。

3つの知識レイヤー

メモリは CLAUDE.md やスキルを置き換えるものではなく、スタックを完成させるものです：

CLAUDE.md   →  standing rules        ("always use pnpm; run tests before commit")
Memory      →  accumulated experience ("we tried X on 2026-06-12; it broke Y")
Skills      →  procedures             ("how to cut a release, step by step")

ルール、経験、手順。書いているメモリがルールのように読めることに気づいたら、それは CLAUDE.md に移すべきです。ステップバイステップのプロセスのように読めるなら、それはスキルになりたがっています。

要約がハードな圧縮を置き換えた

永続メモリは、長い会話の扱い方の変化と対をなしています。旧時代（セッション 6）では、コンテキスト上限に達すると「auto-compact」が発動しました。Fable 5 時代では、会話が長くなるとコンテキストの一部または全部が要約され、その要約と未要約のまま残ったコンテキストが次のコンテキストウィンドウへ引き継がれ、作業はシームレスに続きます。エージェントには、早めに切り上げたりタスクの途中で引き継いだりする必要はないと明示的に伝えられます。

これを補う詳細が2つあります：

• Scratchpad ディレクトリ（スクラッチパッド）：各セッションには、（/tmp の代わりに）すべての一時ファイル用となるセッション固有の scratchpad ディレクトリが与えられます — プロジェクトから隔離され、通常はパーミッションプロンプトなしで使えます。一時的な作業ファイルはメモリではなく、そこに置きます。
• 分業は明快です：要約はこのセッションの流れを保ち、メモリはセッションを超えて残すべきものを保ち、scratchpad はセッションを超えて残すべきでないものを保持します。

ハンズオン例

フォーマットの意図どおりに書かれた、現実的な feedback メモリの例です — 1つの事実、想起で使いやすい description、そして Why と How to apply を備えた本文：

# File: ~/.claude/projects/my-shop-app/memory/feedback_use-pnpm-not-npm.md
---
name: feedback_use-pnpm-not-npm
description: Always use pnpm in this repo — npm installs corrupt pnpm-lock.yaml
metadata:
  type: feedback
---

# Use pnpm, not npm

Confirmed on 2026-07-08 after a broken deploy.

## Why
The repo is a pnpm workspace. Running `npm install` writes a
package-lock.json and desyncs pnpm-lock.yaml, which broke the
CI install step (see [[project_ci-pipeline]]).

## How to apply
- All installs: `pnpm install`, never `npm install`
- Adding deps: `pnpm add <pkg>` in the relevant workspace package
- If package-lock.json ever appears, delete it and re-run `pnpm install`

そして MEMORY.md のインデックス行：

- [Use pnpm, not npm](feedback_use-pnpm-not-npm.md) — npm installs corrupt pnpm-lock.yaml

細部に注目してください：

• 絶対日付。「昨日確認した」ではなく「Confirmed on 2026-07-08」。相対日付は腐ります — 3か月後にこのファイルを読むとき、「昨日」には何の意味もありません。
• 宙に浮いたリンク。[[project_ci-pipeline]] はまだ存在しないかもしれません。それで構いません — 書く価値のあるメモリの目印になります。
• description が仕事をしている。 これは想起時の関連度判定に使われる行なので、トピックだけでなく事実そのものを述べています。

衛生ルール

メモリの品質は蓄積ではなくメンテナンスで保たれます。ルールは4つ：

1. 複製せず、更新する。 事実が変わったら既存のファイルを編集します。同じ事実について食い違う2つのファイルは、ファイルが1つもないより悪い。
2. 間違ったメモリは削除する。 誤りと判明したメモリはマイナスの価値しかありません。取り除きましょう。
3. リポジトリがすでに記録しているものは保存しない。 コード構造、git 履歴、CLAUDE.md にあるもの — それらの真実の源はリポジトリであり、常に最新です。それを写し取るメモリは定義上、陳腐化します。
4. 相対日付は絶対日付に変換する。「先週」は「2026-07-01」になります。

何が変わったか

永続メモリ以前	永続メモリ以後
すべてのセッションがゼロから始まる	キュレーションされた事実がプロジェクトごとに永続する
好みや落とし穴を毎回説明し直す	user と feedback メモリがそれらを引き継ぐ
学んだコンテキストはセッションと共に消える	1事実1ファイルがセッションを生き延びる
チャットログが唯一の記録（ノイズだらけで巨大）	MEMORY.md インデックス：1事実につき1行
CLAUDE.md がガラクタ入れになる	ルール、経験、手順 — 分離されたレイヤー
コンテキスト上限でハードな圧縮	要約が作業をウィンドウ間で引き継ぐ

キーインサイト

メモリはキュレーションされた知識であって、チャットログではありません。

この設計は、あらゆるレベルで同じ選択を繰り返しています：蓄積するのではなく、蒸留する。1ファイル1事実は、各メモリを意図的で編集可能な単位にすることを強制します。インデックスとファイルの分離により、常時ロードのコストは1事実につき1行に抑えられます — スキルをスケールさせたのと同じ「名前は前もって、内容はオンデマンドで」という哲学です。衛生ルールが存在するのは、メモリの失敗モードが「忘れること」ではなく、もはや真実でないことを自信満々に覚えていることだからです。

想起が「従うべき指示」ではなく「再検証すべき背景コンテキスト」として届くのも、同じ理由です。良いメモリシステムはエージェントに過去を信頼させるのではなく、過去を安価に検証できるようにするのです。

次のセッション

セッション 30 では Deferred Tools & ToolSearch を扱います — スキルとメモリですでに2度見てきた「名前は前もって、定義はオンデマンドで」という哲学がツール面全体へと一般化された経緯、そしてそれが大きなツールカタログを持つ MCP サーバーにとって最も重要である理由を解説します。