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.

```sql
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.

```sql
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).

```sql
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.

```sql
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.

```sql
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).

```sql
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

```json
{
  "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)
```