Arra Memory Lab

Un laboratorio independiente de Cloudflare, para un único usuario, con el que aprender los contratos que hay detrás de una memoria de IA fiable: fuentes de autoridad, embeddings reconstruibles, observaciones respaldadas por evidencia, recuperación híbrida inspeccionable, trazas acotadas y operaciones con vista previa antes de la mutación.

El despliegue crea un único Worker, aprovisiona automáticamente su base de datos D1 a partir de wrangler.jsonc y ejecuta las migraciones incluidas mediante el script de despliegue. Workers AI proporciona los embeddings de 768 dimensiones de @cf/google/embeddinggemma-300m.

Qué demuestra esto

• Niveles de autoridad: las memorias son la fuente de autoridad; los fragmentos/embeddings y las observaciones son derivados.

• Recuperación honesta: cada búsqueda informa del modo solicitado, el modo efectivo, la degradación y la procedencia de la clasificación.

• Procedencia de la evidencia: las observaciones conservan los IDs de memoria de origen, las revisiones y los hashes.

• Mutación segura: el olvido y la reconstrucción se ejecutan primero en modo simulado; la confirmación del olvido está vinculada a la instantánea exacta de la vista previa, y el trabajo de reconstrucción confirmado está acotado.

• Minimización de datos: las 100 trazas de búsqueda más recientes contienen metadatos operativos, nunca consultas ni contenido de las memorias.

La queryHash de la traza es un identificador de correlación, no una anonimización —sobre todo en el caso de consultas con poca entropía—, por lo que el acceso a las trazas sigue protegido aunque se omitan la consulta original de texto y el contenido de la memoria.

No es, a propósito, un diseño de identidad ni de tenancy para producción. Usa un único token portador y, sin él, falla en modo cerrado; deja para más adelante OAuth/DCR, los inquilinos, las colas, los índices ANN y la consolidación autónoma.

Flujo de datos y límite de privacidad

• Crear una memoria intenta hacer un embedding de mejor esfuerzo después de que la escritura de la fuente en D1 se realiza correctamente.

• La recuperación semántica/híbrida envía el texto de la consulta a Workers AI.

• Una reconstrucción confirmada envía el título/contenido de la memoria seleccionada a Workers AI y escribe los vectores derivados de la memoria en D1.

• La recuperación por palabras claves y las vistas previas de reconstrucción no llaman a Workers AI.

• D1 almacena el texto de la memoria (autoritativo) junto con el texto/vectores derivados de los fragmentos; las trazas de búsqueda guardan solo un hash de la consulta y metadatos operativos.

Usa datos sintéticos o no sensibles a menos que la política de tu cuenta de Cloudflare y tu modelo de amenazas permitan explícitamente este procesamiento. En el desarrollo local, el binding de Workers AI sigue accediendo al servicio remoto y puede generar consumo.

Despliegue

1. Haz clic en Deploy to Cloudflare más arriba y autoriza el despliegue del repositorio.

2. El formulario de despliegue de Cloudflare pedirá el valor de LAB_ACCESS_TOKEN / Espacio aporta un valor largo y aleatorio (por ejemplo, uno generado con openssl rand -hex 32); Cloudflare lo guarda como un binding secreto.

3. Despliega. El script del repositorio aplica automáticamente las migraciones de D1 antes de compilar y publicar el Worker.

4. Abre la URL del Worker. Introduce el mismo valor del token una vez; el navegador lo guarda solo en sessionStorage, de modo que al cerrar la sesión de esa ventana se borra.

Si el formulario de despliegue o el paso de migración automática requieren una recuperación manual, usa el equivalente con la CLI:

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

La API y /mcp requieren Authorization: Bearer $LAB_ACCESS_TOKEN. Solo GET /api/info es público y expone la arquitectura y las capacidades, no el contenido del corpus. Si no hay LAB_ACCESS_TOKEN, el acceso protegido falla en modo cerrado.

¿Por qué D1 para un despliegue en un clic?

Se usa D1 porque el flujo de despliegue de Cloudflare puede aprovisionarlo y vincularlo automáticamente, lo que mantiene el laboratorio realmente cerca del despliegue en un clic. La compensación es un acoplamiento deliberado al proveedor: esta versión no muestra una capa de base de datos portable ni un despliegue con Turso/libSQL. Esto es aceptable para un laboratorio centrado en Cloudflare, no una recomendación de producción general elística.

Desarrollo local

Requiere Node.js para instalar, compilar y desplegar; Bun para los scripts de prueba y comprobación; y una cuenta de Cloudflare para Workers AI. Wrangler emite un aviso porque el binding de IA sigue estando remoto aunque el Worker y D1 se ejecuten en local.

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

Comprobaciones de calidad:

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

La regla postbuild elimina los archivos .env* y .dev.vars* de dist/, lo que supone una defensa en profundidad para los artefactos locales; el manifiesto de despliegue de Wrangler no sube esos archivos de desarrollo.

Ejemplos 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

El laboratorio expone un servidor MCP Streamable HTTP sin estado en /mcp, con las herramientas siguientes:

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

La implementación fija @modelcontextprotocol/server@2.0.0 y usa el envoltorio createMcpHandler de Cloudflare Agents. «SDK v2» y «protocol /version» son ejes distintos: el endpoint atiende las solicitudes modernas de 2026-07-28 y conserva el flujo initialize de la etapa de 2025 como canal de compatibilidad sin estado. Ninguno de los dos canales crea un Mcp-Session-Id; cada solicitud recibe una nueva instancia del servidor. Consulta docs/mcp-v2-stateless.md para consultar la matriz de prueba.

Comprobación del endpoint MCP con 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"}}}'

Configuración de un cliente MCP

Para clientes que soportan servidores Streamable HTTP:

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

Si tu cliente no interpola variables de entorno en los encabezados, utiliza su gestor de secretos en lugar de enviar el token. La envoltura de configuración exacta varía según el cliente MCP; el endpoint y el encabezado del Bearer no varían.

Contratos de fallo

• Las escrituras de memoria autoritativas sobreviven los fallos de embeddings.

• La recuperación híbrida solo se degrada ante fallos del proveedor de embeddings e informa del motivo.

• La recuperación semántica explícita produce un error si la inferencia semántica no está disponible.

• Los errores de base de datos/vectores no se etiquetan como un fallback de IA.

• Los fallos de escritura de cada traza no alteran una recuperación basada en datos de la misma razón.

• La reconstrucción vuelve a comprobar la revisión/hash de la fuente antes de sustituir los fragmentos derivados.

• La confirmación del olvido requiere la revisión, el hash, el recuento de fragmentos y el recuento de observaciones devueltos por su vista previa; una confirmación desactualizada falla con el código HTTP 409 / stale_preview.

Consulta CONTRACT.md para el límite congelado de la v1 y DESIGN.md para el sistema de interfaz.

Referencias principales de la plataforma

• Botones de despliegue de Cloudflare y aprovisionamiento automático de recursos

• Configuración del binding D1 de Cloudflare

• Bindings de Cloudflare Workers AI

• Contrato del modelo EmbeddingGemma 300M

• Drizzle ORM con Cloudflare D1