Arra Memory Lab

信頼できるAIメモリの背後にある契約を学ぶための、スタンドアロンでシングルユーザー向けのCloudflareラボです。権威あるソース、再構築可能な埋め込み、証拠に裏付けられた観察、検査可能なハイブリッド検索、境界のあるトレース、そして変更前プレビュー操作を扱います。

このデプロイにより、1つのWorkerが作成され、wrangler.jsoncからD1データベースが自動的にプロビジョニングされ、デプロイスクリプトを通じて含まれるマイグレーションが実行されます。Workers AIは768次元の@cf/google/embeddinggemma-300m埋め込みを提供します。

これが示すもの

• 権威の階層: メモリは権威があり、チャンク/埋め込みと観察は派生です。

• 正直な検索: すべての検索は、要求されたモード、有効なモード、劣化、およびランクの来歴を報告します。

• 証拠の系統: 観察は、ソースメモリID、リビジョン、およびハッシュを保持します。

• 安全な変更: forgetとrebuildは常にドライランが先で、forgetの確認は正確なプレビュースナップショットにバインドされ、確認されたrebuild作業は境界があります。

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

• トレース連携検索: トレースの永続化が成功すると、検索はtraceIdを返します。ランク付けされた結果スナップショットは、メモリID、ランク/スコアの来歴、ソースリビジョン、ソースハッシュのみを保持します。

• 明示的な置き換え: supersedesMemoryIdは書き込み時に一度だけ解決され、不変のID/リビジョン/ハッシュスナップショットになります。時間的なグラフを推論することはありません。

• 小さな来歴: project、sourcePath、createdByは構造化フィールドです。Oracleのアイデンティティはoracle-<name>タグのままです。retrospectiveとcheatsheetは第一級のメモリ種類です。

トレースのqueryHashは相関ハンドルであり、匿名化ではありません。特に低エントロピーのクエリでは、生のクエリとメモリの内容が省略されていても、トレースへのアクセスは保護されたままです。

Related MCP server: Ghostkeep

リリースのアイデンティティ

package.jsonは、このラボのバンコクCalVerの単一の情報源です。 YY.M.D-alpha.HMM、ここでHMM = 時間 × 100 + 分（Asia/Bangkok）。 ビルドはその文字列のみをパブリッククライアントに注入します。/api/info、MCP initialize、lab_infoツール、およびUIフッターは同じ値を報告します。

npm run version:next   # preview the next available Bangkok minute
npm run version:bump   # update package.json + package-lock.json, no commit/tag
npm run version:check  # fail if format or lock metadata drift

bumpコマンドは、同じ分での再利用、時計の巻き戻し、不明なフラグ、および 既存のarra-memory-lab-v*タグより新しいCalVerでないものを拒否します。

これは意図的に本番用のアイデンティティやテナンシーの設計ではありません。プライベートWeb APIは1つのオーナーベアラーシークレットを使用します。リモートMCPレーンはOAuth 2.1、S256 PKCE、動的クライアント登録（DCR）、期限切れアクセストークン、およびリフレッシュトークンを使用するため、Claude.aiや他のWeb MCPクライアントはオーナーのパスフレーズを保存せずに接続できます。テナント、キュー、ANNインデックス、自律的な統合は先送りされたままです。

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

• メモリの作成は、D1ソース書き込みが成功した後に、ベストエフォートの埋め込みを試みます。

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

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

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

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

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

デプロイ

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

2. CloudflareのデプロイフォームはLAB_ACCESS_TOKENを要求します。長いランダムな値（たとえばopenssl rand -hex 32で生成したもの）を指定します。Cloudflareはそれをシークレットバインディングとして保存します。同じ値がブラウザAPIをロック解除し、新しいOAuthクライアントを承認しますが、OAuthクライアントはそれを受け取ることはありません。

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

チェックアウトしたリリースでは、wrangler.jsoncのプレースホルダーIDを編集しないでください。 リリースヘルパーは、まずビルドとテストを行い、arra-memory-labという名前のD1データベースとarra-memory-lab-oauthという名前のKV名前空間を正確に1つ解決し、 それらのIDをモード0600の一時設定にのみ書き込み、マイグレーションを適用し、 その後、同じ不変のビルドをデプロイします。

npm run deploy:dry-run
npm run deploy

プライベートな/api/*ルートはAuthorization: Bearer $LAB_ACCESS_TOKENを要求します。/mcpはラボのOAuthプロバイダーによって発行されたアクセストークンのみを受け入れます。オーナーシークレット自体はそこで拒否されます。OAuthディスカバリー、DCR、トークン交換、および承認UIは/.well-known/*、/oauth/*、/authorizeの下にあります。GET /api/infoのみがパブリックなアプリケーションコンテンツです。LAB_ACCESS_TOKENがない場合、プライベートAPIアクセスとOAuth承認はフェイルクローズします。

同意応答は意図的にCSP form-actionを省略しています。実際のMCPホストが使用する埋め込みOAuth ブラウザは、正確なオリジンの許可リストがあっても送信をブロックしました。 フォームターゲットは固定の相対/authorizeです。base-uri 'none' はベースターゲットの書き換えを防ぎ、すべてのDCR由来フィールドはHTMLエスケープされ、 POSTパスはOAuthプロバイダーが検証してリダイレクトを完了する前にPKCE/スコープ/クライアント状態を再解析します。 これは測定された互換性の境界であり、一般的なCSPの推奨ではありません。

ワンクリックデプロイにD1を使う理由

D1が使用されるのは、Cloudflareのデプロイフローが自動的にプロビジョニングしてバインドできるため、このラボを本当にワンクリックに近づけることができます。トレードオフは意図的なプロバイダー結合です。このバージョンは、ポータブルなデータベースレイヤーやTurso/libSQLデプロイを示していません。これは、焦点を絞ったCloudflareラボには許容されますが、包括的な本番推奨ではありません。

ローカル開発

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

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":"retrospective","tags":["architecture"],"project":"github.com/soul-brews-studio/claude-ai-mcp-poc","sourcePath":"ψ/memory/retrospectives/example.md","createdBy":"rrr","oracleName":"neo","supersedesMemoryId":"OPTIONAL_EXISTING_MEMORY_ID"}'

# 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","project":"github.com/soul-brews-studio/claude-ai-mcp-poc","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

このラボは、/mcpでステートレスなStreamable HTTP MCPを公開します。両方のアドバタイズされたスコープを持つトークンは、次のツールを受け取ります:

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

lab_infoは有効なトークンに対して常に存在します。memory:readは recall、memory_stats、trace_list、trace_getを制御します。memory:writeは remember、observe、forget、rebuild_indexを制御します。スコープチェックは、 リフレッシュトークンのダウンスコーピングを含む、すべてのステートレスリクエストでラップ解除されたアクセストークンスコープを使用します。

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

MCPクライアントを接続または再読み込みする

npm run mcp:connect -- codex "$LAB_URL/mcp" arra-memory-lab
# or Claude Code:
npm run mcp:connect -- claude "$LAB_URL/mcp" arra-memory-lab

ヘルパーはURLを登録し、クライアントのOAuthログインを開始します。再実行すると登録/ログインパスが更新されます。Claude.aiの場合、Settings → Connectors → Add custom connectorを開き、https://…/mcpのみを入力し、Connectをクリックして、承認ページでラボのパスフレーズを入力します。

BearerとOAuthの比較

測定された決定とサニタイズされた証明についてはdocs/provenance-oauth-report.mdを参照してください。

失敗の契約

• 権威あるメモリ書き込みは、埋め込みの失敗を乗り越えて生き残ります。

• ハイブリッド検索は、埋め込みプロバイダーの失敗に対してのみ劣化し、その理由を報告します。

• 明示的なセマンティック検索は、セマンティック推論が利用できない場合にエラーになります。

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

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

• 完了したトレース、ランク付けされた結果リンク、および保持プルーニングは1つのD1バッチで試行されます。トレースの永続化は検索に対してフェイルセーフのままです。

• メモリを忘れても、履歴のトレース結果や置き換えスナップショットは消去されません。トレースのプルーニングはそのランク付けされたリンクにカスケードします。

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

• Forgetの確認には、そのプレビューが返したリビジョン、ハッシュ、チャンク数、および観察数が必要です。古い確認はHTTP 409 / stale_previewで失敗します。

現在のランタイム境界についてはCONTRACT.md、UIシステムについてはDESIGN.mdを参照してください。

主要なプラットフォームリファレンス

• Cloudflare Deploy buttons and automatic resource provisioning

• Cloudflare D1 binding configuration

• Cloudflare Workers AI bindings

• Cloudflare OAuth provider for remote MCP

• Anthropic remote MCP connector authentication

• EmbeddingGemma 300M model contract

• Drizzle ORM with Cloudflare D1