system-docs/03_MODELO_DATOS/context-tables.md

Tablas de Contexto

Estado: Implementado
Base de datos: PostgreSQL (ARCHITECT)

---

Descripción

Tablas que proporcionan contexto a las instancias Claude.

---

Diagrama de Relaciones

instancias ──┬── memoria
             │
             └── conversaciones ──── mensajes_v2
                       │
                       └── memoria (conversacion_origen)

conocimiento (independiente, compartido)

contexto_ambiental (independiente, periódico)

---

instancias

Identidad de cada instancia Claude.

CREATE TABLE instancias (
    id            VARCHAR(50) PRIMARY KEY,
    nombre        VARCHAR(100),
    system_prompt TEXT NOT NULL,
    personalidad  JSONB DEFAULT '{
        "tono": "profesional",
        "idioma": "es",
        "verbosidad": "conciso"
    }',
    permisos      JSONB DEFAULT '{
        "puede_ejecutar_bash": false,
        "puede_acceder_red": false,
        "puede_modificar_archivos": false,
        "servidores_permitidos": []
    }',
    modelo        VARCHAR(50) DEFAULT 'sonnet',
    created_at    TIMESTAMP DEFAULT NOW(),
    updated_at    TIMESTAMP DEFAULT NOW()
);

Uso: Define quién es cada Claude, su personalidad, y qué puede hacer.

Instancias Activas

ID	Nombre	Modelo	Servidor
architect	Architect	sonnet	ARCHITECT
hst	HST	sonnet	HST
deck	Deck	sonnet	DECK
corp	Corp	sonnet	CORP
runpod	Runpod	sonnet	RunPod
locker	Locker	haiku	R2/Storage

---

memoria

Memoria a largo plazo por instancia.

CREATE TABLE memoria (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    instancia_id        VARCHAR(50) REFERENCES instancias(id),
    tipo                VARCHAR(50) NOT NULL,
    contenido           TEXT NOT NULL,
    importancia         INT DEFAULT 5,
    usos                INT DEFAULT 0,
    ultimo_uso          TIMESTAMP,
    conversacion_origen UUID REFERENCES conversaciones(id),
    expira_at           TIMESTAMP,
    created_at          TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_memoria_instancia ON memoria(instancia_id, importancia DESC);
CREATE INDEX idx_memoria_tipo ON memoria(instancia_id, tipo);

Tipos de Memoria

Tipo	Descripción
preferencia	Preferencias del usuario
hecho	Hechos aprendidos
decision	Decisiones tomadas
aprendizaje	Lecciones aprendidas
procedimiento	Procedimientos aprendidos

---

conocimiento

Base de conocimiento compartida (RAG).

CREATE TABLE conocimiento (
    id                    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    categoria             VARCHAR(50) NOT NULL,
    titulo                VARCHAR(200),
    contenido             TEXT NOT NULL,
    tags                  TEXT[],
    instancias_permitidas VARCHAR(50)[],
    prioridad             INT DEFAULT 0,
    fuente                VARCHAR(200),
    hash_contenido        VARCHAR(64),
    created_at            TIMESTAMP DEFAULT NOW(),
    updated_at            TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_conocimiento_categoria ON conocimiento(categoria);
CREATE INDEX idx_conocimiento_prioridad ON conocimiento(prioridad DESC);
CREATE INDEX idx_conocimiento_tags ON conocimiento USING GIN(tags);

Categorías

Categoría	Descripción
infraestructura	Documentación de infra
proyecto	Información de proyectos
personal	Datos personales
procedimiento	Procedimientos operativos

---

conversaciones

Sesiones de chat.

CREATE TABLE conversaciones (
    id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    instancia_id       VARCHAR(50) REFERENCES instancias(id),
    usuario            VARCHAR(50) NOT NULL,
    titulo             VARCHAR(200),
    activa             BOOLEAN DEFAULT TRUE,
    total_tokens       INT DEFAULT 0,
    total_mensajes     INT DEFAULT 0,
    resumen            TEXT,
    resumen_updated_at TIMESTAMP,
    contexto_ambiental JSONB DEFAULT '{
        "proyecto_activo": null,
        "archivos_abiertos": [],
        "ultimo_comando": null,
        "hora_local": null
    }',
    created_at         TIMESTAMP DEFAULT NOW(),
    updated_at         TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_conversaciones_instancia ON conversaciones(instancia_id, activa);
CREATE INDEX idx_conversaciones_usuario ON conversaciones(usuario, activa);

---

mensajes_v2

Mensajes con soporte para compactación.

CREATE TABLE mensajes_v2 (
    id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversacion_id    UUID REFERENCES conversaciones(id),
    role               VARCHAR(20) NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
    contenido          TEXT NOT NULL,
    archivos           JSONB DEFAULT '[]',
    tokens_estimados   INT,
    compactado         BOOLEAN DEFAULT FALSE,
    resumen_compactado TEXT,
    metadata           JSONB DEFAULT '{}',
    created_at         TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_mensajes_v2_conversacion ON mensajes_v2(conversacion_id, created_at);
CREATE INDEX idx_mensajes_v2_no_compactados ON mensajes_v2(conversacion_id, compactado) 
    WHERE compactado = FALSE;

Nota: Los mensajes antiguos se compactan (resumen) para ahorrar tokens.

---

contexto_ambiental

Estado actual del sistema (captura periódica).

CREATE TABLE contexto_ambiental (
    id                SERIAL PRIMARY KEY,
    capturado_at      TIMESTAMP DEFAULT NOW(),
    servidores        JSONB,
    servicios         JSONB,
    tareas_pendientes JSONB,
    alertas           JSONB,
    git_estado        JSONB,
    expira_at         TIMESTAMP DEFAULT NOW() + INTERVAL '1 hour'
);

CREATE INDEX idx_contexto_ambiental_tiempo ON contexto_ambiental(capturado_at DESC);

Estructura JSONB

{
  "servidores": {
    "architect": {"status": "online", "uptime": "5d"},
    "deck": {"status": "online", "uptime": "3d"}
  },
  "servicios": {
    "gitea": "running",
    "windmill": "running",
    "directus": "running"
  },
  "tareas_pendientes": [
    {"id": 1, "descripcion": "...", "prioridad": "alta"}
  ],
  "alertas": [
    {"tipo": "warning", "mensaje": "...", "severidad": "medium"}
  ],
  "git_estado": {
    "branch": "main",
    "commits_ahead": 0,
    "uncommitted_changes": false
  }
}

---

Flujo de Contexto

Cuando Claude recibe un mensaje:

1. System Prompt      ← instancias.system_prompt
2. Personalidad       ← instancias.personalidad
3. Memorias           ← memoria WHERE instancia_id = X 
                        ORDER BY importancia DESC LIMIT 20
4. Conocimiento       ← conocimiento WHERE instancias_permitidas 
                        IS NULL OR X = ANY(instancias_permitidas)
5. Contexto Ambiental ← contexto_ambiental 
                        ORDER BY capturado_at DESC LIMIT 1
6. Historial          ← mensajes_v2 WHERE compactado = FALSE 
                        ORDER BY created_at
7. Resumen            ← conversaciones.resumen (mensajes compactados)