CONCEPTOS

El modelo Event-Sourcing

ChainMemory sigue una arquitectura event-sourcing. Entender este patrón es clave para entender todo el sistema.

En sistemas tradicionales, guardás el estado actual y lo sobreescribís en cada cambio. En event-sourcing, guardás cada cambio como un evento inmutable, y el estado actual se deriva reproduciendo esos eventos.

En ChainMemory:

• Las memorias son eventos — Cada memoria es un registro inmutable de algo que pasó: se tomó una decisión, se identificó un riesgo, se eligió una tecnología, se alcanzó un hito.
• El Project State es una vista materializada — El Motor de Consolidación procesa todos los eventos-memoria y produce un snapshot estructurado: el Project State. No se almacena directamente — se computa desde el log de eventos.
• El anclaje es la prueba de existencia — Cuando un Project State se ancla on-chain, la blockchain certifica que esta vista materializada específica existía en ese block height exacto.

Patrón
Memoria #1 (evento) ─┐
Memoria #2 (evento) ─┤
Memoria #3 (evento) ─┼──→ Motor de Consolidación ──→ Project State v1 ──→ Anchor (bloque 120000)
Memoria #4 (evento) ─┤
Memoria #5 (evento) ─┘

Memoria #6 (evento) ─┐
Memoria #7 (evento) ─┼──→ Motor de Consolidación ──→ Project State v2 ──→ Anchor (bloque 123539)
Memoria #8 (evento) ─┘

Esto significa que siempre podés reconstruir cualquier versión del Project State reproduciendo las memorias hasta ese punto. El log de eventos es la fuente de verdad. El estado es una capa de conveniencia. El anchor es la prueba.

Qué es una memoria

Una memoria es la unidad fundamental de ChainMemory. Es un fragmento de información extraído de una conversación con IA que se considera valioso para el futuro del proyecto.

Cada memoria contiene:

• Contenido — El texto de la conversación o nota
• Hash — SHA-256 del contenido, inmutable
• Proyecto — A qué proyecto pertenece
• Tags — Etiquetas libres para organización (decisión, bug, arquitectura, idea, etc.). Los tags son para tu uso — el Motor de Consolidación usa su propia estructura de 6 categorías (ver Project State)
• Número — Secuencial dentro de tu cuenta (#1, #2...)
• Fuente — Desde dónde se guardó (extensión, MCP, API)
• Timestamp — Momento exacto de creación

Proyectos

Un proyecto agrupa memorias relacionadas. Cada proyecto tiene su propia línea de tiempo, estado consolidado, y ancla on-chain independiente.

Ejemplos de proyectos: mi-saas, tesis-ml, chainmemory, app-mobile.

Project State

El Project State es el resultado del Motor de Consolidación: un modelo de IA analiza todas las memorias del proyecto y extrae información estructurada. Es el corazón de ChainMemory — transforma fragmentos de conversación en una base de conocimiento organizada y auditable.

Las 6 Categorías

Ciclo de Vida del Estado

El estado es incremental: cada consolidación parte de la versión anterior y aplica solo las operaciones nuevas. Esto crea una cadena de versiones con integridad completa:

Cadena de versiones
v1 (3 memorias)  ──hash──▶  v2 (8 memorias)  ──hash──▶  v3 (15 memorias)
     │                           │                           │
     └─ anclado bloque 80,467   └─ anclado bloque 81,102   └─ anclado bloque 82,340

Cada versión contiene:

• state_hash — SHA3-256 del estado canónico, con separador de dominio CM_PROJECT_STATE_V<schema_version>, enlazado a la versión anterior
• version — Número secuencial (v1, v2, v3...)
• previous_hash — Hash de la versión anterior (null para v1)
• operations — Qué cambió: adiciones, actualizaciones, supersesiones
• anchor_tx — Hash de transacción on-chain (una vez sellado)

Ejemplo Real: Project State Completo

JSON — Project State v4
{
  "project_id": "payment-system-v2",
  "version": 4,
  "state_hash": "a3f8c2...e91d",
  "previous_hash": "7b2e1a...f4c0",
  "context": {
    "summary": "Sistema de pagos con aislamiento multi-tenant y detección de fraude",
    "goals": ["Procesar 1000 tx/seg", "Cumplimiento PCI DSS Level 1", "Latencia sub-200ms"]
  },
  "decisions": [
    {
      "id": "d001", "title": "Usar Stripe para procesamiento de pagos",
      "status": "active", "evidence": ["#12", "#45", "#67"],
      "rationale": "Mejor documentación de API, confiabilidad de webhooks, PCI compliance integrado"
    },
    {
      "id": "d002", "title": "PostgreSQL con RLS para multi-tenancy",
      "status": "active", "evidence": ["#15", "#23"]
    },
    {
      "id": "d003", "title": "Usar MySQL para multi-tenancy",
      "status": "superseded", "superseded_by": "d002", "evidence": ["#8"]
    }
  ],
  "milestones": [
    {"id": "m001", "title": "Schema de BD", "status": "completed", "date": "2026-05-15"},
    {"id": "m002", "title": "Integración de pagos", "status": "pending"}
  ],
  "risks": [
    {"id": "r001", "title": "Performance de RLS con 100K tenants", "severity": "medium"}
  ],
  "stack": [
    {"name": "Node.js", "version": "22", "role": "runtime"},
    {"name": "PostgreSQL", "version": "16", "role": "primary-db"},
    {"name": "Redis", "version": "7", "role": "cache"}
  ],
  "dependencies": [
    {"name": "Stripe API", "type": "external", "critical": true}
  ]
}

Operaciones del Motor de Consolidación

• ADD — Nueva decisión, hito, riesgo o entrada de stack detectada en el contenido de la memoria
• UPDATE — Entrada existente recibe nueva evidencia, estado actualizado o detalles enriquecidos
• SUPERSEDE — Una decisión es reemplazada por una más nueva (ambas preservadas en el historial)
• COMPLETE — Un hito pasa de pendiente a completado con fecha
• ESCALATE — La severidad de un riesgo aumenta basándose en nueva evidencia

Mejores Prácticas

• Guardá decisiones explícitamente — "Decidimos usar X porque Y" se consolida mejor que "tal vez deberíamos probar X"
• Incluí la justificación — El motor extrae el razonamiento del contenido. Cuanto más contexto des, más rico será el estado
• Consolidá regularmente — cada consolidación crea una versión nueva del estado, que después se ancla on-chain. seal es otra operación: vuelve permanentemente inmutable una memoria
• Revisá decisiones reemplazadas — Cuentan la historia de cómo evolucionó tu proyecto. No las ignores

Cadena de evidencia

Cada decisión, hito y riesgo en el Project State lleva un campo evidence — un array de referencias a memorias que justifican su existencia.

JSON
{
  "id": "d001",
  "title": "Usar consenso Clique PoA",
  "statement": "Blockchain soberana usa Proof of Authority para anclaje rápido y económico",
  "status": "vigente",
  "evidence": ["#12", "#45", "#67"]
}

Esto crea una cadena de procedencia completa:

• La decisión d001 existe porque las memorias #12, #45 y #67 la respaldan
• Cada memoria tiene un hash SHA-256 que prueba que su contenido no cambió
• El Project State que contiene esta decisión tiene un state_hash anclado on-chain
• El ancla on-chain tiene un tx_hash y block number que prueban cuándo se registró

Desde una sola decisión, podés rastrear el camino completo: decisión → memorias de respaldo → hashes de contenido → hash del estado → prueba on-chain. Esto es lo que hace que las decisiones de ChainMemory sean auditables e inalterables.

Resolución de conflictos

Cuando dos memorias contienen información contradictoria, el Motor de Consolidación aplica una estrategia de resolución determinística:

Precedencia temporal

La memoria más reciente tiene prioridad. Si la Memoria #20 dice "Usaremos PostgreSQL" y la Memoria #40 dice "Cambiamos a ClickHouse", el motor marca la decisión de PostgreSQL como reemplazada y crea una nueva decisión activa para ClickHouse.

Supersesión explícita

El motor detecta patrones de lenguaje que indican cambio de dirección: "en vez de", "reemplazando", "decidimos cambiar", "ya no usamos". Cuando se detecta, la decisión anterior se marca explícitamente como reemplazada con referencia a la nueva.

Ciclo de vida de estados

Flujo de estados
vigente ──→ reemplazada    (sustituida por una decisión más nueva)
vigente ──→ en evaluación  (bajo revisión, aún no confirmada)
en evaluación ──→ vigente  (confirmada tras evaluación)
en evaluación ──→ rechazada (descartada)

Acumulación de evidencia

Cuando múltiples memorias refuerzan la misma decisión, el motor las agrega al array de evidencia en lugar de crear duplicados. Una decisión con evidencia de 5 memorias es más sólida que una con una sola referencia.

Gobernanza del estado

El ciclo de vida del Project State está gobernado por reglas claras:

Quién puede consolidar?

Solo el dueño del proyecto (la cuenta que lo creó) puede disparar una consolidación. Esto asegura que la extracción de conocimiento estructurado siempre esté controlada por el dueño de los datos.

Cuándo ocurre la consolidación?

• La dispara el cliente — un modelo de IA propone operaciones vía update_project_state (MCP) o POST /v1/project/:name/state/ops (API). El servidor las valida y recién entonces se vuelven estado
• No hay disparador automático — la consolidación nunca ocurre sola. Nada se escribe en tu estado si un cliente no lo propone

Se puede revertir?

Cada consolidación crea una nueva versión (v1, v2, v3...). Las versiones anteriores siguen accesibles. No podés borrar una versión, pero siempre podés consolidar de nuevo para producir un estado corregido. La cadena de versiones es append-only.

Snapshots

Cada versión del Project State es un snapshot. La combinación de número de versión + state_hash + ancla on-chain crea un checkpoint verificable. Podés obtener cualquier versión histórica vía GET /v1/project/:name/state?version=2.

Hash y verificación

Cada memoria genera un hash SHA-256 de su contenido. Este hash es la huella digital única e inmutable de esa memoria. El contenido no se puede modificar sin cambiar el hash.

El state hash es un hash del estado consolidado completo (todas las decisiones, hitos, riesgos, etc.). Este state hash se ancla en la blockchain mediante una transacción en el contrato ProjectStateAnchor.

Verificación pública

La verificación en ChainMemory es pública y sin permisos. Cualquier persona puede:

1. Llamar a GET /v1/project/:name/state/anchor (no requiere API key)
2. Obtener el state_hash y el tx_hash de la transacción
3. Verificar en el explorer que la transacción existe
4. Leer el contrato directamente en la blockchain para confirmar que el hash coincide

Esto demuestra que el estado del proyecto existía exactamente así en el momento del anclaje. No se puede falsificar retroactivamente.

Modelo de privacidad

Una preocupación común con sistemas basados en blockchain es la exposición de datos. ChainMemory aborda esto con una separación estricta:

Qué se guarda dónde

Un ancla de estado contiene solo el identificador del proyecto hasheado, el número de versión, el hash del estado y un timestamp. Una transacción de memoria lleva además el contenido cifrado más su categoría, importancia y largo del texto plano. Desde cualquiera de las dos es imposible reconstruir el contenido sin la llave del dueño.

Este diseño significa que ChainMemory puede proveer verificación criptográfica sin comprometer la privacidad. La blockchain prueba que un estado existió, no qué contenía.