メモリプラグインの作成

メモリプラグインはストレージバックエンドです。エージェントが記憶した内容を永続化し、リコールクエリに答えます。これは最もデータモデルが重いプラグインの種類です。ツールが1つの関数を持ち、チャネルがメッセージ形状を持つところ、メモリバックエンドはマルチエージェントの属性付け、名前空間、セッション、カテゴリ、重要度の重み付けを持ち、ランタイムのメモリセマンティクス（スコープ付きリコール、GDPRエクスポート、置換）は、行モデルを正しく実装することに依存しています。

このガイドは、ツールプラグインの基礎と、チャネルガイドで説明したウォームストアのライフサイクルを理解していることを前提としています。内容は wit/v0/memory.wit と、crates/zeroclaw-plugins/src/wasm_memory.rs 内のホストアダプターに照らして検証されています。

接続状況。 WasmMemory は memory-plugin ワールド向けにランタイムの完全な Memory トレイトを実装しており、ケイパビリティによる制御と単体テストによるカバーが行われています。ランタイムはまだこれを構成可能なバックエンドとして構築しておらず、ホストには channel_plugin_details() に対応するメモリ用のものがありません。チャネルと同様、コントラクトを基準に実装してください。固定されるのは WIT ワールドとアダプターのセマンティクスです。メモリワールドにはまだ設定エクスポートもないため、config_read を要求せず、型付き設定 ABI とリゾルバーが WasmMemory に組み込まれた後にのみ追加してください。

データモデル

1つのレコード型が両方向に境界をまたぎます。memory-entry（memory.wit）。ストレージを設計する前にそのフィールドを把握してください。オプションのメソッドはすべてそれらに対するビューだからです:

(key, agent-id) の複合キーは、最もよくある間違いです。ベースの get の契約では、次のように明示されています。複数の行が同じキーを共有する場合、任意の一致する行が返され、エージェントスコープのルックアップは get-for-agent を経由します。同様に、forget は帰属に関係なくキーに対応するすべての行を削除しますが、forget-for-agent は (key, agent-id) の行を正確に削除し、兄弟の行はそのまま残します。

必須エクスポート

12個の関数にはデフォルトがなく、動作する必要があります（memory.wit、required-methods セクション）：

recall-for-agents は agent-filter バリアントを受け取ります。all（エージェントフィルターなし）または some(list<string>)（リストされたエージェント ID に限定）のいずれかです。ランタイムは Rust の &[&str] スライスを、空スライスは all を意味するようにマッピングするため、some([]) はすべてではなく何にも一致しないものとして扱ってください。

機能フラグ: 11 個のオプションメソッド

チャネルと同じ仕組みです。ホストは get-memory-capabilities を一度だけ読み取り、設定されていない各フラグについては、あなたを呼び出す代わりに Rust トレイトのデフォルトを使用します。デフォルトは memory.wit 内のフラグの隣にインラインで記載されており、ホスト側のフォールバックは wasm_memory.rs で確認できます（各ゲート付きメソッドはフラグをチェックし、フラグがない場合はフォールバックパスを取ります）。

最後の行をもう一度読んでください。store-with-metadata を実装しない場合、ランタイムが要求した名前空間と重要度はフォールバックによってサイレントに破棄されます。名前空間付きのデータを保存するバックエンドは、store-with-metadata、recall-namespaced、purge-namespace を一式として実装すべきです。そうしないと、名前空間の分離は静かにポストフィルタリングと不可逆な書き込みへと劣化します。

purge ファミリーはデータ削除のためのインターフェイスです。purge-agent は（ID ではなく）agent-alias を受け取ります。export-entries は GDPR 第 20 条のデータポータビリティに対応するために存在し、作成時刻の昇順でエントリを返し、埋め込みは除外する必要があります。バックエンドが実際のユーザーデータを扱う場合は、purge および export のフラグを実装してください。「サポートされていない」という回答が許容されるのは、使い捨てのバックエンドの場合のみです。

スケッチ: ストレージの形

コンポーネントのパターンはチャネルと同じ（ウォームインスタンス、thread_local 状態）なので、異なるのはデータレイヤーだけです。最小限で誠実なバックエンドは、正しくキー付けされたインメモリマップです。

#![allow(unused)]
fn main() {
use std::collections::HashMap;

struct Row {
    id: String,
    content: String,
    category: Category,
    timestamp: String,
    session_id: Option<String>,
    namespace: String,
    importance: Option<f64>,
    superseded_by: Option<String>,
    agent_alias: Option<String>,
}

/// (key, agent_id) -> Row。agent_id の None は未帰属の行を表します。
type Table = HashMap<(String, Option<String>), Row>;
}

すべての必須メソッドは、その後、単純な走査になります:

• store-entry は名前空間 "default" で (key, None) に挿入します。
• store-with-agent は、呼び出し元の名前空間と重要度を使用して (key, agent-id) に挿入します。
• recall は content に対して部分文字列/ランクでフィルタリングし、セッションフィルタを適用し、timestamp に対して RFC 3339 の境界値（両端を含む）を適用し、ソートして limit で切り詰めます。空のクエリまたは * クエリは、最新のものから順に処理してください。
• recall-for-agents は、キーの2番目のコンポーネントに対するエージェントフィルターのウォークを追加します。

実際のバックエンドでは、コントラクトの形状を変更することなく、マップを組み込みストアに置き換えられます。メモリアダプタは、そのスコープが http_client を持つ場合でも、意図的にまだ wasi:http をリンクしていません。リモートバックエンドには、コンポーネントでテストされた別個のメモリとネットワークの境界が必要です。

ホストが周囲で行うこと

wasm_memory.rs におけるアダプターの動作を知ることで、いくつかのコントラクトのエッジが説明できます:

• ウォームストア、呼び出しごとに補給。 チャンネルと同じ: プラグインのライフタイムに1つのインスタンス、各呼び出しごとに新しい燃料、呼び出しは mutex の背後でシリアライズされます。バックエンドが同時呼び出しを見ることはありません。
• ロード時にキャッシュされるケイパビリティ。 ホストは from_wasm 中にフラグを一度だけ読み取り、その後は二度と読み取りません。動的なケイパビリティ検出はありません。デーモンを再起動することで再読み取りされます。
• トラップのラップ。 すべての呼び出しサイトは、名前付きコンテキスト（memory.recall-namespaced trapped など）でトラップをラップします。1回の呼び出しでのトラップはプラグインを破壊しませんが、繰り返しのトラップはバックエンドを無用にします。予期される失敗に対してはパニックする代わりに err(string) を返してください。
• ポストフィルタのフォールバックはホスト側です。 recall-namespaced フラグが未設定の場合、名前空間フィルターは recall が返した後にホスト上で実行されます。limit の処理がこれと相互作用します。ホストは呼び出し元の limit を recall に渡すため、ポストフィルタリングによって結果が埋まりきらないことがあります。名前空間付きバリアントをネイティブに実装するもう一つの理由です。

マニフェスト、ビルド、インストール

マニフェストとは、プラグインディレクトリ内にある manifest.toml という名前のファイルです。そのフィールドは crates/zeroclaw-plugins/src/lib.rs 内の PluginManifest の serde サーフェスであり、これが信頼できる情報源となります。

コードが実際に使用する権限のみを宣言してください。宣言されていない権限はコンポーネントが到達できないホストサーフェスであり、不要に宣言された権限は自ら求めた攻撃対象領域であり、プラグインをレビューする人にとっての監査負担です。

オペレーター値は plugins.entries 内では文字列のまま保持され、永続化時には、ホスト所有のパッケージ、ケイパビリティ、バインディングの識別情報から導出されたバージョン付きの zpi1_… 文字列をキーとして暗号化されます（インストール時に出力され、デフォルトのツールバインディングのフルインスタンスキーにシードされます）。文字列はそのまま保存され、ブール値と数値には JSON スカラーのテキストが使用され、配列とオブジェクトには JSON テキストが使用されます。ゲストコードが実行される前に、ホストはそれらの文字列をパッケージスキーマの型に実体化し、ツールアダプターとチャンネルアダプターについてオブジェクト全体を検証します。シークレットではないツールプロパティで __config が構成され、チャンネルは config.get を介してシークレットではないオブジェクトを取得します。x-secret = true とマークされたプロパティは両方の公開サーフェスから省略され、認可されたサービスフレーム内で secrets.get("property") を介してのみ利用できます。1 回の呼び出し中のチャンネルの公開読み取りとシークレット読み取りは単一の正規リビジョンを共有し、ホストは呼び出しの終了時にその実体化されたビューを破棄します。準拠するチャンネルプラグインは、利用する各時点でその両方を 必ず 解決し、ウォームなゲスト状態に設定や資格情報の値を保持してはなりません。ゲストに平文を返すと、ホストは悪意のあるコードに対して値を保持しないことを強制できなくなります。config_read が要求されたものの実効的に許可されなかった場合、ホストは空のオブジェクトを検証します。そのため、必須プロパティを持つスキーマは、必須設定なしで起動するのではなくフェイルクローズします。空のオブジェクトが有効な場合、ツールは空の __config を省略し、チャンネルの設定/シークレットインポートは access-denied を返します。認可されたフレーム外の呼び出し、解決失敗、ホスト呼び出し予算の枯渇は unavailable を返します。

メモリバックエンドの場合: capabilities に memory を含めます。まだ config_read を要求しないでください: 受け入れにはスキーマが必要ですが、現在のメモリワールドには、ホストが結果のオブジェクトを渡すためのエクスポートがありません。http_client にも依存しないでください: 権限付与だけではメモリアダプターの範囲を広げられず、現在はネットワークサーフェスを公開していません。

WASI Preview 2 ターゲットを一度インストールしてから、コンポーネントをビルドします:

rustup target add wasm32-wasip2
cargo build --release --target wasm32-wasip2

コンポーネントは target/wasm32-wasip2/release/<crate_name>.wasm に生成されます（クレート名のハイフンはアンダースコアに変換されます）。プラグインディレクトリを構成する際は、マニフェストの wasm_path で宣言した名前に変更してください。

[!IMPORTANT] コンパイル済みの .wasm および .cwasm ファイルはバイナリ成果物であり、多くの場合それぞれ数メガバイトになります。Git LFS を使わずに Git のソースツリーへコミットしないでください。リビルドのたびに素のブロブとしてコミットされると、リポジトリの履歴が永久的に肥大化し、git diff やレビューツールがそれらの処理でつまずきます。これらは他のビルド出力と同様に扱ってください。target/ と *.wasm/*.cwasm を .gitignore に追加し、代わりにリリース成果物やプラグインレジストリのアーカイブを通じて配布してください。どうしても成果物をツリー内に置く必要がある場合は、最初のコミットの前に LFS でパターンを追跡してください（git lfs track "*.wasm"）。

ターゲットホストがランタイム専用ビルド（JITバックエンドがコンパイルに含まれていない）の場合、ロード時に .wasm をコンパイルできません。代わりに事前コンパイル済みの .cwasm をデシリアライズします。ホストのバージョンと一致する wasmtime CLI で事前コンパイルし、.cwasm を wasm_path アーティファクトとして同梱してください。バージョンが一致しないアーティファクトは、wasmtime のデシリアライズチェックによって拒否され、サイレントに誤ロードされることはありません。

これらのコマンドには、プラグインホストをコンパイルして組み込んだバイナリが必要です。 インストーラーが配布するビルド済みリリースバイナリは plugins-wasm 機能なしでビルドされているため、そこでは zeroclaw plugin ... は認識されないサブコマンドとなり、インストール済みのプラグインは検出されません。プラグイン実行バックエンドを指定してソースからビルドしてください。例: cargo build --release --features plugins-wasm-cranelift。

各プラグインは、プラグインディレクトリ（デフォルト ~/.zeroclaw/plugins/、plugins.plugins_dir を通じて解決）の独自のサブディレクトリに配置され、マニフェストとマニフェストの wasm_path に一致する名前のコンポーネントを保持します:

~/.zeroclaw/plugins/
└── my-plugin/
    ├── manifest.toml
    └── my-plugin.wasm

ローカルディレクトリからインストール（これはマニフェストの形状を検証し、何かをコピーする前に署名ポリシーを実行します）:

zeroclaw plugin install ./my-plugin/

プラグインシステムを有効にして検出を確認する:

zeroclaw config set plugins.enabled true
zeroclaw plugin list
zeroclaw plugin info my-plugin

zeroclaw plugin list と zeroclaw plugin info は、パッケージがインストールされ、検出可能であることを確認しますが、検出は有効化を意味しません。plugins.enabled = true によってプラグインホストが有効になります。自動検出されたツールおよびスキルの機能は、plugins.auto_discover = true も設定されている場合にのみ実行時に読み込まれ、このフラグはデフォルトでは false です（フェイルクローズド）:

zeroclaw config set plugins.auto_discover true

したがって、plugins.enabled = true だけでは、[channels.plugin.<alias>] の下で宣言したチャンネルのみが有効になり、プラグインのツールやスキルは有効になりません。ツールまたはスキルのパッケージが zeroclaw plugin list に表示されていても、実行時には何も提供しないことがあります。明示的なチャンネルバインディングは自動検出ではなくオペレーターが名前を指定するものなので、auto_discover は不要です。このフラグが制御するのは、自動検出されたツールとスキルだけです。

zeroclaw plugin list にないプラグインは検出時にスキップされました: 起動ログでスキップ警告を確認してください（形式が不正なマニフェスト、wasm_path ファイルの欠落、または署名ポリシーによる拒否）。

次へ

• スキルバンドル: 同じインストール機構を通じた markdown のみのスキル配布。
• プラグインの配布。