fix: corregir descripciones de servidores TZZR

- Añadir tabla correcta: ARCHITECT=Desarrollo, DECK=Usuario, CORP=Corporativo - Eliminar ejemplos inventados (architect_persona) - Usar ejemplos genéricos (system_rules, dev_config)
2026-01-01 16:16:35 +00:00
parent 76c04c7255
commit 05d21976ca
3 changed files with 467 additions and 173 deletions
--- a/docs/CTO.md
+++ b/docs/CTO.md
@@ -1,101 +1,209 @@
-# Context Manager (CTO) - Schema v1.0
+# CTO Schema v2.0 - Context Manager

-Sistema de gestión de contexto con embeddings para TZZR.
+## 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
-Almacena bloques de memoria extraídos de conversaciones.
+### cto.blocks (23 columnas)

-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| hash | CHAR(64) | SHA-256 único del contenido |
-| session_hash | CHAR(64) | Sesión donde se extrajo |
-| owner_id | CHAR(64) | Propietario (PLY hash) |
-| block_type | TEXT | fact, instruction, preference, context |
+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) | Embedding OpenAI |
-| importance | FLOAT | Importancia 0.0-1.0 |
-| access_count | INT | Veces accedido |
-| source_hash | CHAR(64) | Mensaje origen (log.messages) |
-| metadata | JSONB | Datos adicionales |
+| 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 |

-### cto.memory
-Memoria activa por sesión - qué bloques están en contexto.
+**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

-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| session_hash | CHAR(64) | Sesión actual |
+### 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 |
-| block_hash | CHAR(64) | Referencia a cto.blocks |
-| position | INT | Orden en contexto |
-| score | FLOAT | Puntuación de relevancia |
-| token_count | INT | Tokens consumidos |
-| included | BOOLEAN | En contexto actual |
+| 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 |

-### cto.algorithms
-Configuración de algoritmos como JSONB.
+**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) |

-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| name | TEXT | Nombre único |
-| version | TEXT | Versión |
-| config | JSONB | Configuración |
-| enabled | BOOLEAN | Activo |
+### cto.algorithms (14 columnas)

-## Algoritmos por defecto
+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

-### extractor
-```json
-{
-    "min_content_length": 10,
-    "max_block_size": 500,
-    "extraction_mode": "heuristic",
-    "patterns": ["fact", "instruction", "preference", "context"]
-}
-```
-
-### scorer
 ```json
 {
+  "version": "2.0.0",
+  "extraction": {
+    "enabled": true,
+    "async": true,
+    "batch_size": 10
+  },
+  "scoring": {
    "weights": {
-        "recency": 0.3,
-        "frequency": 0.2,
-        "importance": 0.3,
-        "similarity": 0.2
+      "recency": 0.20,
+      "importance": 0.40,
+      "relevance": 0.30,
+      "frequency": 0.10
    },
-    "decay_factor": 0.95
+    "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
+  }
 }
 ```

-### selector
-```json
-{
-    "budget_tokens": 8000,
-    "min_score": 0.1,
-    "max_blocks": 50,
-    "strategy": "greedy"
-}
+## 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
 ```

-### consolidator
-```json
-{
-    "similarity_threshold": 0.85,
-    "merge_strategy": "newest",
-    "compression_ratio": 0.7
-}
+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
+);
 ```

-## Despliegue
+### cto.get_active_blocks(scope, server_code, agent_code)

-Schema aplicado en:
- ARCHITECT (69.62.126.110)
- DECK (72.62.1.113)
- CORP (92.112.181.188)
+Obtiene bloques activos filtrados por scope:

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

- PostgreSQL 14+
- pgvector extension
- OpenAI API (embeddings)
+-- 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;
+```