メモリとペイロードのライフサイクル

ZeroClaw は、ターンの実行中にいくつかの種類の「記憶された」情報を保持します。これらはすべてが同じ所有者、永続性、プライバシー境界、レビューリスクを持つわけではありません。

変更がメモリ、履歴、セッションの永続化、ツール結果、ファイル、メディア添付、要約、コンテキストのトリミング、またはプロンプトの組み立てに関わる場合は、このページを参照してください。最も重要な問いは「エージェントはこれを記憶しているか?」ではなく、「どのサーフェスがこのデータを所有し、どれだけ存続するのか?」です。

何が何を所有するか

この表は Runtime state and persistence を補完するものです。あちらのページでは状態がどこに存在するかを説明していますが、このページではユーザー向けのペイロードがメモリ、履歴、ツール、ファイル、メディア、プロバイダーリクエストをどのように移動するかを説明します。

長期記憶

エージェントはメモリファクトリからメモリハンドルを受け取ります。共有バックエンドと Markdown ストレージでは具体的なレイアウトが異なりますが、レビュー規則は同じです。メモリアクセスは、ランタイム内部 で説明されているエージェントのアイデンティティと設定済みのピア許可リストに拘束されたままでなければなりません。

情報が永続的なメモリになる通常の方法は2つあります:

• エージェントが memory_store などのメモリツールを呼び出します。
• ランタイムコードが、設定された会話の自動保存パスなど、メモリエントリを明示的に保存します。

デフォルトでは、プロンプトコンテキスト、ツール出力、ファイル、ログを永続メモリとして扱わないでください。それらのサーフェスのいずれかを永続化する PR では、メモリカテゴリ、セッションスコープ、エージェントスコープ、保持動作、およびオペレーター可視のコントロールを明記する必要があります。

プロンプトコンテキストと再呼び出し

ターン開始時に、ランタイムは関連するメモリを想起し、有界な [Memory context] ブロックをユーザー可視のプロンプトコンテキストに注入できます。関連するエントリポイントがすべて同一のフィルタを適用するわけではありません。チャネル/インタラクティブループは、ターンに安全なセッションスコープがない場合、またはユーザー起点でない場合に、生成されたオートセーブノイズ、古い <tool_result> ブロック、および Conversation エントリをフィルタします。汎用メモリ読み込みはオートセーブノイズと関連性をフィルタしますが、それ自体ではチャネルループの Conversation 除外を強制しません。

したがって、プロバイダーへのリクエストには、現在のターンを新しいメモリにすることなく、呼び出されたメモリを含めることができます。プロンプト組み立ての変更を確認するには、次の点を確認してください。

• どのメモリバックエンドとエージェントスコープがクエリされたか。
• 会話エントリが許可されている場合に、クエリがセッションスコープであるかどうか。
• 自動保存によるノイズ、古いツール結果ブロック、関連性の低いエントリがフィルタリングされたままかどうか。
• ユーザーまたはオペレーターが、古いコンテキストが削除されたタイミングを確認できるかどうか。

セッション履歴とトリミング

セッション履歴は、会話の連続性を記録するものです。チャットメッセージ、アシスタントのツール呼び出し、ツールの結果を含めることができます。これは長期メモリとは異なるものです。

履歴管理がトリミングの仕組みを担います。このページではライフサイクルの境界を示すだけです。トリミングは、プロバイダーから見える/セッションから見えるコンテキストに対する損失を伴う変更であり、メモリの削除ではありません。また、古いコンテキストが引き続き利用可能であるかのように暗黙のうちに振る舞うのではなく、可視化されなければなりません。

バイト数の節約よりもツール呼び出しのペアリングが重要です。履歴の変更によって、対応する tool_result を伴わない tool_use がプロバイダーリクエストに残ってはならず、その逆も同様です。

ツールの結果

ツールは小さな構造化された結果として success、output、error を返します。ディスパッチャーはこれらの結果を次のモデル呼び出し用のプロバイダーメッセージに変換し、一方でストリーミングクライアントはターン中に関連付けられた ToolCall および ToolResult イベントを受け取ることができます。

ツール結果のペイロードは過剰に保持されがちです。レビュー担当者は以下を確認してください:

• 結果の最大サイズ（max_tool_result_chars を含む）。
• 切り捨てが構造化されたエンベロープと画像マーカーを保持するかどうか。
• 検索・一覧ツールが付随的な画像パスをメディアペイロードに変換しないようにするかどうか。
• レシート、ログ、オブザーバーイベントが生の機密出力ではなく、範囲を制限しサニタイズされた証跡を保持しているかどうか。
• 結果が現在のターン/セッション履歴にのみ残るのか、それともメモリにも意図的に書き込まれるのか。

PR がツール結果を「記憶された」と述べている場合、それがプロバイダー可視の履歴、永続化されたセッション履歴、メモリバックエンドの行、ファイルアーティファクト、レシート、またはログイベントのいずれを意味するのかを明記するよう要求する。

ファイルとメディア

ファイルの内容とメディアバイトはペイロードであり、メモリではありません。ファイルシステムの所有者は、Filesystem コンポーネント および Runtime 内部 で説明されているエージェントごとのワークスペースポリシーです。ファイルの読み取りはコンテンツをツール結果またはプロンプトに配置できます。ファイルの書き込みは永続的なファイルシステム状態を作成できます。どちらも自動的にメモリ行を作成することはありません。

受信チャネルメッセージは、ファイル名、バイト列、およびオプションの MIME タイプを持つ MediaAttachment 値を含むことができます。MediaKind は MIME タイプまたはファイル拡張子から導出されます。低レベルの添付ファイルローダーは呼び出し元が指定したパスをそのまま読み取るため、信頼できないパスを受け入れる呼び出し元は、読み込み前にそれらのパスを検証または制約する必要があります。

ファイルとメディアについて、レビュアーは次を確認してください：

• 読み取りおよび書き込み前のワークスペースポリシーの適用。
• ユーザー、HTTPリクエスト、チャネルペイロード、またはツール引数から取得したパスに対するパス検証。
• 不足しているファイルや読み取り不能なファイルに対する、境界付きのバイト処理と明確な失敗動作。
• プロンプトに大容量またはバイナリのペイロードが入る場合は、明示的な要約または参照を使用してください。
• 長期メモリへの添付ファイルやファイル内容からのサイレントコピーは行いません。

ログと可観測性

オブザーバーイベントとランタイムログは、何が起きたかを説明するのに役立ちます。これらは隠れたペイロードストアになってはいけません。メモリリコールイベントは、スクラブ済み/切り詰められたクエリサマリーとカウントを保持します。メモリストアイベントは、制限付きカテゴリとバックエンド識別子を保持します。

ツール呼び出しの可観測性には特別な注意が必要です。シンクは単一のペイロードコントラクトを共有していないためです。現在の型付きツール呼び出しオブザーバーイベントは、完全な引数と認証情報を除去した完全な結果出力を伝送でき、OTel はそれらの値をスパン属性へ転送します。コードが実際にそれをバウンドまたは要約していない限り、そのパスを「サマリー」と表現しないでください。新しいテレメトリでは、バウンドされた識別子、カウント、期間、成功フラグ、およびオペレーターにとって有用なサマリーを優先すべきです。生のコンテンツをログやオブザーバーイベントに含めるのは、機能が明示的に必要とし、かつプライバシー境界が文書化されている場合のみにしてください。

レビュー担当者向けチェックリスト

メモリ、ペイロード、履歴、ファイル、またはメディアの変更については、レビュアーのサインオフ前にこれらに回答してください:

• データの正規の所有者は何ですか？
• それは現在のターンのみ、セッション永続、ファイルシステム永続、メモリ永続、またはログ永続ですか？
• どのエージェント、セッション、チャネル、またはワークスペースのスコープがアクセスを制限しますか?
• 呼び出し元は、設定された許可リストを超えてメモリリコールを広げることができますか？
• 自律ジョブはチャット由来の会話メモリを参照できますか？
• ツール出力、ファイルバイト、メディアバイト、プロンプトサイズを制限するものは何ですか？
• トリミングや切り捨てによって損失がサイレントではなく可視になりますか？
• プロバイダー可視のペイロードは、永続メモリ書き込みから分離されていますか？
• ログとオブザーバーイベントはスクラブされ、バウンドされていますか？
• PR が生成されたまたは派生したペイロードを変更する場合、生成された出力を手編集するのではなく、ソースオーナーを更新していますか？

ソースポインタ

正規ドキュメント:

• ランタイム状態と永続化
• 履歴管理
• ランタイム内部構造
• 関係性メモリ
• ツールレシート

主要なコードエントリポイント:

• メモリトレイトとエントリの形状: crates/zeroclaw-api/src/memory_traits.rs
• メモリファクトリとエージェントスコーピング: crates/zeroclaw-memory/src/lib.rs、crates/zeroclaw-memory/src/agent_scoped.rs、および crates/zeroclaw-memory/src/agent_scoped_markdown.rs
• メモリツールのレジストリと例: crates/zeroclaw-tools/src/lib.rs (MEMORY_TOOL_NAMES)、crates/zeroclaw-tools/src/memory_store.rs、および crates/zeroclaw-tools/src/memory_recall.rs
• プロンプトの想起と注入: crates/zeroclaw-runtime/src/agent/memory_inject.rs（想起ポリシーと [Memory context] レンダラー）は、crates/zeroclaw-runtime/src/agent/turn/mod.rs でエンジン側に注入されます。ターンごとのメモリハンドルは crates/zeroclaw-runtime/src/agent/loop_.rs を通じて受け渡されます
• 履歴トリミングとツール結果ペイロードの整形: crates/zeroclaw-runtime/src/agent/history.rs、crates/zeroclaw-runtime/src/agent/history_trim.rs、および crates/zeroclaw-runtime/src/agent/turn/results_collect.rs
• ツールとプロバイダーのメッセージ形状: crates/zeroclaw-api/src/tool.rs と crates/zeroclaw-api/src/model_provider.rs
• チャンネル添付: crates/zeroclaw-api/src/channel.rs および crates/zeroclaw-api/src/media.rs