Arra Memory Lab

Ein eigenständiges, Single-User-Cloudflare-Lab zum Erlernen der Verträge hinter vertrauenswürdigem KI-Gedächtnis: maßgebliche Quellen, neu aufbaubare Embeddings, evidenzgestützte Beobachtungen, überprüfbares hybrides Abrufen, begrenzte Spuren und Vorschau-vor-Änderung-Operationen.

Die Bereitstellung erstellt einen Worker, richtet automatisch seine D1-Datenbank aus wrangler.jsonc ein und führt die enthaltenen Migrationen über das Bereitstellungsskript aus. Workers AI liefert 768-dimensionale @cf/google/embeddinggemma-300m-Embeddings.

Was hier demonstriert wird

• Autoritätsebenen: Erinnerungen sind maßgeblich; Chunks/Embeddings und Beobachtungen sind abgeleitet.

• Ehrliches Abrufen: Jede Suche meldet den angeforderten Modus, den effektiven Modus, die Degradation und die Rang-Herkunft.

• Evidenz-Abstammung: Beobachtungen behalten Quell-Erinnerungs-IDs, Revisionen und Hashes.

• Sichere Mutation: Vergessen und Neuaufbau sind zuerst als Trockenlauf; die Vergessen-Bestätigung ist an die exakte Vorschau-Snapshot gebunden, und bestätigte Neuaufbau-Arbeit ist begrenzt.

• Datenminimierung: Die neuesten 100 Suchspuren enthalten operative Metadaten, niemals Abfrage- oder Erinnerungsinhalte.

• Spur-verknüpftes Abrufen: Ein Abruf gibt eine traceId zurück, wenn die Spuren-Persistenz erfolgreich ist; Snapshot-Ergebnisse mit Rangfolge behalten nur Erinnerungs-ID, Rang/Score-Herkunft, Quellrevision und Quell-Hash.

• Explizite Ablösung: supersedesMemoryId wird einmalig beim Schreiben in einen unveränderlichen ID/Revision/Hash-Snapshot aufgelöst. Es wird kein zeitlicher Graph abgeleitet.

• Kleine Herkunft: project, sourcePath und createdBy sind strukturierte Felder; eine Oracle-Identität bleibt ein oracle-<name>-Tag. retrospective und cheatsheet sind erstklassige Erinnerungsarten.

Der Spuren-queryHash ist ein Korrelations-Handle, keine Anonymisierung – insbesondere bei Abfragen mit geringer Entropie –, daher bleibt der Spurenzugriff geschützt, auch wenn rohe Abfrage- und Erinnerungsinhalte weggelassen werden.

Related MCP server: Ghostkeep

Release-Identität

package.json ist die einzige Quelle der Wahrheit für das Bangkok-CalVer des Labs: YY.M.D-alpha.HMM, wobei HMM = Stunde × 100 + Minute in Asia/Bangkok. Der Build injiziert nur diese Zeichenfolge in den öffentlichen Client; /api/info, MCP initialize, das lab_info-Tool und die UI-Fußzeile melden denselben Wert.

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

Der Bump-Befehl lehnt Wiederverwendung in derselben Minute, Uhrzeit-Rollback, unbekannte Flags und jedes CalVer ab, das nicht neuer als vorhandene arra-memory-lab-v*-Tags ist.

Dies ist bewusst kein Produktions-Identitäts- oder Mandanten-Design. Die private Web-API verwendet ein einziges Besitzer-Bearer-Geheimnis. Der entfernte MCP-Pfad verwendet OAuth 2.1, S256 PKCE, Dynamic Client Registration (DCR), ablaufende Zugriffstokens und Aktualisierungstokens, damit Claude.ai und andere Web-MCP-Clients eine Verbindung herstellen können, ohne die Besitzer-Passphrase zu speichern. Mandanten, Warteschlangen, ANN-Indizes und autonome Konsolidierung bleiben aufgeschoben.

Datenfluss und Datenschutzgrenze

• Das Erstellen einer Erinnerung versucht nach erfolgreichem D1-Quellschreiben ein Best-Effort-Embedding.

• Semantisches/hybrides Abrufen sendet den Abfragetext an Workers AI.

• Ein bestätigter Neuaufbau sendet die ausgewählten Erinnerungstitel/Inhalts-Chunks an Workers AI und schreibt abgeleitete Vektoren in D1.

• Stichwort-Abruf und Neuaufbau-Vorschauen rufen Workers AI nicht auf.

• D1 speichert maßgeblichen Text plus abgeleiteten Chunk-Text/Vektoren; Suchspuren und Ergebnislinks speichern nur Hashes, IDs, Ränge, Scores und operative Metadaten.

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

Bereitstellen

1. Klicken Sie oben auf Deploy to Cloudflare und autorisieren Sie die Repository-Bereitstellung.

2. Das Cloudflare-Bereitstellungsformular fragt nach LAB_ACCESS_TOKEN. Geben Sie einen langen zufälligen Wert an (z. B. einen mit openssl rand -hex 32 generierten); Cloudflare speichert ihn als geheime Bindung. Derselbe Wert entsperrt die Browser-API und genehmigt neue OAuth-Clients, aber OAuth-Clients erhalten ihn nie.

3. Bereitstellen. Das Bereitstellungsskript des Repositorys wendet die D1-Migrationen automatisch an, bevor der Worker erstellt und veröffentlicht wird.

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

Wenn das Bereitstellungsformular oder der automatische Migrationsschritt manuelle Wiederherstellung benötigt, verwenden Sie das äquivalente CLI-Fallback:

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

Für ein ausgechecktes Release bearbeiten Sie keine Platzhalter-IDs in wrangler.jsonc. Das Release-Hilfsprogramm erstellt und testet zuerst, löst genau eine D1-Datenbank namens arra-memory-lab und einen KV-Namespace namens arra-memory-lab-oauth auf, schreibt deren IDs nur in eine temporäre Konfiguration mit Modus 0600, wendet Migrationen an und stellt dann denselben unveränderlichen Build bereit:

npm run deploy:dry-run
npm run deploy

Private /api/*-Routen erfordern Authorization: Bearer $LAB_ACCESS_TOKEN. /mcp akzeptiert nur Zugriffstokens, die vom OAuth-Anbieter des Labs ausgestellt wurden; das Besitzer-Geheimnis selbst wird dort abgelehnt. OAuth-Erkennung, DCR, Token-Austausch und die Genehmigungs-UI befinden sich unter /.well-known/*, /oauth/* und /authorize. Nur GET /api/info ist öffentlicher Anwendungsinhalt. Wenn LAB_ACCESS_TOKEN fehlt, schlagen privater API-Zugriff und OAuth-Genehmigung fehl.

Die Zustimmungsantwort lässt absichtlich CSP form-action weg: eingebettete OAuth- Browser, die von echten MCP-Hosts verwendet werden, blockierten die Übermittlung selbst mit einer Exact-Origin-Allowlist. Das Formularziel ist ein festes relatives /authorize; base-uri 'none' verhindert Base-Target-Umschreibung, jedes DCR-abgeleitete Feld ist HTML-escaped, und der POST-Pfad parst PKCE/Scopes/Client-Zustand neu, bevor der OAuth-Anbieter validiert und die Weiterleitung abschließt. Dies ist eine gemessene Kompatibilitäts- grenze, keine allgemeine CSP-Empfehlung.

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

D1 wird verwendet, weil der Bereitstellungsablauf von Cloudflare es automatisch bereitstellen und binden kann, wodurch dieses Lab wirklich nahe an einem Klick bleibt. Der Kompromiss ist bewusste Anbieterkopplung: Diese Version demonstriert keine portable Datenbankschicht oder Turso/libSQL-Bereitstellung. Das ist für ein fokussiertes Cloudflare-Lab akzeptabel, keine pauschale Produktionsempfehlung.

Lokale Entwicklung

Erfordert Node.js für Install/Build/Deploy, Bun für die Test-/Check-Skripte und ein Cloudflare-Konto für Workers AI. Wrangler warnt, weil die AI-Bindung entfernt bleibt, selbst wenn der Worker und D1 lokal ausgeführt werden.

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/. Dies ist Verteidigung in der Tiefe für lokale Artefakte; das Bereitstellungsmanifest 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":"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

Das Lab stellt zustandsloses Streamable HTTP MCP unter /mcp bereit. Ein Token mit beiden beworbenen Scopes erhält diese Tools:

lab_info, remember, recall, observe, forget, rebuild_index, memory_stats, trace_list, trace_get.

lab_info ist für ein gültiges Token immer vorhanden. memory:read steuert recall, memory_stats, trace_list und trace_get; memory:write steuert remember, observe, forget und rebuild_index. Scope-Prüfungen verwenden den entpackten Zugriffstoken-Scope bei jeder zustandslosen Anfrage, einschließlich Refresh-Token- Herabstufung.

Die Implementierung pinnt @modelcontextprotocol/server@2.0.0 und verwendet den Cloudflare-Agents-createMcpHandler-Wrapper. „SDK v2“ und „Protokollversion“ sind separate Achsen: Der Endpunkt bedient moderne 2026-07-28-Anfragen und behält den initialize-Ablauf aus der 2025-Ära als zustandslosen Kompatibilitätskanal. Kein Kanal erstellt eine Mcp-Session-Id; jede Anfrage erhält eine frische Serverinstanz. Siehe docs/mcp-v2-stateless.md für die Beweismatrix.

MCP-Client verbinden oder neu laden

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

Das Hilfsprogramm registriert die URL und startet den OAuth-Login des Clients. Erneutes Ausführen aktualisiert den Registrierungs-/Login-Pfad. Für Claude.ai öffnen Sie Settings → Connectors → Add custom connector, geben Sie nur https://…/mcp ein, klicken Sie auf Connect und geben Sie die Lab-Passphrase auf der Genehmigungsseite ein.

Bearer versus OAuth

Siehe docs/provenance-oauth-report.md für die gemessene Entscheidung und bereinigte Beweise.

Fehlerverträge

• Maßgebliche Erinnerungsschreibvorgänge überleben Embedding-Fehler.

• Hybrides Abrufen degradiert nur bei Embedding-Anbieter-Fehlern und meldet den Grund.

• Explizites semantisches Abrufen gibt einen Fehler zurück, wenn semantische Inferenz nicht verfügbar ist.

• Datenbank-/Vektorfehler werden nicht als KI-Fallback fehlbezeichnet.

• Spuren-Schreibfehler verändern niemals ein erfolgreiches Abrufen oder maskieren dessen ursprünglichen Fehler.

• Abgeschlossene Spur, Ergebnislinks mit Rangfolge und Aufbewahrungsbereinigung werden in einem D1-Batch versucht; Spuren-Persistenz bleibt relativ zum Abrufen ausfallsicher.

• Das Vergessen einer Erinnerung löscht keine historischen Spuren-Ergebnis- oder Ablösungs-Snapshots; das Bereinigen einer Spur kaskadiert zu ihren Rangfolge-Links.

• Neuaufbau überprüft Quellrevision/-Hash erneut, bevor abgeleitete Chunks ersetzt werden.

• Vergessen-Bestätigung erfordert die Revision, den Hash, die Chunk-Anzahl und die Beobachtungsanzahl, die von seiner Vorschau zurückgegeben wurden; veraltete Bestätigung schlägt mit HTTP 409 / stale_preview fehl.

Siehe CONTRACT.md für die aktuelle Laufzeitgrenze und DESIGN.md für das UI-System.

Primäre Plattformreferenzen

• Cloudflare-Bereitstellungsbuttons und automatische Ressourcenbereitstellung

• Cloudflare-D1-Bindungskonfiguration

• Cloudflare-Workers-AI-Bindungen

• Cloudflare-OAuth-Anbieter für entferntes MCP

• Anthropic-Remote-MCP-Connector-Authentifizierung

• EmbeddingGemma-300M-Modellvertrag

• Drizzle ORM mit Cloudflare D1