エージェントメモリ向け chDB Durable Layer

手元に戻ってこなかった状態 #

私たちの取り組みは、ある問題から始まりました。

私たちは、ClickHouse を搭載した組み込み SQL OLAP エンジンである chDB の上にエージェントメモリを構築していました。1 台のノート PC 上でコーディングエージェントを何週間も稼働させており、組み込みの chDB には大量の状態が静かに蓄積されていました。プロジェクトのルール、ユーザーの好み、2 度改訂された決定事項、それらの決定の根拠となった生の文字起こし、そしてどのタスクでどのメモリが想起(リコール)されたかを示すトレースなどです。この仕組みはうまく機能していました。想起はローカルのクエリで済み、データをマシンの外に出す必要もありませんでした。

しかし、話は 1 台のノート PC だけでは収まらなくなりました。同じメモリを CI 環境や、1 時間で消去される可能性のあるサンドボックス内、さらには 2 台目のノート PC でも利用できるようにする必要が生じたのです。その瞬間から、ローカルディスクを前提とした設計が課題となり始めました。メモリはあるディスク上の MergeTree ディレクトリに存在しており、そのディスクは他のどこにも存在しなかったためです。

私たちが最初に取った解決策は、バックエンドとして ClickHouse サーバーを追加することでした。これによってポータビリティは解決したものの、最も気に入っていた利点が失われてしまいました。想起がローカルの関数呼び出しではなく、ネットワークラウンドトリップになってしまったのです。ツール呼び出しのたびに、認証情報、接続管理、リモートレイテンシのコストを支払わなければならなくなりました。かつては単なるディレクトリだったものが、運用するか料金を支払って借りる必要のあるサービスへと変わってしまったのです。

これにより、ローカルの単一マシン向けストレージとクラウドデータベースサーバーの間にギャップが生じました。エージェントメモリに求めていたのは、もっと軽量なものでした。想起のたびにリモートクエリを走らせることなく、ユーザーにサーバーの運用を求めることもなく、自身が保有するストレージへ復元可能な分析状態をパブリッシュできる方法です。

要件はシンプルになりました。状態が生成元のホストよりも長く存続できる、ローカルの分析用データベースが必要だったのです。それこそが chDB Durable Layer が解決する問題です。chDB の周囲に設けた小さな耐久性レイヤーであり、オブジェクトストレージ内に復元可能な状態を保持します。

現在のエージェントメモリの一般的な取り扱い方 #

chDB Durable Layer の詳細に入る前に、現在エージェントメモリが一般的にどのように保存されているかを確認しておくと役立ちます。以下の選択肢はいずれも間違っているわけではありません。それぞれが課題の異なる部分に優れており、そのギャップこそが chDB Durable Layer の存在領域を定義しています。

組み込みキー・バリューストアの状態:SQLite チェックポインタとシンプルなメモリストア。 これは一般的かつ合理的な出発点です。LangGraph には SqliteSaver があり、OpenAI Agents SDK には SQLiteSession があります。このパターンでは、ローカルストアがセッション間でランタイムの状態や小さなファクトを保持するため、エージェントは中断した箇所から処理を再開できます。これらのシステムは小規模で、トランザクションに対応し、組み込み可能で成熟しています。

不整合が生じるのは、メモリが「履歴」となったときです。あるメモリの出所はどこか、どの文字起こしがそれを裏付けているか、どの古い見解を置き換えたのか、役に立たなかった想起はどれか、失敗したツール呼び出しが不正な状態を生み出していないか、といった点を調べたくなりました。こうした問いに答えるには、フィルタリング、グルーピング、ソート、結合、監査証跡、バッチ想起が必要です。これらは、追記専用(append-only)のメモリ、トレース、会話履歴に対する OLAP クエリです。SQLite はチェックポイントを保存できますが、その履歴を分析するのに適した形状ではなく、依然として 1 台のマシン上のファイルやディレクトリに縛られがちです。

レプリケーションされたローカル SQLite:SQLite と Litestream の組み合わせ。 Litestream は SQLite 用のレプリケーションツールです。WAL ファイルをオブジェクトストレージへ継続的にコピーするため、新しいプロセスがバケットからデータベースを復元できます。これにより SQLite における単一ディスクの問題は解決します。しかし、依然として行ストアのデータベースであり、運用すべきレプリケーションプロセスが存在することに変わりはありません。

サーバーデータベースまたはメモリプラットフォーム:Postgres、pgvector、サーバーサイドの ClickHouse、Letta、mem0 Platform、Zep Cloud。 チーム規模でのデプロイ、複数のライター、共有サービスにおいては、多くの場合これが適切な選択肢となります。共有アクセス、一元管理された運用、真の同時実行性が得られます。トレードオフは、エージェントがリモートサービスに依存することです。ネットワーク呼び出し、認証情報、接続管理、そして誰かが運用しなければならないシステムが必要になります。主に 1 台のマシン上で動作する単一ユーザーまたは単一プロジェクトのメモリにとっては、復元可能なコピーを保持するためだけに用意するインフラとしては過剰になりかねません。

ベンダー保有の耐久性状態:Cloudflare Durable Objects。 Durable Objects はエレガントな構造を持っています。各オブジェクトがアイデンティティ、シングルスレッド実行、バインドされた永続ストレージを備えています。このアイデンティティと単一ライターのモデルは、私たちが求めていたものに近いものでした。トレードオフは、ベンダーへの依存とストレージの透明性の低さです。オブジェクトはプラットフォームの境界の奥深くに存在し、モデルは組み込みの列指向分析というよりもアプリケーション状態に近いものです。

ローカルの組み込み OLAP DB:DuckDB または chDB。 ローカル OLAP は高速で、サーバーレスであり、快適に使用できます。これこそが、私たちが維持したかったホットパスそのものです。残る問題は、冒頭の話に戻りますが、状態が依然として 1 つのディスク上のディレクトリにすぎない点です。

最後の行こそが、これまで欠けていた形状です。インプロセス OLAP のホットパスを維持し、正となるコピーを自身が保有するストレージに配置し、データベースサーバーや PVC、サイドカーを不要にします。

chDB Durable Layer:ローカルの作業コピーとバケット上の正のコピー #

chDB Durable Layer は、アドレス指定可能で単一ライター構成の、復元可能な組み込み分析オブジェクトです。各オブジェクトは完全な chDB データベースです。名前空間内で名前を指定して開き、ローカルでクエリを実行し、ローカルの状態をいつ永続化するかを選択できます。

durable エクストラを指定して chDB 4.4 以降をインストールします。これには S3 バックエンドが含まれます。GCS と Azure Blob はそれぞれ別のエクストラを使用します。

1pip install "chdb[durable]"

以下のシーケンス図は、Durable がローカルの状態をバックアップし、別のマシン上で復元する流れを示しています。

エンドツーエンドの例:書き込みと復元 #

インターフェースは小規模です。5 つの要素で構成されています。

その境界線について明確にしておく価値があります。

• 単一ライターです。ユーザーやプロジェクトごとに 1 つの「頭脳」を持つ構成においては、これは有用な特性です。チームで共有するデータベースとしては不向きなツールです。
• V1 WAL は書き込みステートメントをリプレイするため、それらのステートメントは決定的(deterministic)である必要があります。典型的な避けるべき例としては、now() を呼び出す INSERT ステートメントが挙げられます。
• OLTP データベースではなく、Postgres の代替でもありません。高頻度のポイント更新やマルチライターのトランザクションは、他のシステムで処理すべきです。

単なるストレージバックエンドにとどまらない価値 #

単に「このチェックポイントを保存する」ことだけが要件であれば、SQLite がすでにそれを実現しています。新たなバックエンドを追加すること自体には、それほど大きな面白みはありません。

chDB Durable Layer がもたらすのは、これまで欠けていたデプロイメントの形態です。復元可能な作業コピーに対する組み込み OLAP を実現し、自身が保有するストレージに正となるコピーを配置し、その間にサービスを一切介在させません。

• ローカルコンピュート:ホットなクエリはエージェントプロセス内に留まります。
• 分析に適したレイアウト:MergeTree は圧縮された追記専用の履歴、バッチ想起、フィルタリング、集計、ベクトル支援検索に適しています。
• ポータブルな耐久性:同じオブジェクトを別のノート PC、CI、または短命なサンドボックス内で復元できます。
• 明示的な制御:アプリケーションはいつ flush() を呼び出し、いつ checkpoint() を呼び出すかを自ら決定します。
• 運用の不要なサービス:データベースサーバー、PVC、レプリケーション用サイドカーは不要です。 SQLite はローカル状態の消失を防ぎます。chDB Durable Layer は、ローカルの分析状態を復元可能な状態に保ちながら、エージェントがそれをローカルで分析し続けられるようにします。

実際の運用で得られるメリット #

chDB Durable Layer を構築する中で、エージェントメモリに適している理由として 3 つの特性が常に際立っていました。

ホットクエリをローカルに維持し、決定事項のみを永続化する。 負荷の高い分析処理は chDB プロセス内に留まります。Durable Layer は、確定したメモリ、改訂内容、チェックポイント、およびそれらを裏付ける証拠など、マシン間で引き継ぐ価値のある状態のみをパブリッシュします。

chDB クックブックの chDB アナリストのデプロイ レシピでは、Lambda、Lambda MicroVM、Cloud Run、Azure Container Apps、E2B にわたるこの運用モデルが示されています。エージェントランタイムは、秒単位またはミリ秒単位のライフサイクルコストで作成、復元、一時停止、破棄ができるため、コンピュートインスタンス自体を耐久性のある存在にする必要はありません。私たちの ローカル対リモートのベンチマーク では、ローカルクエリはリモートクエリよりも 58 倍高速でした。これも重要なポイントの半分を占めています。ホットな想起処理がリモートデータベースへのラウンドトリップになってはならないのです。

追記専用メモリは圧縮効率に優れる。 エージェントメモリの大部分は、メッセージ、ツール呼び出し、ツールの結果、トークン数、改訂履歴、証拠などの追記専用 JSONL です。小規模なローカル実験では、213,721 行からなる 1.45 GB の Claude Code 文字起こしサンプルを MergeTree にロードしたところ、ZSTD(3) では 521 MiB に、LZ4 では 991 MiB に圧縮されました。

テキストの圧縮率は非常に良好でした。容量を消費していたのはスクリーンショットでした。行数としては全体のわずか 0.8% にすぎないものの、このサンプルにおけるバイト数の約 3 分の 2 を占めていました。バイナリ blob をテーブルの外に置き、参照情報のみを型定義されたカラムに保持すべきなのはこのためです。

モデリング前に生の JSONL をクエリする。 chDB は file(..., JSONAsString) を直接クエリできるため、スキーマを決定する前に文字起こしデータの内容を検査できます。これは開発の初期段階で役立ちます。イベントタイプのカウント、ツール名の検索、コストの高い呼び出しの特定などを行ったうえで、プロジェクト、タイムスタンプ、モデル、ツール、トークン、コストなどの頻出フィールドを MergeTree の型定義されたカラムへと昇格させます。

以下の 2 つのクエリカードはその形状を示しています。1 つのクエリは生のイベントタイプをグルーピングし、もう 1 つはインポート手順を踏むことなく同じ JSONL コーパスを検索しています。

他の開発者たちも同じパターンに気づいています。Subara3 による ccsql は、Claude の JSONL を型定義された MergeTree テーブルにロードし、コスト、ツール、キャッシュ、セッション、ヒートマップのレポートを出力します。また、claude-scope は Claude の履歴をローカルのダッシュボードへと変換します。これらのプロジェクトは取り込みとクエリの側面を示しており、Durable は結果として得られる MergeTree 状態にポータビリティのレイヤーを追加します。

ベストプラクティス #

これらのパターンは、システムの構築経験および以下のプロジェクトから得られたものです。

メモリを 1 つのドキュメントではなく、追記専用テーブルとしてモデリングする。 有用なテーブルとしては、現在の見解を保持する memories、改訂履歴の行を保持する memory_history、コールドな文字起こしやツール出力を保持する raw_evidence、何が想起されそれが役立ったかを保持する recall_traces、互いに矛盾する意味的に近い行を保持する conflicts、そして tool_events などがあります。version またはタイムスタンプを付けて行を追記します。論理削除はフラグで行います。現在の状態は ORDER BY version DESC LIMIT 1 BY memory_id によって導出します。エージェント向けローカルデータエンジン の記事では、現在状態のクエリ、全履歴のクエリ、ポイントインタイムクエリについて解説しています。

生の証拠データはコールドかつ圧縮された状態に保ち、blob は外部に置く。 文字起こしやツール出力は、CODEC(ZSTD(3)) を適用して raw_evidence に格納します。通常、テキストは約 4 分の 1 に圧縮され、ホットパスから読み出されることもありません。スクリーンショットなどのバイナリペイロードは外部バケットに配置し、テーブル内にはキーのみを保存するようにします。そうしないと、チェックポイントの容量の大部分をそれらが占めることになります。フィルタリングやグルーピングに使用されるカラムは型定義し、適宜 LowCardinality を使用することで、ホットクエリが JSON に触れる必要をなくします。

毎行ではなく、意味のあるバッチごとにフラッシュする。 エージェントの書き込みは、多くの場合、小さなイベントのストリームとなります。作業コピーにそれらを吸収させ、タスクの完了時、ツールループの終了時、あるいは N 件のメモリ確定後といった境界で flush() を呼び出します。フラッシュの間隔が、許容するデータ損失の範囲となります。

コンパクションのタイミングでチェックポイントを作成する。 チェックポイントを作成する適切なタイミングには、一括インポートの後、多数の改訂が発生した後、長時間のセッション終了時、あるいはオブジェクトを別のホストへ渡す前などが含まれます。新しいベーススナップショットを作成することで次回のオープンが高速化し、ログを短く保つことができます。

オブジェクト名ごとに 1 つのライターを使用する。 リースによってこれが強制されるため、アプリケーション側でもこの設計に従う必要があります。2 つのワーカーが同時に書き込む必要がある場合は、2 つのオブジェクトを使用するか、サーバーデータベースを使用します。

ユーザーまたはプロジェクトごとに 1 つの名前空間を使用する。 Namespace("s3://bucket/agent-memory", owner=...) と、user-123 や org/repo などのオブジェクト名を組み合わせることで、障害ドメインを小さく抑え、プレフィックス操作による削除を可能にし、将来的にオブジェクトを一覧表示したりクエリしたりする余地を残せます。

サーバーを使用すべきタイミングを把握する。 マルチライターによるコラボレーション、多数のクライアントからのミリ秒未満のポイント更新、ローカルディスクを超える作業セット、または一元化されたコンプライアンス管理が必要な場合は、サーバーサイドの ClickHouse や Postgres を使用してください。その場合でも SQL や MergeTree のレイアウトは引き継ぐことができ、remote() を利用すればアプリケーションを書き換えることなく移行パスを確保できます。

例:ClickMem #

ClickMem は、今回の取り組みに注力するきっかけとなったプロジェクトであり、Durable のユースケースを最も明確に示す例です。

ClickMem は、自らを「チャット履歴ベクトルデータベース」化することを意図的に避けています。自動的にメモリになるものは一切ありません。ファクトがストアに追加されるのは、ユーザーやエージェントが clickmem_remember を使用して明示的に送信したとき、または AGENTS.md や .cursor/rules/*.mdc などの精査されたドキュメントがインポートされたときのみです。生の文字起こしはコールドな証拠データとして保持され、検索や監査は可能ですが、メモリとしてコンテキストに注入されることはありません。その基盤の上で、拡張(expand)、改訂(revise)、縮小(contract)、強化(reinforce)、拒否(refuse)の 5 つの操作からなる見解改訂モデルが動作します。新しいメモリが既存のメモリと意味的に近く、かつ内容が矛盾する場合、誰かが解決するまで両方の行に競合(conflict)マークが付けられます。各想起では、なぜその結果が一致したのかを説明するトレースを生成できます。

データモデリングの観点から見ると、これはまさに上述したテーブル群そのものです。確定したメモリ、改訂履歴、コールドな文字起こし、競合行、想起トレースに加え、プロジェクト、プライバシー、ラベル用のスコープが含まれます。ClickMem のダッシュボードは履歴に関する問いに答えます。この見解はどのように変化したのか？ 未解決の競合はどれか？ なぜこの想起結果が一致したのか？ どの文字起こしからこのメモリが生成されたのか？ キー・バリューストアではなく、chDB と MergeTree 上で動作している理由はここにあります。

現在、ClickMem には 2 つのストレージモードがあります。単一マシンまたは LAN 共有ホストでは、~/.clickmem/data 配下の組み込み chDB を使用します。複数のデバイス間では、ClickHouse サーバーを介してメモリを共有できます。また、頭脳を手動で移行するための埋め込みを含む export / import 機能も備えています。

chDB Durable Layer は、これら 2 つの形態の間に第 3 の選択肢を追加します。ホットパスは組み込みのままであり、想起はローカルクエリとして行われます。各ユーザーまたはプロジェクトの正となるコピーは、そのユーザー自身のバケットに存在します。同じオブジェクトを後から別のノート PC 上で開くことも、プロジェクトのルールを必要とする CI ジョブ内で開くことも、1 時間で破棄されるサンドボックス内で開くことも可能です。確定したメモリのバッチごとにフラッシュし、インポートや競合解決の処理後にチェックポイントを作成し、プロジェクトごとに 1 つのオブジェクトを使用します。こうすることで、メモリストアが最初に構築されたマシンに依存しなくなります。

同じ問題の別の 3 つの形態 #

エージェントメモリは分かりやすい例ですが、同じパターンは、組み込み分析データベースが使い捨てのキャッシュではなくなるあらゆる場面で見られます。

Maple Local:ローカルファーストのオブザーバビリティ。 Maple Local はトレース、ログ、メトリクスを受信し、chDB を組み込んで、ローカルクエリとダッシュボードを提供します。データベース内に数日間にわたって収集されたテレメトリが含まれるようになると、耐久性は製品機能となります。クラッシュリカバリ、ダーティストアリカバリ、チェックポイント、復元などです。Durable はそうしたリカバリパターンをデータベースレイヤーに移管し、アプリケーション側でいつフラッシュするか、いつチェックポイントを作成するか、各オブジェクトをどのように命名するかを決定できるようにします。

ReplayHouse:リプレイバッファと学習状態。 ReplayHouse は、ローカル処理に組み込み chDB を使用する ClickHouse ベースのリプレイバッファです。トラジェクトリとスコア付けされたロールアウトを保存し、重み付けされた学習バッチをサンプリングし、学習エラーを優先度として書き戻し、トレーナーが消費したデータを正確にクエリします。これはワークフローの途中に存在する、不可視の長期的な状態です。リプレイバッファには、長時間の実行を通じて収集された貴重な経験が含まれています。Durable を使用することで、バッチ、エポック、またはマイルストーンの境界でフラッシュを実行し、ノート PC から CI、さらには学習マシンへと移行できるようになります。エンジンは引き続き chDB であるため、サンプリング分布や優先度のドリフトを SQL で検査できます。

vcfclick:コストの高いインポート後にすぐクエリできるデータ。 vcfclick は、組み込み ClickHouse 上に構築されたバイオインフォマティクス研究用の VCF データベースであり、DuckDB によるアノテーションと MCP 自然言語レイヤーを備えています。生の VCF ファイル自体は、すでに別の場所に安全に保存されている場合があります。コストがかかる貴重な資産は、インポート、正規化、アノテーション、インデックス作成が完了し、クエリ可能な状態に準備されたデータです。耐久性のあるチェックポイントがなければ、新しいマシンごとにそのインポート作業を繰り返す必要があります。チェックポイントがあれば、準備済みのコホートデータベースに対して一度チェックポイントを作成するだけで、どこでもローカルのクエリコピーとして再オープンできます。

現在のステータスと今後の予定 #

Durable V1 コントラクトは、各種バインディング間で共有されるようになりました。chDB 4.4 では、S3 互換ストレージ向けの chdb[durable] に加え、ネイティブの GCS および Azure Blob 向けの chdb[durable-gcs] と chdb[durable-azure] を含む Python 実装が提供されています。Node、Go、Rust でも、chdb@3.4.0、chdb-go/v2@2.2.0、chdb-rust@2.0.0 を通じて同じオブジェクトレイアウトとライフサイクルが公開されています。

これらはすべて、chdb-core 26.7.3 の Durable V1 コンポーネント(バックアップ、復元、ステートメント分類、head.json、WAL、チェックポイント、CAS、リースの挙動、エラーカテゴリ、クロスバインディングフィクスチャ)をベースに構築されています。あるバインディングで書き込まれたオブジェクトは、同じコントラクトに対応する別のバインディングから復元できるように設計されています。

ローカルファーストのエージェントシステムにおいて、その構造はシンプルです。データベースサーバーも、PVC も、レプリケーション用サイドカーも不要であり、想起のたびにリモート呼び出しが発生することもありません。データベースは組み込みのまま維持されます。状態はマシンよりも長く存続します。

エージェントメモリに真に必要なのは、より大きなコンテキストウィンドウというよりも、環境の移行に耐えうるローカルの分析的な頭脳なのかもしれません。

次に試すこと #

• pip install "chdb[durable]" をインストールし、所有するバケット上に名前空間を開いて、既存の chDB メモリテーブルをそこにアタッチします。
• 実際に動作する分かりやすい例については、durable-agent-memory クックブックレシピ を参照してください。
• Durable コントラクトの全体像と実装の詳細については、chdb durable ドキュメント を参照してください。
• ユースケース、質問、または設計に関するフィードバックがある場合は、chdb-io/chdb でディスカッションを開始してください。