Segundo Cerebro Serverless

¿Qué es?

La implementación de producción del segundo cerebro serverless descrito en el ensayo homónimo. Mientras el ensayo define la arquitectura — capas de memoria, cómputo e interfaz con «dos puertas» para humanos y agentes — este repositorio es el código que la materializa.

Disponible como código fuente.

Arquitectura

El sistema separa tres capas con responsabilidades claras:

• Memoria: DynamoDB single-table design con GSIs para queries bidireccionales + S3 para contenido largo
• Cómputo: 5 funciones Lambda especializadas (capture, search, graph, connect, flag) orquestadas por Step Functions
• Interfaz: dos puertas — API Gateway REST para el SPA humano, AgentCore Gateway para agentes MCP

Bedrock proporciona clasificación (Claude) y embeddings (Titan 1,024 dimensiones).

Progreso

El proyecto sigue cuatro fases definidas en el ensayo. Las cuatro fases están completas y desplegadas en dev:

Lo que funciona hoy

Puerta humana (API Gateway REST):

• POST /capture — ingesta texto, clasifica con Bedrock Claude, genera embeddings con Titan, persiste en DynamoDB + S3 vía Step Functions
• GET /search?q= — búsqueda híbrida keyword + semántica con cosine similarity sobre embeddings de 1,024 dimensiones
• GET /graph — grafo completo de conocimiento (nodos + edges bidireccionales)
• GET /nodes/{id} — nodo individual con edges y nodos relacionados
• GET /health — health check

Puerta del agente (AgentCore MCP Gateway):

• read_node — lee un nodo por slug con metadata, edges y nodos relacionados
• list_nodes — lista nodos con filtros por tipo, status y tags
• search — búsqueda híbrida keyword + semántica
• add_node — crea un nodo seed con clasificación automática de Bedrock
• connect_nodes — crea edges bidireccionales con audit trail
• flag_stale — marca un nodo para revisión humana sin modificarlo

Surfacing (digest diario):

• 5 analizadores: seeds olvidados, nodos huérfanos, conexiones faltantes, candidatos a promoción, gaps de contenido
• EventBridge cron diario a las 8 AM UTC → Surfacing Lambda → SNS email
• Umbrales configurables vía variables de entorno (STALE_DAYS, MIN_EDGES, SIMILARITY_THRESHOLD)
• Verificado en dev: 17 stale seeds, 1 huérfano, 40 content gaps en ~2.5s para 170 nodos

Infraestructura:

• CloudFront + S3 para hosting estático del frontend
• Migración completa de ~160 nodos desde jonmatum.com MDX a DynamoDB + S3
• Backfill de embeddings para todos los nodos existentes
• CI/CD con GitHub Actions OIDC (sin credenciales estáticas)
• Smoke test script con 12 verificaciones de endpoints
• GitHub Actions OIDC role en bootstrap Terraform

Resiliencia (deep review #3):

• invokeWithRetry() con backoff exponencial para throttling de Bedrock (1s, 2s, 4s)
• Pipeline de captura crea edges bidireccionales (consistencia con connect_nodes)
• batchGetNodes() elimina queries N+1 en Graph Lambda
• CORS en todas las rutas de error, Content-Type en todas las respuestas
• Despliegue a prod en CI/CD con aprobación por environment

Puerta del agente: MCP Gateway

La «puerta del agente» expone las funciones Lambda como herramientas MCP vía Bedrock AgentCore. Cualquier agente compatible con MCP puede descubrir y usar las herramientas semánticamente:

Write safety

Las operaciones de escritura siguen controles estrictos:

• Audit trail: toda mutación crea un item AUDIT# en DynamoDB con actor, acción, cambios y TTL de 90 días
• Seed-only: los nodos creados por agentes inician como seed — requieren revisión humana para promoción
• Sin deletes: los agentes no pueden eliminar nodos, solo marcarlos para revisión con flag_stale
• Actor tracking: cada operación registra el actor (agent:{session_id} o api)
• Validación de existencia: connect_nodes verifica que ambos nodos existan antes de crear edges

// Audit trail en cada operación de escritura
const audit: AuditItem = {
  PK: `AUDIT#${now}`,
  SK: `NODE#${slug}`,
  action: "connect",
  actor,
  changes: { source, target, edge_type, weight },
  ttl: Math.floor(Date.now() / 1000) + 90 * 86400,
};
await putAudit(audit);

Diseño de DynamoDB

Single-table design con cuatro tipos de items:

Dos GSIs habilitan queries inversas y filtros por status:

• GSI1: SK (hash) + PK (range) — «¿qué nodos apuntan a serverless?»
• GSI2: GSI2PK (status) — «todos los seeds sin actualizar en 7 días»

Pipeline de captura

Step Functions orquesta el pipeline completo con retry automático en throttling de Bedrock:

Cada paso es una invocación Lambda separada. Se usa Express Workflow (síncrono) para mantener la respuesta dentro del timeout de API Gateway.

Búsqueda híbrida

La Search Lambda combina keyword matching y similitud semántica:

// Búsqueda híbrida: keyword + semántica
const keywordResults = await queryByKeywords(query, table);
const queryEmbedding = await generateEmbedding(query);
const allEmbeddings = await scanEmbeddings(table);
 
const semanticResults = allEmbeddings
  .map(item => ({
    slug: item.PK.replace("NODE#", ""),
    score: cosineSimilarity(queryEmbedding, item.embedding),
  }))
  .sort((a, b) => b.score - a.score);
 
// Combinar scores con pesos configurables
const combined = mergeResults(keywordResults, semanticResults, {
  keywordWeight: 0.3,
  semanticWeight: 0.7,
});

A la escala actual (~160 nodos, ~700KB de vectores) el scan en memoria es suficiente. El benchmark de escalabilidad (issue #12) evaluará alternativas para 10K+ nodos.

Infraestructura como código

Toda la infraestructura se define con Terraform usando módulos reutilizables:

infra/
  bootstrap/              → Backend de estado (S3 + DynamoDB lock)
  modules/
    dynamodb/             → Single-table design + GSIs
    lambda/               → Funciones de cómputo
    api-gateway/          → Puerta humana (REST)
    step-functions/       → Orquestación de pipelines
    s3/                   → Contenido y frontend
    cloudfront/           → CDN + headers de seguridad
    iam/                  → Roles y políticas
    agentcore-gateway/    → Puerta del agente (MCP)
    sns/                  → Notificaciones
  environments/
    dev/                  → Configuración dev (desplegado)
    prod/                 → Configuración prod

CI/CD usa GitHub Actions con OIDC — sin credenciales estáticas de AWS:

• terraform-plan.yml — plan en PRs
• terraform-apply.yml — apply en merge a main
• lambda-deploy.yml — empaquetado y despliegue de funciones

Costo

Escala a cero. Sin costos mínimos más allá del almacenamiento S3:

Decisiones de arquitectura

El repositorio incluye 12 ADRs (Architecture Decision Records) en docs/decisions/ que documentan cada decisión técnica con contexto, alternativas evaluadas, datos de benchmarks y criterios de revisión:

Próximos pasos

• AgentCore Runtime (issue #8) — hosting del agente de razonamiento en microVMs serverless con acceso a todas las herramientas del Gateway
• Observabilidad (issue #14) — dashboards CloudWatch, alarmas, X-Ray tracing
• Configuración domain-agnostic (issue #13) — hacer el sistema desplegable para cualquier dominio con terraform apply
• Autenticación (issue #17) — implementar ADR-003: Cognito + modelo de visibilidad pública/privada

¿Por qué importa?

Este proyecto traduce una arquitectura de referencia en código desplegable. La meta es que cualquier builder pueda tomar el repositorio, configurar su dominio (legal, investigación, educación) en terraform.tfvars, y desplegar un segundo cerebro completo con terraform apply. El ensayo explica el «por qué» de cada decisión; el código implementa el «cómo».

Las cuatro fases ya demuestran que la arquitectura funciona: captura con clasificación automática, búsqueda semántica híbrida, un grafo de conocimiento bidireccional, una puerta MCP para agentes IA con controles de escritura, y un digest diario proactivo que identifica seeds olvidados y conexiones faltantes — todo serverless, todo en Terraform, escalando a cero con ~$0.51/mes de costo idle.

Referencias

• Del prototipo a producción: un segundo cerebro serverless — Ensayo que define la arquitectura completa.
• Repositorio en GitHub — Código fuente del proyecto.
• AWS Serverless Lens — AWS, 2024. Marco de referencia para aplicaciones serverless.
• DynamoDB Developer Guide — AWS, 2024. Guía del diseño single-table.
• Bedrock AgentCore — AWS, 2025. Gateway MCP y Runtime para agentes.
• AgentCore Gateway Developer Guide — AWS, 2025. Documentación del gateway MCP para herramientas Lambda.
• MCP Specification — Anthropic, 2025. Protocolo de interoperabilidad para agentes.
• Step Functions Developer Guide — AWS, 2024. Orquestación de workflows serverless.