Arra Memory Lab

Ein eigenständiges, auf einen einzelnen Benutzer ausgelegtes Cloudflare-Lab zum Erlernen der Verträge hinter vertrauenswürdigem KI-Memory: autoritative Quellen, wiederherstellbare Embeddings, evidenzgestützte Beobachtungen, überprüfbarer hybrider Abruf, begrenzte Traces und Operationen mit Vorschau vor jeder Mutation.

Die Bereitstellung erstellt einen Worker, richtet die D1-Datenbank automatisch über wrangler.jsonc ein und wendet die enthaltenen Migrationen über das Deploy-Skript an. Workers AI liefert 768-dimensionale Embeddings von @cf/google/embeddinggemma-300m.

Was dieses Lab demonstriert

• Autoritätsstufen: Erinnerungen sind autoritative Quellen; Chunks/Embeddings und Beobachtungen sind davon abgeleitet.

• Ehrlicher Abruf: Jede Suche meldet den angefragten Modus, den tatsächlich verwendeten Modus, die Degradation und die Herkunft des Rankings.

• Evidenzherkunft: Beobachtungen behalten die Quell-Erinnerungs-IDs, Revisionen und Hashes.

• Sichere Mutation: forget und rebuild starten mit einem Dry-Run; die Bestätigung von forget ist exakt an den Vorschau-Snapshot gebunden, und die bestätigte Rebuild-Arbeit ist begrenzt.

• Datenminimierung: Die 100 neuesten Such-Traces enthalten ausschließlich betriebliche Metadaten, niemals Abfrage- oder Erinnerungsinhalt.

Der queryHash im Trace ist eine Korrelationskennung, keine Anonymisierung – insbesondere bei Abfragen mit geringer Entropie –, weshalb der Zugriff auf Traces geschützt bleibt, obwohl roher Abfrage- und Erinnerungsinhalt weggelassen wird.

Dies ist bewusst kein Produktionsdesign für Identität oder Mandantenfähigkeit. Es verwendet ein einziges Bearer-Token und verweigert ohne dieses den Zugriff (fail closed). OAuth/DCR, Mandanten, Queues, ANN‑Indizes und autonome Konsolidierung werden auf später verschoben.

Datenfluss und Datenschutzgrenze

• Beim Anlegen einer Erinnerung wird nach erfolgreichem Schreiben der Quelle in D1 ein Best-Effort-Embedding versucht.

• Semantischer oder hybrider Abruf sendet den Abfragetext an Workers AI.

• Ein bestätigter Rebuild sendet die ausgewählten Titel-/Inhalts-Chunks der Erinnerung an Workers AI und schreibt die abgeleiteten Vektoren in D1.

• Keyword-Abruf und Rebuild-Vorschauen rufen Workers AI nicht auf.

• D1 speichert den autoritativen Text sowie abgeleitete Chunk-Texte/-Vektoren; Such-Traces speichern nur einen Hash und betriebliche Metadaten.

Verwenden Sie synthetische oder nicht-sensitive Daten, es sei denn, die Richtlinie Ihres Cloudflare-Kontos und Ihr Bedrohungsmodell erlauben diese Verarbeitung ausdrücklich. Bei der lokalen Entwicklung greift die Workers-AI-Bindung weiterhin auf den entfernten Dienst zu und kann Nutzung verursachen.

Deploy

1. Klicken Sie oben auf Deploy to Cloudflare und autorisieren Sie die Bereitstellung des Repositories.

2. Das Cloudflare-Bereitstellungsformular fragt nach LAB_ACCESS_TOKEN. Geben Sie einen langen Zufallswert ein (etwa einen mit openssl rand -hex 32 erzeugten); Cloudflare speichert ihn als Secret-Binding.

3. Deploy starten. Das Deploy-Skript des Repositories wendet die D1-Migrationen automatisch an, bevor der Worker gebaut und veröffentlicht wird.

4. Öffnen Sie die Worker-URL. Geben Sie das Token einmal ein; der Browser speichert es nur in sessionStorage, sodass das Schließen der Browser-Sitzung es löscht.

Falls das Deployment-Formular oder der automatische Migrationsschritt manuell repariert werden muss, verwenden Sie das entsprechende CLI-Fallback:

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

Die API und /mcp erfordern Authorization: Bearer $LAB_ACCESS_TOKEN. Nur GET /api/info ist öffentlich und legt Architektur/Konzepte offen – nicht Korpusinhalte. Ohne LAB_ACCESS_TOKEN verweigert der geschützte Zugriff den Zugriff (fail closed).

Warum D1 für die Ein-Klick-Bereitstellung?

D1 wird verwendet, weil der Cloudflare-Bereitstellungsablauf D1 automatisch bereitstellen und anbinden kann, sodass dieses Lab wirklich nah am Ein-Klick-Erlebnis bleibt. Der Kompromiss ist eine bewusste Anbieterkopplung: Diese Version demonstriert keine portable Datenbank-Schicht und keine Turso/libSQL-Bereitstellung. Das ist für ein fokussiertes Cloudflare-Lab akzeptabel, aber keine pauschale Produktionsempfehlung.

Lokale Entwicklung

Erforderlich sind Node.js für Installation/Build/Deployment, Bun für die Skripte zu Test/Prüfung und ein Cloudflare-Konto für Workers AI. Wrangler warnt, weil die KI-Bindung remote bleibt, auch wenn Worker und D1 lokal laufen.

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

Qualitätsprüfungen:

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

Der postbuild-Hook entfernt .env*- und .dev.vars*-Dateien aus dist/. Das ist Defense-in-Depth für lokale Artefakte; das Deployment-Manifest von Wrangler lädt diese Entwicklungsdateien nicht hoch.

HTTP-Beispiele

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

Das Lab stellt zustandsloses Streamable-HTTP-MCP unter /mcp mit den folgenden Tools bereit:

lab_info, remember, recall, observe, forgot, rebuild_index, memory_stats.

Die Implementierung legt die Version @modelcontextprotocol/server@2.0.0 fest und verwendet den createMcpHandler-Wrapper von Cloudflare Agents. „SDK v2“ und „Protokollversion“ sind getrennte Achsen: Der Endpunkt bedient moderne 2026-07-28-Anfragen und führt den initialize‑Ablauf aus der 2025-Ära als zustandslosen Kompatibilitätszweig weiter. Weder Zweig erzeugt eine Mcp-Session-Id, jede Anfrage erhält eine neue Server-Instanz. Siehe docs/mcp-v2-stateless.md für die Nachweismatrix.

MCP-Endpunktprüfung mit curl

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"}}}'

Konfiguration des MCP-Clients

Für Clients, die Streamable-HTTP-Server unterstützen:

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

Wenn Ihr Client Umgebungsvariablen nicht in Headern auflöst, verwenden Sie dessen Secret Manager anstatt das Token in das Repositorium zu committen. Die exakte Konfiguration variiert je nach MCP-Client; Endpunkt und Bearer-Header bleiben jedoch gleich.

Fehlerverträge

• Schreibvorgänge für autoritative Erinnerungen überstehen einen Ausfall der Embedding-Erstellung.

• Hybrider Abruf wird nur bei Fehlern des Embedding-Anbieters reduziert und der Grund dafür wird vermeldet.

• Ausdrücklicher semantischer Abruf meldet einen Fehler, wenn die semantische Inferenz nicht verfügbar ist.

• Datenbank-/Vektorfehler werden nicht fälschlich als KI-Fallback markiert.

• Fehler beim Schreiben von Traces verändern nie einen erfolgreichen Abruf und verdecken nicht seinen ursprünglichen Fehlernutzen.

• Der Rebuild prüft Revision und Hash der Quelle erneut, bevor abgeleitete Chunks ersetzt werden.

• Die Bestätigung von forget erfordert Revision, Hash, Chunk-Zahl und Beobachtungs-Zahl aus der angehängten Vorschau; abgelaufene Bestätigungen führen zu HTTP 409 / stale_preview.

Siehe CONTRACT.md für die eingefrorene v1-Grenze und DESIGN.md für das UI-System.

Wichtige Plattformverweise

• Cloudflare-Deploy-Buttons und automatisch belegte Ressourcen

• Cloudflare-D1-Bindungskonfiguration

• Cloudflare-Workers-AI-Bindings

• EmbeddingGemma-300M-Modellvertrag

• Drizzle ORM mit Cloudflare D1