記憶・状態・障害復旧

複数段階の実行では、決定・成果物の版・検証記録・結果不明の操作が生まれます。情報の用途と保存期間を分け、チェックポイントと条件付き更新を組み立て、中断後に実際に継続できるかを検証します。

ライフサイクルと用途の分離

モデルのパラメータは、トレーニングによって得られた能力と知識を担います。アプリケーションの状態は、本タスクの入力、決定、ファイル、実行結果を担います。現在のコンテキストは、今回の推論で実際にアクセス可能な材料であり、通常は保存された状態の一部にすぎません。「あるインターフェースでは履歴を明示的に渡す必要がある」ということから「モデルの全知識が履歴から来る」と導き出すことはできません。また、「要約」を天然に揮発性のデータと見なすこともできません。

「短期記憶」とは、時に1つのスレッドにのみ属する状態を指すことがあり、必ずしもRAMを指すわけではありません。例えば、LangGraph はスレッドのチェックポイントとスレッド間のストアを区別していますが、メモリ実装自体はプロセス再起動後も保持されません。適切な永続バックエンドを選択する必要があります。LangGraph Persistence

毎回増大する履歴を再送信すると、単発の入力は履歴の増加に伴って増大し、マルチラウンドタスク全体の累積入力量はさらに急速に増加する可能性があります。各ラウンドで h トークンが追加され、n ラウンド分の追加履歴を再送信する場合、そのカウントは h×n(n+1)/2 となります。プレフィックスキャッシュは計算やコストを変化させる可能性はありますが、この履歴がコンテキストを占有するという事実を消すことはできません。ウィンドウ管理については コンテキストエンジニアリング を参照してください。

チェックポイントに保存すべき内容

チェックポイントは、復元プログラムが「現在の目標は何か、どのアクションが確実に完了したか、どのアクションの結果が不明か、次のアクションの前に何をチェックすべきか」という問いに答えられるものでなければなりません。最終的な自然言語の要約だけを保存すると、これらの境界情報が失われることがよくあります。

エージェントがインポーターの修正を行っていると仮定します。パッチをコミットし、ユニットテストを実行済みですが、再起動後の復元テストはまだ行っていないとします。以下のようなアプリケーション独自のカスタムレコードを採用できます。

{
  "task_id": "importer-fix-42",
  "revision": 7,
  "state": "running",
  "goal": "重複インポートを修正し、既存のインターフェースを維持する",
  "artifacts": [{"path": "src/importer.py", "revision": "patch-3"}],
  "verified": [{"check": "unit", "artifact_revision": "patch-3",
                "report": "artifacts/unit-patch-3.txt"}],
  "pending": ["restart-recovery-test"],
  "unknown_operations": [],
  "next_action": "patch-3 とテストレポートを確認し、復元テストを実行する"
}

revision はこの状態記録のバージョンを示し、artifact_revision はテスト対象の成果物のバージョンを示します。これらは同じカウンターではありません。実際のシステムでは、コミットID、コンテンツハッシュ、または独自のバージョン識別子を使用できますが、対応するコンテンツを特定可能でなければなりません。

復元時は、まずチェックポイントを読み取り、成果物が存在し、バージョンが一致しているかを確認します。もしファイルがすでに patch-4 に変更されている場合、古いテスト結果は patch-3 に対してのみ有効であり、「すべての検証が完了した」としてそのまま続けることはできません。最後に unknown_operations を処理します。リモートへの書き込み操作が送信されたが応答が失われた場合、まずその実際の状態を照会し、盲目的に再実行してはいけません。副作用の復元境界については エージェントループ を参照してください。

チェックポイントと外部操作は通常、同じトランザクション内にはありません。完了を記録してから実行すると、記録が事実よりも先行するウィンドウが生じます。実行してから完了を記録すると、事実が記録よりも先行するウィンドウが生じます。これらは、「チャットの履歴が自動的に保存される」ことで重複実行が解消されると信じるのではなく、業務の冪等キー、結果の照会、または共通トランザクションなどのメカニズムを使用して処理する必要があります。

候補事実から有効な記憶へ

将来の行動に影響を与える情報を保存する

長期保存に適しているのは、安定しており再利用価値のある情報です。例えば、「本プロジェクトのリリース成果物には互換性レポートを添付しなければならない」といった情報です。あるツールの数千行に及ぶ完全な出力は、通常、一次証拠として保存する方が適しており、記憶には結論と位置情報のみを保持します。これらは両立可能であり、毎回長い履歴を再読み込みする必要を避けることができます。

1つの記憶エントリは、少なくとも内容、適用範囲、出典を説明できるものでなければなりません。

「1つの事実につき1つのファイル」という形式は手動管理には便利ですが、必須要件ではありません。データ量が多く、並列処理や複雑なフィルタリングが必要な場合、データベースのエントリの方が適しているかもしれません。重要なのは、エントリが独立して位置指定、更新、撤回可能であり、検索時に出典と範囲を保持することです。

記憶の書き込みにもエラーが発生する可能性がある

モデルが「ユーザーは常に非常に短い回答を好む」と言った場合、それは単に1つのタスクから推測された好みかもしれません。その推測性質を保持し、推測をユーザーの恒久的な承認に格上げしてはいけません。新しい要求と古い記憶が競合する場合、まず作用範囲と時間を判断します。明確な新しい決定は、古いエントリに取って代わるべきであり、2つの競合する記録が同時に有効になるべきではありません。

繰り返し要約を行うと、限定条件が徐々に失われることがあります。例えば、原文が「テスト環境では承認をスキップできる」であっても、2回目の要約で「承認をスキップできる」となると、権限の意味が変わってしまいます。このような制約については、原文の位置限定と範囲を保持する必要があります。記憶を検索した後でも、現在のタスクと権限に基づいて検証を行う必要があります。

Claude の memory tool は、クライアント側の実行インターフェースです。モデルがファイル操作を要求すると、アプリケーションは論理的な記憶パスを自前のストレージにマッピングし、結果を返します。ツールを宣言しただけでは、永続化が実装されたわけでも、サービスがテナントと権限を自動的に管理しているわけでもありません。Memory tool

2 実行器で状態が上書きされる仕組み

ストレージが壊れなくても、各々妥当な2回の書込で更新は失われます。CAS は判断に使った版を条件に含めます。拒否後は古い更新の版番号だけ変えず、再計算します。

バージョン付きの更新とマージ

なぜ「読み取り後に上書き」すると決定が失われるのか

A と B がともにバージョン v7 を読み取り、A が「レポートに出典を添付する」を追加し、B が「記録の時間範囲を記録する」を追加したとします。両者が同じファイル全体を上書きする場合、B の後書き込みの内容が A の変更を消去してしまう可能性があります。1回の書き込みの原子性（アトミック性）を保証しただけでは、古いバージョンを基にした変更の問題は解決できません。

1つの方法は条件付き更新です。送信時に読み取りバージョンを添付し、ストレージはバージョンがまだ一致している場合にのみ書き込みを行い、バージョンをインクリメントします。競合が発生した場合は、再読み取りして、2つの変更をマージできるかどうかを判断します。相互に排他的な決定に関わる場合は、ビジネスルールに従って解決する必要があり、機械的に連結してはいけません。

以下に、一時的な SQLite データベースを使用して条件付き更新を実演し、接続を閉じた後に再開いて保存結果を検証する例を示します。2人の編集者の古いバージョンは、シーケンシャルな送信によってシミュレートされます。これは並列負荷テストや停電テストではありません。

import sqlite3
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as directory:
    path = Path(directory) / "memory.sqlite"
    db = sqlite3.connect(path)
    db.execute("""CREATE TABLE memory (
        owner TEXT, key TEXT, version INTEGER NOT NULL, value TEXT,
        PRIMARY KEY(owner, key))""")
    db.execute("INSERT INTO memory VALUES (?, ?, ?, ?)",
               ("user-1", "report-rule", 7, "記録の時間範囲"))
    db.commit()

    def update(expected, value):
        with db:
            cursor = db.execute("""UPDATE memory
                SET value=?, version=version+1
                WHERE owner=? AND key=? AND version=?""",
                (value, "user-1", "report-rule", expected))
            return cursor.rowcount == 1

    assert update(7, "記録の時間範囲、および出典を添付")
    assert not update(7, "古いバージョンによる上書き")
    db.close()

    reopened = sqlite3.connect(path)
    row = reopened.execute(
        "SELECT version, value FROM memory WHERE owner=? AND key=?",
        ("user-1", "report-rule")).fetchone()
    assert row == (8, "記録の時間範囲、および出典を添付")
    reopened.close()
    print(row)

SQLite の UPDATE は、WHERE 句を満たすレコードのみを変更し、一致するレコードがない場合は SQL エラーにはなりません。そのため、影響を受けた行数を確認する必要があります。SQLite UPDATE 例では owner が信頼できるアプリケーション側に固定されていますが、実際のサービスでは、認証された身份からアクセス可能な範囲を導出する必要があり、モデルのパラメータが他人の owner を指定できるようにしてはいけません。

条件付き更新は、サイレントな上書きを防ぎますが、マージ後の内容が本当に正しいことを保証するものではありません。より厳格なシステムでは、バージョン履歴、監査、削除フラグも必要です。バックアップから復元したり、インデックスを再構築したりする際には、撤回されたエントリが古いコピーによって再読み込みされないようにする必要があります。

復元テストと隔離の境界

永続化、検索、正しい使用をそれぞれテストする

保存と読み取りの成功は、第一関門にすぎません。「閉じて開き直せば継続できる」という验收では、否定された方案を繰り返し探索していないか、ユーザーの制約が保持されているか、未完了タスクと実際の成果物が一致しているかもチェックする必要があります。長時間実行されるエージェントのエンジニアリング経験では、進捗記録、環境チェック、検証可能な増分的な成果物の重要性も強調されています。Effective harnesses for long-running agents

ファイルディレクトリは完全な権限モデルに代えられない

自己管理型のファイル記憶では、ルートディレクトリの制約、パスの解決、シンボリックリンクの処理、書き込みの競合に対処する必要があります。resolve() を実行してから open() を行うチェックには時間的ギャップがあり、並列変更が可能なディレクトリでは、チェック後に置換が発生する可能性があります。1回の文字列またはパスのチェックを、完全なファイル隔離ソリューションと見なすことはできません。実行身份、ディレクトリ権限、および適切な制限付きファイル操作メカニズムが、境界を共同で担う必要があります。

記憶に秘密鍵の本文を保存するのは適していません。資格情報は、専用の資格情報管理コンポーネントによって提供されます。エントリ内のドキュメントリンクやリソースハンドルも、使用時に権限をチェックする必要があります。検索前にユーザー、プロジェクト、および権限範囲に基づいてフィルタリングを行い、データベース全体を取得してからモデルに「他のユーザーのデータを見てはいけない」と要求してはいけません。これらの要件は、セキュリティと保護 のツール境界と連携して機能します。

状態を復元しても根拠は有効か

復旧では信頼できる事実の境界を再構築します。ファイル名や要約が同じでも現内容を検証したとは限りません。版やハッシュへの紐付けで古い根拠を検出します。

次に読む：権限・信頼・ツールの境界。