Arra Memory Lab

Un laboratorio independiente de un solo usuario en Cloudflare para aprender los contratos que sustentan la memoria de IA confiable: fuentes autorizadas, embeddings reconstruibles, observaciones respaldadas por evidencia, recuperación híbrida inspeccionable, trazas acotadas y operaciones de vista previa antes de la mutación.

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

Qué demuestra esto

• Niveles de autoridad: las memorias son autoritativas; los chunks/embeddings y las observaciones son derivados.

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

• Linaje de evidencia: las observaciones conservan IDs de memoria de origen, revisiones y hashes.

• Mutación segura: olvidar y reconstruir son primero de vista previa; la confirmación de olvido está vinculada a la instantánea de vista previa exacta, 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 memoria.

• Recuperación vinculada a trazas: una recuperación devuelve un traceId cuando la persistencia de la traza tiene éxito; las instantáneas de resultados clasificados conservan solo el ID de memoria, la procedencia de rango/puntuación, la revisión de origen y el hash de origen.

• Supersesión explícita: supersedesMemoryId se resuelve una vez en el momento de la escritura en una instantánea inmutable de ID/revisión/hash. No infiere un grafo temporal.

• Procedencia pequeña: project, sourcePath y createdBy son campos estructurados; una identidad de Oracle sigue siendo una etiqueta oracle-<name>. retrospective y cheatsheet son tipos de memoria de primera clase.

El queryHash de la traza es un identificador de correlación, no un anonimato—especialmente para consultas de baja entropía—por lo que el acceso a las trazas sigue protegido aunque se omitan la consulta cruda y el contenido de la memoria.

Related MCP server: Ghostkeep

Identidad de versión

package.json es la única fuente de verdad para el CalVer de Bangkok del laboratorio: YY.M.D-alpha.HMM, donde HMM = hora × 100 + minuto en Asia/Bangkok. La compilación inyecta solo esa cadena en el cliente público; /api/info, MCP initialize, la herramienta lab_info y el pie de página de la interfaz informan el mismo valor.

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

El comando de incremento rechaza la reutilización en el mismo minuto, el retroceso del reloj, las banderas desconocidas y cualquier CalVer que no sea más nuevo que las etiquetas existentes arra-memory-lab-v*.

Esto no es intencionalmente un diseño de identidad o tenencia de producción. La API web privada usa un secreto de portador de un solo propietario. El carril MCP remoto usa OAuth 2.1, PKCE S256, Registro Dinámico de Clientes (DCR), tokens de acceso que expiran y tokens de actualización para que Claude.ai y otros clientes web MCP puedan conectarse sin almacenar la frase de contraseña del propietario. Los inquilinos, las colas, los índices ANN y la consolidación autónoma siguen diferidos.

Flujo de datos y límite de privacidad

• Crear una memoria intenta un embedding de mejor esfuerzo después de que la escritura de origen en D1 tenga éxito.

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

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

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

• D1 almacena texto autoritativo más texto/vectores de chunks derivados; las trazas de búsqueda y los enlaces de resultados almacenan solo hashes, IDs, rangos, puntuaciones 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 enlace de Workers AI aún accede al servicio remoto y puede incurrir en uso.

Despliegue

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

2. El formulario de despliegue de Cloudflare solicita LAB_ACCESS_TOKEN. Proporciona un valor aleatorio largo (por ejemplo, uno generado con openssl rand -hex 32); Cloudflare lo almacena como un enlace secreto. El mismo valor desbloquea la API del navegador y aprueba nuevos clientes OAuth, pero los clientes OAuth nunca lo reciben.

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

4. Abre la URL del Worker. Ingresa el mismo token una vez; el navegador lo almacena solo en sessionStorage, por lo que cerrar esa sesión del navegador lo borra.

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

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

Para una versión extraída, no edites los IDs de marcador de posición en wrangler.jsonc. El asistente de versión compila y prueba primero, resuelve exactamente una base de datos D1 llamada arra-memory-lab y un espacio de nombres KV llamado arra-memory-lab-oauth, escribe sus IDs solo en una configuración temporal con modo 0600, aplica migraciones, y luego despliega esa misma compilación inmutable:

npm run deploy:dry-run
npm run deploy

Las rutas privadas /api/* requieren Authorization: Bearer $LAB_ACCESS_TOKEN. /mcp acepta solo tokens de acceso emitidos por el proveedor OAuth del laboratorio; el secreto del propietario se rechaza allí. El descubrimiento OAuth, DCR, el intercambio de tokens y la interfaz de aprobación viven bajo /.well-known/*, /oauth/* y /authorize. Solo GET /api/info es contenido de aplicación público. Si LAB_ACCESS_TOKEN está ausente, el acceso a la API privada y la aprobación OAuth fallan de forma segura.

La respuesta de consentimiento omite intencionalmente form-action de CSP: los navegadores OAuth integrados utilizados por hosts MCP reales bloquearon el envío incluso con una lista de permitidos de origen exacto. El destino del formulario es un /authorize relativo fijo; base-uri 'none' evita la reescritura del destino base, cada campo derivado de DCR se escapa en HTML, y la ruta POST vuelve a analizar PKCE/ámbitos/estado del cliente antes de que el proveedor OAuth valide y complete la redirección. Este es un límite de compatibilidad medido, no una recomendación general de CSP.

¿Por qué D1 para el despliegue de un clic?

Se usa D1 porque el flujo de despliegue de Cloudflare puede aprovisionarlo y vincularlo automáticamente, manteniendo este laboratorio genuinamente cerca de un clic. La compensación es un acoplamiento deliberado al proveedor: esta versión no demuestra una capa de base de datos portátil ni un despliegue Turso/libSQL. Eso es aceptable para un laboratorio de Cloudflare enfocado, no una recomendación general de producción.

Desarrollo local

Requiere Node.js para instalar/compilar/desplegar, Bun para los scripts de prueba/verificación y una cuenta de Cloudflare para Workers AI. Wrangler advierte porque el enlace de IA sigue siendo remoto incluso mientras el Worker y D1 se ejecutan localmente.

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

Verificaciones de calidad:

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

El hook postbuild elimina los archivos .env* y .dev.vars* de dist/. Esto es defensa en profundidad para 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":"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

El laboratorio expone MCP HTTP sin estado de Streamable en /mcp. Un token con ambos ámbitos anunciados recibe estas herramientas:

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

lab_info siempre está presente para un token válido. memory:read controla recall, memory_stats, trace_list y trace_get; memory:write controla remember, observe, forget y rebuild_index. Las verificaciones de ámbito usan el ámbito del token de acceso sin envolver en cada solicitud sin estado, incluida la reducción de ámbito del token de actualización.

La implementación fija @modelcontextprotocol/server@2.0.0 y usa el envoltorio createMcpHandler de Cloudflare Agents. "SDK v2" y "versión de protocolo" son ejes separados: el endpoint sirve solicitudes modernas 2026-07-28 y mantiene el flujo initialize de la era 2025 como un carril de compatibilidad sin estado. Ningún carril crea un Mcp-Session-Id; cada solicitud recibe una instancia de servidor nueva. Consulta docs/mcp-v2-stateless.md para la matriz de prueba.

Conectar o recargar un cliente 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

El asistente registra la URL e inicia el inicio de sesión OAuth del cliente. Volver a ejecutarlo actualiza la ruta de registro/inicio de sesión. Para Claude.ai, abre Settings → Connectors → Add custom connector, ingresa solo https://…/mcp, haz clic en Connect e ingresa la frase de contraseña del laboratorio en la página de aprobación.

Portador versus OAuth

Consulta docs/provenance-oauth-report.md para la decisión medida y la prueba sanitizada.

Contratos de fallo

• Las escrituras de memoria autoritativas sobreviven a fallos de embedding.

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

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

• Los errores de base de datos/vectores no se etiquetan erróneamente como respaldo de IA.

• Los fallos de escritura de trazas nunca alteran una recuperación exitosa ni enmascaran su error original.

• La traza completada, los enlaces de resultados clasificados y la poda de retención se intentan en un lote D1; la persistencia de trazas sigue siendo a prueba de fallos en relación con la recuperación.

• Olvidar una memoria no borra las instantáneas históricas de resultados de trazas o supersesión; podar una traza se propaga a sus enlaces clasificados.

• La reconstrucción vuelve a verificar la revisión/hash de origen antes de reemplazar los chunks derivados.

• La confirmación de olvido requiere la revisión, el hash, el recuento de chunks y el recuento de observaciones devueltos por su vista previa; la confirmación obsoleta falla con HTTP 409 / stale_preview.

Consulta CONTRACT.md para el límite de tiempo de ejecución actual 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 enlace D1 de Cloudflare

• Enlaces de Workers AI de Cloudflare

• Proveedor OAuth de Cloudflare para MCP remoto

• Autenticación del conector MCP remoto de Anthropic

• Contrato del modelo EmbeddingGemma 300M

• Drizzle ORM con Cloudflare D1