Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-005 title: メモリーストレージはバックエンドに依存せず、SQLiteをデフォルトとする date: 2026-07-14 status: 承認済み relates-to:

  • ADR-002
  • docs/book/src/foundations/fnd-001-intentional-architecture.md
  • docs/book/src/foundations/fnd-002-documentation-standards.md
  • https://github.com/zeroclaw-labs/zeroclaw/issues/6850
  • crates/zeroclaw-api/src/memory_traits.rs
  • crates/zeroclaw-memory
  • crates/zeroclaw-config/src/schema.rs

ADR-005: メモリストレージはバックエンド非依存で、SQLiteをデフォルトとする

これは、正式なADRプロセスが導入される前に発展したアーキテクチャの遡及的な記録です。この記録では、当初の決定が行われた正確な日付は確認できません。上記の日付は、このADRがアーキテクチャドキュメントに追加された日付です。

FND-002 は当初、この決定を SQLite と Markdown を 2 つのメモリーバックエンドとして選択するものと説明していました。その説明では、より広範な契約をもはや捉えられません。この記録では、バックエンド数を固定するのではなく、永続的なアーキテクチャについて説明します。

コンテキスト

ZeroClaw は、異なる運用上の制約を持つインストール環境間で永続的なメモリを必要とします。ローカルの単一プロセスエージェントは、サービス依存のない組み込みストアの恩恵を受けます。オペレーターは、人間が判読可能なファイルシステムストア、共有データベース、ベクターデータベース、または他のメモリシステムとの統合を必要とする場合もあります。

これらのストアは、スキーマも運用上の特性も同一ではありません。それでも、メモリ操作とスコープ設定については、1つのランタイムインターフェースを提供する必要があります。個々の操作では、バックエンド固有の機能セマンティクスを持たせることができます。たとえば、Markdown メモリは追記専用であり、エントリを削除しません。ターン処理は具体的なデータベース型に依存してはならず、バックエンドを追加する際に、プロンプトの組み立て、統合、ハイジーン、エージェント認可ポリシーをそのバックエンドにコピーする必要があってはなりません。

現在のリポジトリは、SQLite、Lucid、PostgreSQL、Qdrant、Markdown ストレージに加え、永続メモリを無効にする none を認識します。SQLite がデフォルトです。FND-001 では、最終的な最小ランタイムに望ましいベースラインストアとして SQLite と Markdown を別途指定しています。このパッケージング目標は、ストレージ契約を 2 つの実装に限定するものではありません。

決定

メモリの永続化は、バックエンドに依存しない契約を通じて選択され、デフォルトのバックエンドとして SQLite が使用されます。

ストレージコントラクト

具象ストアは zeroclaw-api の Memory トレイトを実装します。このトレイトは、バックエンドに依存しない永続化操作とエントリのセマンティクスを担います。呼び出し側は、ターン処理コードで SQLite、Markdown、PostgreSQL、Qdrant、Lucid ごとに分岐するのではなく、Memory ハンドルを使用します。

バックエンド構築は現在、2つの重複した設定レベルを参照しています。agents.<alias>.memory.backend は Markdown および none の構築パスのみを直接ルーティングし、同一バックエンド共有検証で使用されるカインドを提供します。その他すべてのエージェントごとの値はインストール全体のファクトリを経由し、memory.backend が具体的な型付き storage.<kind>.<alias> エントリを選択します。レガシーの裸の名前は default エイリアスに解決されます。この ADR は、その重複を理想的な最終状態として扱うことなく、その相互作用を記録します。ランタイムコンポーネントは、サポートされていないエージェントごとの選択を推論したり、別の保存済みセレクターを作成したりするのではなく、現在のファクトリおよび検証のオーナーシップに従う必要があります。

SQLiteは、永続的なローカルストレージ、ハイブリッド検索、外部サービス不要という利点を提供するため、引き続きデフォルトとなっています。他のバックエンドは、それぞれ異なるストレージ、デプロイ、可読性、または統合の特性が必要な場合に選択できます。noneは永続メモリを無効にする明示的な要求であり、暗黙的なフォールバックではありません。

どちらかのセレクターを変更しても、既存のデータは移行されません。バックエンドの種類間でデータを移動するには、あるストアを別のストアとして暗黙的に再解釈するのではなく、明示的な移行手順が必要です。

ライフサイクルポリシー

ストレージバックエンドは、プロンプトの構築やターンポリシーを所有しません。ターンエンジンがメモリコンテキストの選択とレンダリングを所有します。MemoryStrategy は Memory ハンドルの上位における統合とガバナンスのための指定された境界ですが、その境界への移行は完了していません。一部のパスは、依然として低レベルのライフサイクル関数を直接呼び出しています。Issue #6850 で残りの整合作業を追跡しています。バックエンドの実装は、それらのライフサイクルルールの長期的な所有者になることなく、ストレージと取得の動作を提供します。

エージェントのスコープ

メモリのスコープは、具体的なストアとは独立してエージェントのアイデンティティに紐付けられます。SQLバックエンドのストアは内部UUIDを使用する場合があり、非SQLストアはエージェントのエイリアスを直接使用する場合があります。エージェントスコープアダプターはバックエンドをエージェントに紐付けており、エージェントをまたいだリコールは、設定済みのallowlistを通じ、かつ対象エージェントが同一のバックエンドを使用している場合にのみ許可されます。呼び出し元はそれらのアダプターを迂回したり、バックエンド固有の識別子が同一の表現を持つと推測したりしてはなりません。

このADRは、特定のバイナリにどのバックエンド実装を同梱するか、または将来のバックエンドがネイティブか、機能フラグで制御されるか、プラグインによって提供されるかを決定しません。それらはパッケージングおよびプラグインライフサイクルに関する決定事項です。安定した制約は、サポートされるすべてのバックエンドが共通のストレージおよびエージェントスコーピングコントラクトを維持することです。

結果

肯定的な結果:

  • エージェント、チャネル、ゲートウェイ、およびツールのコードは、1つのメモリインターフェースに依存できます。
  • SQLite は、組み込みストレージを唯一のデプロイメントモデルにすることなく、有用なローカルのデフォルトを提供します。
  • オペレーターは、ターン処理の呼び出し元を変更することなく、埋め込み型、ファイルベース、共有データベース、またはベクトルストレージを選択できます。
  • プロンプトの構築、統合、および整理は、すべてのストレージ実装にライフサイクルポリシーメソッドを追加することなく進化できます。
  • エージェントの分離は、バックエンド固有の識別子とストレージモデルをまたいで、呼び出し元から見える単一のコントラクトを持ちます。

否定的な結果:

  • バックエンド実装は、ストレージモデルとクエリモデルが異なる場合でも、共通のエントリ契約とスコープ契約を維持する必要があります。
  • 呼び出し元は、追記専用ストアや、未サポートまたは no-op の動作を報告するトレイト操作などの機能差を考慮する必要があります。
  • バックエンドの種類間での移行には明示的なデータ移動が必要です。構成済みのバックエンドを変更しても、既存のデータが新しいストアに現れることはありません。
  • オプションのサービスや機能は、ほとんどの呼び出し元が共有トレイトしか参照しない場合でも、検証マトリックスを拡大させます。

フォローアップの決定:

  • Issue #6850 では、ストレージと上位のメモリライフサイクルポリシーの境界を扱います。
  • WASM メモリアダプターは、まだ設定可能なデーモンバックエンドではありません。そのランタイム構築とパッケージ化は、引き続き別個のプラグイン作業です。
  • クロスバックエンドマイグレーション、共有エージェントのリコール、またはストレージアイデンティティへの変更には、明示的な互換性レビューが必要です。

参照