Arra Memory Lab

Arra Memory Lab は、シングルユーザー向けのスタンドアロン型 Cloudflare ラボで、信頼できる AI メモリの背景にある契約を学習するためのものです。具体的には、権威ある情報源、再ビルド可能なエンベディング、エビデンスに基づく観察、検査可能なハイブリッド検索、制限付きトレース、変更前のプレビュー操作などを扱います。

デプロイを行うと Worker が1つ作成され、wrangler.jsonc から D1 データベースが自動でプロビジョニングされ、同梱のマイグレーションがデプロイスクリプト経由で実行されます。Workers AI は 768 次元の @cf/google/embeddinggemma-300m エンベディングを提供します。

これが示すもの

• 権限の階層: メモリは権威ある情報源であり、チャンク/エンベディングと観察は派生データです。

• 誠実な検索: すべての検索は、要求モード、実効モード、劣化、ランクの出自を報告します。

• エビデンスの来歴: 観察は、ソースとなるメモリ ID、リビジョン、ハッシュを保持します。

• 安全な変更: forget と rebuild は、まずドライポランで実行されます。forget の確認はプレビューのスナップショットに正確に紐付けられ、確認済みの rebuild は作業量が限定されています。

• データ最小化: 新しい最新の 100 件の検索トレースには運用メタデータのみが含まれ、クエリやメモリの内容は一切含まれません。

トレースの queryHash は、非匿名化ではなく相関のためのハンドルです。特に低エントロピーなクエリでは、クエリやメモリの本文が含まれない場合でもトレースのアクセス保護は維持されます。

これは意図的に、本番環境向けのアイデンティティまたはテナントの設計ではありません。1つのベアラートークンを使用し、トークンがない場合にはフェイルクローズします。また、OAuth/DCR、テナント、キュー、ANN インデックス、自律的な結合は将来の課題としています。

データフローとプライバシーの境界

• メモリの作成は、D1 へのソース書き込みが成功した後、ベストエフォートでエンベディングを試行します。

• セマンティック / ハイブリッド検索は、クエリテキストを Workers AI に送信します。

• 確認済みの rebuild は、選択したメモリのタイトル/内容チャンクを Workers AI に送信し、派生ベクトルを D1 に書き込みます。

• キーワード検索とリビルドのプレビューは Workers AI を呼び出しません。

• D1 は権威あるテキストと派生したチャンクテキスト/ベクトルを保存し、検索トレースはクエリハッシュと運用メタデータのみを保存します。

ご利用の Cloudflare アカウントのポリシーと脅威モデルが明示的に許可しない限り、合成または非機密データを使用してください。ローカル開発中でも、Workers AI バインディングはリモートサービスにアクセスし、利用は発生する可能性があります。

デプロイ

1. 上の Deploy to Cloudflare をクリックし、リポジトリのデプロイを承認します。

2. Cloudflare のデプロイフォームで LAB_ACCESS_TOKEN が求められます。長いランダムな値（例: openssl rand -hex 32 で生成）を指定してください。Cloudflare はそれをシークレットバインディングとして保存します。

3. デプロイします。リポジトリーのデプロイスクリプトは、Worker をビルド・公開する前に D1 マイグレーションを自動で適用します。

4. Worker の URL を開き、同じトークンを一度入力します。ブラウザは sessionStorage にのみ保存するため、そのブラウザセッションを閉じると消去されます。

デプロイフォームまたは自動マイグレーションの手順において手動による復旧が必要な場合は、同等の CLI フォールバックを使用してください:

printf '%s' 'replace-with-a-long-random-token' | npx wrangler secret put LAB_ACCESS_TOKEN
npx wrangler d1 migrations apply DB --remote

API と /mcp は Authorization: Bearer $LAB_ACCESS_TOKEN を必要とします。公開されているのは GET /api/info のみですが、これにはコーパスの内容でなくアーキテクチャ/機能が開示されます。LAB_ACCESS_TOKEN がない場合、保護されたアクセスはフェイルクローズします。

ワンクリックデプロイに D1 を選ぶ理由

D1 を利用するのは、Cloudflare のデプロイフローが自動的にプロビジョニングとバインドを行えるため、このラボのワンクリックに近い運用を実現できるからです。このトレードオフは意図的なもので、クラウドプロバイダへの依存を含みます。このバージョンでは、ポータブルなデータベース層や Turso/libSQL のデプロイは示していません。これは、フォーカスした Cloudflare ラボには妥当ですが、一般的な本番環境の推奨というわけではありません。

ローカル開発

インストール / ビルド / デプロイには Node.js が、テスト/スクリプト check には Bun が、Workers AI には Cloudflare アカウントが必要です。Worker と D1 がローカルで実行されても、AI バインディングはリモートのままなので、Wrangler が警告を出します。

cd labs/arra-memory-lab
npm install
cp .env.example .dev.vars
# Set LAB_ACCESS_TOKEN in .dev.vars
npx wrangler d1 migrations apply DB --local
npm run dev

品質チェック:

npm run typecheck
npm test
npm run build
# or all three:
npm run check

postbuild フックは、dist/ から .env* と .dev.vars* ファイルを削除します。これはローカル成果物に対する多層防御です。Wrangler のデプロイマニフェストは、これらの開発用ファイルをアップロードしません。

HTTP の例

export LAB_URL='https://arra-memory-lab.<account>.workers.dev'
export LAB_ACCESS_TOKEN='your-long-random-token'
export AUTH="Authorization: Bearer $LAB_ACCESS_TOKEN"

# Public capability disclosure
curl "$LAB_URL/api/info"

# Create an authoritative memory (indexing is best effort)
curl -X POST "$LAB_URL/api/memories" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"title":"Prefer explicit authority","content":"Memories are sources; embeddings are projections.","kind":"decision","tags":["architecture"]}'

# Hybrid recall exposes requested/effective modes and rank provenance
curl -X POST "$LAB_URL/api/search" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"query":"Which data is authoritative?","mode":"hybrid","limit":8}'

# Preview a forget and retain the returned expected* fields
curl -X POST "$LAB_URL/api/memories/MEMORY_ID/forget" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":false}'

# Confirm only that exact preview. A changed source/impact returns 409 stale_preview.
curl -X POST "$LAB_URL/api/memories/MEMORY_ID/forget" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":true,"expectedRevision":1,"expectedHash":"COPY_FROM_PREVIEW","expectedChunks":0,"expectedObservationCount":0}'

# Preview a bounded rebuild; confirmed work is capped at 10 memories / 256 chunks
curl -X POST "$LAB_URL/api/index/rebuild" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":false}'

多様な

このラボは /mcp でステートレスな Streamable HTTP MCP を公開し、以下のツールを提供します。

lab_info、remember、recall、observe、forget、rebuild_index、memory_stats。

実装では @modelcontextprotocol/server@2.0.0 を固定し、Cloudflare Agents 🎯 の createMcpHandler ラッパーを使用します。「SDK v2」と「プロトコルバージョン」は別の軸です。このエンドポイントは新しい 2026-07-28 の要求を提供し、2025 世代の initialize フローをステートレスな互換レーンとして維持します。どちらのレーンも Mcp-Session-Id を作成せず、各要求は新しいサーバインスタンスを受け取ります。実際性のマトリクスについては docs-mcp-v2-stateless を参照してください。

curl による MCP エンドポイント確認

curl -X POST "$LAB_URL/mcp" \
  -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

MCP クライアント設定

Streamable HTTP サーバーに対応するクライアント向け:

{
  "mcpServers": {
    "arra-memory-lab": {
      "type": "http",
      "url": "https://arra-memory-lab.<account>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${LAB_ACCESS_TOKEN}"
      }
    }
  }
}

クライアントがヘッダー内の環境変数を展開しない場合は、トークンをコミットせずシークレットマネージャーを使用してください。正確な設定のラッパーは MCP クライアントごとに異なりますが、エンドポイントと「Bearer」ヘッダーは変わりません。

障害時コントラクト

• 権威あるメモリの作成書き込みは、エンベディングの失敗にも耐えます。

• ハイブリッド検索は、エンベディングプロバイダー障害時のみ機能が低下し、理由を報告します。

• 明示的なセマンティック検索は、インファレンスが利用不可能な場合はエラーになります。

• データベース / ベクトルのエラーは、AI フォールバックと誤ったラベル付けがされません。

• トレイト書き込みの失敗は、成功した検索結果を変更または元のエラーを隠ぺいしません。

• rebuild は、派生チャンクを置き換える前にソースのリビジョン / ハッシュを再確認します。

• forget の確認には、プレビューが返したリビジョン、ハッシュ、チャンク数、計数がないと成り立ちません。古い確認は HTTP 409 / stale_preview で失敗します。

凍結された v1 境界については CONTRACT.md を、UI システムについては DESIGN.md を参照してください。

主要プラットフォームの Reference

• Cloudflare デプロイボタンとリソース自動プロビジョニング

• Cloudflare D1 バインド設定

• Cloudflare Workers AI バインディング

• EmbeddingGemma 300M のモデル契約

• Drizzle ORMとCloudflare D1