context-manager/docs/CTO.md

# CTO Schema v2.0 - Context Manager

## Resumen

El schema `cto` gestiona el contexto de los agentes TZZR mediante tres tablas principales:

| Tabla | Propósito |
|-------|-----------|
| `cto.blocks` | Bloques de contexto estático (personas, reglas, conocimiento) |
| `cto.memory` | Memoria a largo plazo con embeddings |
| `cto.algorithms` | Configuración de algoritmos de selección/scoring |

## Tablas

### cto.blocks (23 columnas)

Almacena bloques de contexto que pueden inyectarse en las conversaciones.

| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | BIGSERIAL | PK |
| hash | CHAR(64) | SHA-256 del contenido (UNIQUE) |
| code | VARCHAR(50) | Identificador legible único (ej: `system_rules`, `dev_config`) |
| name | VARCHAR(200) | Nombre descriptivo |
| session_hash | CHAR(64) | Hash de sesión (si aplica) |
| owner_id | CHAR(64) | Propietario del bloque |
| block_type | VARCHAR(50) | Tipo legacy |
| category | VARCHAR(50) | Categoría: persona, rules, capabilities, instructions, knowledge |
| content | TEXT | Contenido del bloque |
| embedding | vector(1536) | Vector para búsqueda semántica |
| priority | INT | Orden de inclusión (mayor = primero) |
| scope | VARCHAR(20) | Ámbito: global, server, agent, session |
| server_code | VARCHAR(20) | Si scope=server: ARCHITECT, DECK, CORP |
| agent_code | VARCHAR(50) | Si scope=agent: código del agente |
| token_count | INT | Tokens estimados |
| status | VARCHAR(20) | active, inactive, deprecated |
| created_at | TIMESTAMPTZ | Fecha creación |
| updated_at | TIMESTAMPTZ | Última modificación |

**Scopes:**
- `global`: Aplica a todos los agentes en todos los servidores
- `server`: Aplica solo a agentes en un servidor específico
- `agent`: Aplica solo a un agente específico
- `session`: Aplica solo a una sesión

### cto.memory (26 columnas)

Memoria a largo plazo con scoring basado en importancia, recencia y relevancia semántica.

| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | BIGSERIAL | PK |
| hash | CHAR(64) | SHA-256 único |
| session_hash | CHAR(64) | Sesión origen |
| block_hash | CHAR(64) | FK a blocks |
| owner_id | CHAR(64) | Propietario |
| type | VARCHAR(20) | preference, decision, fact, entity, temporal |
| content | TEXT | Contenido de la memoria |
| summary | VARCHAR(500) | Resumen corto |
| importance | FLOAT | 0-1 (mayor = más importante) |
| confidence | FLOAT | 0-1 (certeza) |
| embedding | vector(1536) | Vector para similitud |
| embedding_model | VARCHAR(50) | Modelo usado |
| access_count_v2 | INT | Veces accedida |
| last_access | TIMESTAMPTZ | Último acceso |
| source_hash | CHAR(64) | Memoria origen (si derivada) |
| expires_at | TIMESTAMPTZ | Expiración (para temporales) |
| status | VARCHAR(20) | active, superseded, expired, deleted |
| superseded_by | BIGINT | ID de memoria que la reemplaza |
| related_to | BIGINT[] | IDs de memorias relacionadas |
| metadata | JSONB | Metadatos adicionales |
| owner_type | VARCHAR(20) | user, agent, system |
| created_at | TIMESTAMPTZ | Fecha creación |
| updated_at | TIMESTAMPTZ | Última modificación |

**Tipos de memoria:**
| Tipo | Decay Rate | Descripción |
|------|------------|-------------|
| preference | 0.01 | Preferencias del usuario (decae muy lento) |
| decision | 0.05 | Decisiones tomadas |
| fact | 0.10 | Hechos aprendidos |
| entity | 0.05 | Entidades mencionadas |
| temporal | 0.50 | Info temporal (decae rápido) |

### cto.algorithms (14 columnas)

Configuración de algoritmos de scoring, selección y extracción.

| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | SERIAL | PK |
| code | VARCHAR(50) | Código único |
| name | VARCHAR(100) | Nombre |
| version | VARCHAR(20) | Versión |
| config | JSONB | Configuración completa |
| enabled | BOOLEAN | Legacy |
| status | VARCHAR(20) | draft, active, experiment, deprecated |
| parent_id | INT | FK a algoritmo padre (versionado) |
| metrics | JSONB | Métricas de rendimiento |
| activated_at | TIMESTAMPTZ | Fecha activación |
| deprecated_at | TIMESTAMPTZ | Fecha deprecación |
| created_at | TIMESTAMPTZ | Fecha creación |
| updated_at | TIMESTAMPTZ | Última modificación |

## Configuración del Algoritmo v2

```json
{
  "version": "2.0.0",
  "extraction": {
    "enabled": true,
    "async": true,
    "batch_size": 10
  },
  "scoring": {
    "weights": {
      "recency": 0.20,
      "importance": 0.40,
      "relevance": 0.30,
      "frequency": 0.10
    },
    "decay_rates": {
      "preference": 0.01,
      "decision": 0.05,
      "fact": 0.10,
      "entity": 0.05,
      "temporal": 0.50
    }
  },
  "selection": {
    "strategy": "priority",
    "token_budget": 8000,
    "priority_order": ["system", "core", "working", "retrieved"]
  },
  "compression": {
    "strategy": "progressive",
    "keep_first": 3,
    "keep_last": 10
  },
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimension": 1536
  }
}
```

## Funciones

### cto.calculate_memory_score(memory_id, query_embedding, current_time)

Calcula score combinado de una memoria:

```
score = 0.20 * recency + 0.40 * importance + 0.30 * relevance + 0.10 * frequency
```

Donde:
- **recency**: Decae exponencialmente según tipo y tiempo desde último acceso
- **importance**: Valor 0-1 asignado al crear la memoria
- **relevance**: Similitud coseno con query_embedding
- **frequency**: Basado en access_count (normalizado 0-1)

### cto.search_memories(query_embedding, owner_id, limit, min_similarity)

Busca memorias por similitud semántica:

```sql
SELECT * FROM cto.search_memories(
    '[0.1, 0.2, ...]'::vector(1536),  -- embedding de la query
    'owner_hash',                       -- propietario
    20,                                 -- límite
    0.3                                 -- similitud mínima
);
```

### cto.get_active_blocks(scope, server_code, agent_code)

Obtiene bloques activos filtrados por scope:

```sql
-- Bloques globales
SELECT * FROM cto.get_active_blocks('global');

-- Bloques para un servidor específico
SELECT * FROM cto.get_active_blocks('server', 'DECK');

-- Bloques para un agente específico
SELECT * FROM cto.get_active_blocks('agent', NULL, 'mi_agente');
```

## Servidores TZZR

| Servidor | IP | Propósito |
|----------|-----|-----------|
| ARCHITECT | 69.62.126.110 | Desarrollo |
| DECK | 72.62.1.113 | Usuario |
| CORP | 92.112.181.188 | Corporativo |

Schema CTO v2.0 desplegado en los 3 servidores.

## Verificar instalación

```sql
\d cto.blocks
\d cto.memory
\d cto.algorithms
SELECT code, version, status FROM cto.algorithms;
```