Claude Memoryツールで複数セッション開発を再開するパターン

セッションが切れるたびに作業が振り出しに戻るとき

エージェントに数日がかりの開発を任せると、セッションが切れた時点でそれまでの理解が消えます。新しいセッションはコードベースを読み直し、過去の設計判断を推測し直すところから始まります。

この問題に対して、Messages APIのMemoryツールで「あらかじめ決めた形のメモリファイルを残す」運用パターンがあります。狙いは、各セッションが前のセッションの記録した状態から正確に再開できることです。Memoryを単なるメモ帳ではなく、復旧の仕組みとして設計します。

ここで扱うMemoryツールは、Messages APIに自分で組み込む機能です。Claude Codeが自動で書き溜めるメモリや、Fable 5にシステムプロンプトだけで教訓を書かせるメモリシステムの運用パターンとは別物です。両者の違いはClaudeの記憶の仕組みにあります。

メモリの置き場所は自分のアプリ側にある

Memoryツールはクライアント側で動きます。Claudeがファイル操作を要求し、実際にファイルを読み書きするのはアプリケーションです。リクエストのtoolsに次の1行を足すのが設定のすべてで、入力スキーマは書きません。

{"type": "memory_20250818", "name": "memory"}

/memoriesは、アプリ側の実ストレージに対応づけるための接頭辞にすぎません。ユーザーごとのディレクトリでもデータベースのキーでも構いません。複数セッションの再開には次の条件がかかります。

• 後のセッションが同じtoolsの指定でリクエストを送る
• ハンドラが同じストアを返す

プロジェクトごとにストアを分けておけば、別プロジェクトの進捗を取り違える事故を避けられます。ハンドラの実装は、PythonとTypeScriptのSDKにローカルファイル版(BetaLocalFilesystemMemoryTool)が付属しています。Python版は次の形です。

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool
 
client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")
 
runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "決済APIの実装を続けてください。"}],
    tools=[memory],
)
final_message = runner.until_done()

Memoryツール自体にベータヘッダーは不要です。ヘルパーとツールランナーがSDKのbeta名前空間にあるだけです。ツール呼び出しループの扱いはTool RunnerでAnthropic APIのツール呼び出しループを自動化するにあります。6つのコマンドの返却文字列はClaude Memoryツールの6コマンド実装で扱っています。

初期化セッションで3点を用意する

最初のセッションでは、実質的な作業に入る前に次の3点を用意します。

1. 進捗ログ: 何が完了し、次に何をするか
2. 機能チェックリスト: 作業のスコープそのもの
3. 起動・初期化スクリプトへの参照: プロジェクトが必要とする起動手順

ファイル名や書式は実装側で決める部分です。次は一例で、これが唯一の正解ではありません。

/memories/progress.md       ← 進捗ログ(完了/次にやること/直近の判断理由)
/memories/checklist.md      ← 機能チェックリスト(スコープと完了条件)
/memories/setup.md          ← 起動・初期化スクリプトの場所と実行方法

progress.mdは時系列の追記式にすると、後続セッションが読みやすくなります。

## 2026-09-01 セッション1
- 完了: 決済APIクライアントの雛形作成
- 未着手: 認証まわり
- 次にやること: OAuthトークンの取得処理から着手する
 
## 2026-09-02 セッション2
- 完了: 認証実装
- 未着手: リトライ処理
- 次にやること: 429応答時の指数バックオフを実装する

checklist.mdはスコープと完了条件を対にして書きます。「実装した」ではなく「何をもって完了とみなすか」まで書いておけば、終了時更新で完了マークを付けてよいかを判断できます。

初期化の詳しい事例は、Anthropicのエンジニアリングブログ「Effective harnesses for long-running agents」にあります。初期化スクリプト・進捗ファイルの構造・Gitを使った復旧まで載っています。Memoryツールのドキュメントも、このパターンの詳細な事例としてそこを挙げています。

後続セッションの最初の一手は、API側が指示している

Memoryツールをtoolsに含めると、APIがシステムプロンプトに次の趣旨の指示を自動で足します。自分で書く必要はありません。

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
   - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

後続セッションのClaudeは、この指示に従ってまず/memoriesをviewします。返ってくるのはサイズ付きのファイル一覧です。ハンドラ側の実装が返す形式は、ドキュメントでは次のように示されています(サイズとパスの間はタブ)。

Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:
{size}	/memories
{size}	/memories/progress.md
{size}	/memories/checklist.md

初期化セッション側に目を向けると、空のストアへの最初のview /memoriesはエラーではありません。SDKのローカルファイル版は、呼び出しの前にメモリのルートを作り、空ディレクトリ自身の1行を返します。存在しないパスをviewしたときの文言はThe path {path} does not exist. Please provide a valid path.です。

準備が足りないと、この自動指示は空振りします。進捗ログとチェックリストが無いストアをviewしても、Claudeは何も復元できず、コードベースの再探索に戻ります。

進捗ログが育って長くなったら、viewが返す文字数に上限を設ける手があります。ドキュメントは、残りをview_rangeで読み進めさせる構成を挙げています。[10, -1]のように書けば、10行目から末尾までを読めます。

終了時更新で「完了」の線を守る

セッションが終わる前に、進捗ログを「何を完了し、何が残っているか」で更新します。これで次のセッションが正確な出発点を持てます。省略すると、進捗ログは初期化時点の情報のまま古びていきます。

このパターンの原則は、一度に1つの機能だけを進めることです。ある機能を「完了」と記録してよいのは、エンドツーエンドの検証で動作を確かめたときだけで、コードを書き終えた時点ではありません。

線引きが緩むと、後続セッションが「完了しているはずの機能」の上に積み増して壊す事故につながります。

決済APIを3セッションで進める例

決済APIの実装を3セッションに分けた場合の流れです。

各セッションが読むのは、前セッションの詳細な作業ログではなく、要約された状態とスコープだけです。会話ログを持ち越さないので、セッションをまたいでもコンテキストウィンドウは圧迫されません。

運用で引っかかりやすい点

セッションの再開が失敗する原因は、パターンの外側にもあります。ドキュメントが挙げる注意を、複数セッション運用の目で並べます。

ファイルが乱雑になるときは、整理を促す一文をプロンプトに足す手があります。ドキュメントの例は「メモリフォルダを編集するときは、内容を最新で整合した整理された状態に保つ。不要になったファイルは名前変更や削除をしてよい。必要な場合を除き新規ファイルは作らない」という趣旨です。

複数のセッションをAgent SDKで回す場合は、そのセッションがプランの利用上限をどう使うかも確認点になります。詳細はClaude Agent SDKはプランの利用上限を消費するかにあります。

その場しのぎで書いたメモリは何が問題か

このパターンを使わず、Claudeにその場その場で自由にメモリファイルを書かせた場合に起きやすい問題を2つ挙げます。これはパターンの狙いから逆算した見立てで、公式の記述ではありません。

1つ目は、ファイルの粒度と役割がセッションごとにばらつくことです。あるセッションはnotes.txtに何でも書き込み、別のセッションはtodo.mdを新設します。すると後続セッションは、どのファイルに現在の状態があるのかを推測する羽目になります。進捗ログとチェックリストの役割をあらかじめ固定しておけば、この推測は要りません。

2つ目は、「完了」の基準が揺れることです。実装が終わった時点で完了と書くセッションと、検証まで終えてから書くセッションが混ざります。一度に1機能と検証後の完了を全セッションで共有して、進捗ログは無条件に信頼できる情報源になります。

Context editingやCompactionと組み合わせる

長時間稼働するエージェントの文脈管理には、Memoryのほかに、Context editingとCompactionがあります。どれも今の会話のなかで効くか、会話をまたいで残るかで性質が分かれます。

Memoryのドキュメントは、長時間稼働するエージェントでCompactionとMemoryの併用を検討するよう勧めています。Compactionで文脈を小さく保ち、要約を越えて残す情報だけをMemoryに書く、という分担です。複数セッション開発のパターンは、その「要約を越えて残す情報」を進捗ログとチェックリストの形に定型化したものと読めます。

要約でsystem promptのプロンプトキャッシュまで無効になる問題は、Compactionとプロンプトキャッシュを両立させるcache_controlの置き方で扱っています。長時間セッションのトークンコストを抑える別の手段としては、Anthropic APIのPrompt Cachingを理解するがあります。

まとめ

メモリファイルは作業の途中で書き足すのではなく、初期化セッションで進捗ログとチェックリストの形を決めておきます。そのうえで、後続セッションが同じストアを読めることと、「完了」を検証済みの事実だけに限ることの2点が、再開の信頼性を左右します。