Sougen Blog

Claude Code の記憶を /checkpoint と /bye でファイルに残す

claudeaiworkflowmemory

Claude Code で新しいセッションを始めたり /clear したりすると、それまでの会話は新しい文脈へ引き継がれません。
同じ指摘を毎回くり返さずに済むよう、セッションの区切りで「次に役立つこと」をファイルに書き出させています。
書き出しには、自作のスラッシュコマンドを 2 つ使います。

どちらも ~/.claude/commands/ に置いた Markdown のファイルで、中身は Claude への指示書です。
指示書を公開用に整えた版を、checkpoint.md と bye.md として置きました。
手元の版から、記憶の置き場所を ~/.claude/memory/ に、jj のコマンドを git に置き換え、自作の hook に関わる手順を外しています。
使うときは、2 つとも ~/.claude/commands/ に保存し、~/.claude/CLAUDE.md に @~/.claude/memory/MEMORY.md の 1 行を足します。

残すものを 4 種類に絞る

コマンドの指示書には、保存する情報と保存しない情報の基準を書いています。

### 保存すべき情報の判断基準

以下に該当するものがあれば保存する（なければスキップ）：

- **user**: ユーザーの役割・知識・好みで新たに判明したこと
- **feedback**: ユーザーが承認・修正した非自明なアプローチ（なぜそうするかの理由も含めて）
- **project**: 誰が何をいつやるか、意思決定の背景、締め切り等
- **reference**: 外部システム・ URL・ドキュメントの場所

### 保存しないもの

- コードパターン・アーキテクチャ（コードから読める）
- git 履歴・直近の変更（git log から読める）
- 一時的なタスク状態・今セッションだけの情報
- CLAUDE.md に既に書かれていること

コードや git の履歴は元の場所から読み直せるうえ、記憶に写すと、元が変わったあとも古い内容が残ります。
記憶には、コードからは読めない判断の理由や、人から言われた指摘を残します。

feedback には、指摘をそのまま書くだけでなく、なぜそう言われたのか（Why）と、次にどう当てはめるか（How to apply）を添えさせています。
たとえば、compact の前に /checkpoint を使うことについては、次の記憶があります（frontmatter を除いた本文）。

コンテキストが逼迫したとき `/compact` を直接実行するのではなく、先に `/checkpoint` でメモリ保存を行う。

**Why:** `/compact` は会話履歴を圧縮するため、その後で「何を覚えるべきか」を判断しようとしても材料が失われている。`/bye` の目的（記憶の保存）が半減する。

**How to apply:** Stop フックで `/compact` を提案するときは必ず「先に `/checkpoint`、次に `/compact`」の順序をセットで案内する。コマンド説明文にも「`/compact` 前に実行」と明記する。

理由が書いてあると、似ているが条件の違う場面で、記憶を当てはめるかどうかを判断できます。

1 つの事実を 1 つのファイルに書き、索引から引く

記憶は ~/.ai-shared/memory/ に、1 つの事実につき 1 つの Markdown ファイルとして置いています。
ファイルの頭には、YAML の frontmatter で name、description、metadata.type を書きます。
同じディレクトリの MEMORY.md が索引で、1 つの記憶を 1 行のリンクと短い説明で並べます。

索引は、グローバルの CLAUDE.md（~/.claude/CLAUDE.md）に @~/.ai-shared/memory/MEMORY.md と書いて読み込ませています。
CLAUDE.md の中で @ に続けてパスを書くと、そのファイルの中身も起動時に読み込まれます。
起動するたびに索引が文脈に入り、Claude はそこから関係のありそうな記憶のファイルだけを開きます。
2026 年 10 月の時点で、記憶のファイルは 685 個、索引は 125 行です。

置き場所を ~/.ai-shared/ にしたのは、Claude Code 以外のエージェントとも共有するためです。
Codex CLI、opencode、Gemini 系の CLI の設定ファイル（それぞれの AGENTS.md）には、セッションの始めにこの索引を読むよう書いています。
Claude Code で受けた指摘を、ほかのエージェントも守るようになります。
書き込むのは Claude Code の /bye と /checkpoint で、ほかのエージェントは覚えたいことを見つけても提案するだけにしています。

索引は毎回の起動で読み込まれるので、長くなるほど起動直後の文脈が重くなります。
200 行を超えたときには、超えた分が読み込みで切り捨てられることを、自作の hook が警告しました。
そこで、関連する記憶を topic_*.md という話題ごとのファイルにまとめ、索引からはそのファイルへの 1 行だけを残すようにしました。
個別の記憶のファイルは消さず、話題のファイルから [[ファイル名]] と書いたリンクでたどれるようにしています。

/bye は保存の前にやり残しを確かめる

/bye は、記憶を書く前に次のことを確かめさせます。

push は、そのセッションで push してよいと言われているときだけ jj git push で行います（バージョン管理には jj を使っています）。
言われていなければ、push 待ちのコミットも残っている作業として挙げます。
残っている作業があれば、終える前に「今やるか」を聞かせます。

/checkpoint はこの確かめを省き、保存だけをしてセッションを続けます。
長い作業の途中で記憶を書き出しておきたいときや、compact が走る前に使います。
compact は、文脈が上限に近づいたときや /compact を打ったときに、会話を要約に置き換える機能です。
先に compact が走ると、何を覚えておくべきかを判断する材料が消えてしまいます。

索引は書き換えずに追記する

運用を始めてしばらくして、索引に足したはずの記憶が 4 件消えたことがありました。
あるセッションが索引を整理している間に別のセッションが記憶を書き足すと、整理した側は読み込んだ時点の索引で全体を書き直すので、足された行が消えます。
足した側には、書き込みに成功したと表示されます。

この経緯を残した記憶には、書き込みの成功表示だけで判断せず、足したらすぐに grep で自分の行を確かめる手順も書いています。

今は、索引への書き足しをファイル全体の書き換えではなく、シェルの >> による追記にさせています。

cat >> ~/.ai-shared/memory/MEMORY.md <<'EOF'
- [索引への追記方法](feedback_memory_index_lost_update.md) — 並行セッションの整理で追記が消えた
EOF

追記にすれば、書き足す側が古い内容で索引全体を書き戻すことはなくなります。
ただし、別のセッションが索引全体を整理し直せば、追記した行もやはり消えます。
足した直後に grep で自分の行を確かめる手順を残しているのは、そのためです。

大きな文脈では書き込みを 1 回にまとめる

/checkpoint は、文脈が大きくなってから呼ぶことが多いコマンドです。
Claude Code は、ツールの結果を受け取って次の API 要求を送るたびに、その時点の文脈全体を要求に含めます。
会話の大半はプロンプトキャッシュから読まれるので、料金は通常の入力の 5%（Opus 5.5 の場合）で済みます。
それでも文脈が 30 万トークンあれば、1 要求ごとに 30 万トークン分のキャッシュ読み出しがかかります。
記憶 1 件ごとに既存のファイルの確認、本体の書き込み、索引への追記と 3 回ずつ順番にツールを呼ぶと、その回数だけこの読み出しが重なります。

そこで指示書では、保存する事実を先に全部決めさせ、書き込みを 1 回の Bash にまとめさせています。
新しく書くか既存の記憶を直すかは、文脈に入っている索引を見て先に決めさせます。
たとえば、新しい記憶を 1 件書く Bash は次の形になります。

cat > ~/.ai-shared/memory/feedback_example.md <<'EOF'
---
name: feedback-example
description: ...
metadata:
  type: feedback
---
...
EOF
cat >> ~/.ai-shared/memory/MEMORY.md <<'EOF'
- [例](feedback_example.md) — ...
EOF
head -3 ~/.ai-shared/memory/feedback_example.md

索引の MEMORY.md は起動時に文脈へ入っているので、保存のたびに読み直させません。
既存の記憶を一部だけ直すときにかぎり、ファイルを編集するツールを使わせます。

こうして書き出した記憶は、次のセッションの起動時に索引から引かれます。
/clear や新しいセッションで会話が引き継がれなくても、一度した指摘は Claude Code にもほかのエージェントにも残ります。