コーディングエージェントに画像を溜め込まないためのVisual Storeを作った

Wed, 16 Sep 2026 18:55:53 +0900

Visual Storeというローカル画像ストレージを作りました。

コーディングエージェントでUIの実装やブラウザーの描画を確認していると、スクリーンショットを何枚も撮ることがあります。その画像をすべて会話へ表示していると、画像そのものだけでなく、会話履歴のデータ量も増えていきます。

今回は、画像を保存することと、AIに画像を見せることを分けるための仕組みを作りました。

きっかけはCodexの長期セッション

以前、Omoikaneの開発をCodexで長時間続けていたところ、デバッグ用のスクリーンショットが会話履歴へ大量に蓄積しました。

そのときの調査内容は、大量の無圧縮PNGを含むCodexの長期セッションでremote compactが失敗したので復旧したに書いています。

有効なコンテキストを調べると、画像は次のような状態でした。

PNG 40枚
画像本体 約42 MB
Base64 data URL 約56 MB

このPNGを画素を変えずに再圧縮したところ、画像本体は約277 KBまで縮みました。その後、同じセッションでremote compactを成功させることもできました。

ただ、この方法はすでに会話履歴へ入ってしまった画像を後から修復するものです。そもそも、デバッグ画像を撮るたびに全部を会話へ入れる必要はありません。

そこで、保存した画像を参照IDで管理し、必要になったときだけ一枚を取り出すことにしました。

保存する画像と見る画像は別

デバッグ中には、次の二つの要求があります。

この画像は後で調べるために保存しておきたい

今この画像をAIに見せたい

これは同じではありません。

例えばブラウザーのレンダリング比較で100枚のスクリーンショットを撮ったとしても、100枚をすべてその場でモデルへ渡す必要はありません。撮影した画像を残し、ラベルやフレーム番号から候補を絞り、差分がありそうな一枚だけ確認すればよい場合もあります。

Visual Storeでは、次のような流れにします。

画像を保存
 ↓
参照IDだけ受け取る
 ↓
一覧やメタデータから対象を絞る
 ↓
必要な一枚だけ取得
 ↓
その時点で初めて画像を表示

保存しただけでは画像を表示しません。CLIも画像本体やBase64を標準出力へ流さず、小さなJSONだけを返します。

これは、画像ファイルを小さくすればモデルの画像トークンも同じ割合で減る、という話ではありません。画像の保存サイズと、モデルが画像を見たときのコンテキスト消費は別です。Visual Storeが扱うのは、保存した画像を無条件に会話へ入れないことです。

Visual Storeの構成

Visual StoreはRustで実装した単一のローカルCLIです。CLI名はvstoreです。

メタデータはSQLiteで管理し、画像やVP9セグメントの物理データはローカルファイルシステムへ保存します。ネットワークサービスではなく、実行時にFFmpegやImageMagick、APIキー、ネットワーク接続も必要ありません。

画像は物理ファイルのパスではなく、次のような論理参照で扱います。

visual://<store_id>/images/<image_id>

参照IDにはcodecや物理ファイルの場所を入れていません。画像の保存形式がPNGからVP9セグメントへ変わっても、画像のimage_idと参照は変わらないようにしています。

SQLiteでは、観測した画像と、その画像の現在の保存表現を分けています。

images
 観測そのもの。image_id、run、stream、frame_no、メタデータ

representations
 現在有効なPNGまたはVP9セグメント

segments / frame_locations
 VP9セグメントと、その中のフレーム位置

blobs
 SHA-256で管理する物理データ

この分離があるので、保存形式の変更と観測履歴の変更を別に扱えます。

開発ツール

コーディングエージェントに画像を溜め込まないためのVisual Storeを作った

きっかけはCodexの長期セッション

保存する画像と見る画像は別

Visual Storeの構成