347 lines
12 KiB
Markdown
347 lines
12 KiB
Markdown
# Context Manager v8 - Sistema de Gestión de Contexto para IA
|
|
|
|
**Versión:** 8.1
|
|
**Fecha:** 2026-01-01
|
|
**Sistema:** CAPTAIN CLAUDE - TZZR
|
|
**Generador:** ARCHITECT
|
|
|
|
---
|
|
|
|
## Visión General
|
|
|
|
El **Context Manager v8** es un sistema completo para la gestión del contexto en sistemas de IA. Proporciona:
|
|
|
|
1. **Log inmutable** con integridad criptográfica (blockchain-style)
|
|
2. **Integración con Sistema de Componentes TZZR** (players, items, locations, hashtags, flags)
|
|
3. **Referencias relacionales** a contexto, libros contables y registros de secretaría
|
|
4. **Contexto ambiental** dinámico embebido en mensajes
|
|
5. **Soporte multiagente** con owner, players y master_player
|
|
|
|
---
|
|
|
|
## Arquitectura de Schemas
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ CONTEXT MANAGER v8.1 │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ SCHEMA: log (Inmutable) │ │
|
|
│ │ │ │
|
|
│ │ ├── log.messages (mensajes) │ │
|
|
│ │ └── log.message_refs (referencias a contexto) │ │
|
|
│ │ │ │
|
|
│ │ Características: │ │
|
|
│ │ ├─ Solo INSERT (UPDATE/DELETE bloqueados) │ │
|
|
│ │ ├─ Cadena SHA-256: prev_hash → hash │ │
|
|
│ │ └─ Integración con Sistema Componentes TZZR │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ SISTEMA DE COMPONENTES TZZR (Referencias externas) │ │
|
|
│ │ │ │
|
|
│ │ ├── ply (Players: usuarios, agentes, empresas) │ │
|
|
│ │ ├── hst (Hash Semantic Tagging: etiquetas) │ │
|
|
│ │ ├── flg (Flags: jurisdicciones, normativas) │ │
|
|
│ │ ├── itm (Items: productos, componentes) │ │
|
|
│ │ └── loc (Locations: ubicaciones físicas) │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ FUENTES DE CONOCIMIENTO (via message_refs) │ │
|
|
│ │ │ │
|
|
│ │ ├── context → log.messages (historial) │ │
|
|
│ │ ├── accountant → libros contables │ │
|
|
│ │ └── secretary → registros de secretaría │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Schema LOG (2 tablas)
|
|
|
|
### 1. `log.messages` - Mensajes
|
|
|
|
Almacena todos los mensajes del sistema de forma inmutable.
|
|
|
|
**Características:**
|
|
- Solo permite INSERT (triggers previenen UPDATE/DELETE)
|
|
- Cadena de integridad: cada mensaje contiene hash del anterior
|
|
- Integración completa con Sistema de Componentes TZZR
|
|
- Soporte multiagente: owner (emisor), players (receptores), master_player (líder)
|
|
|
|
**Schema:**
|
|
```sql
|
|
CREATE TABLE log.messages (
|
|
id BIGSERIAL PRIMARY KEY,
|
|
hash CHAR(64) UNIQUE NOT NULL, -- SHA-256 del mensaje
|
|
session_hash CHAR(64) NOT NULL, -- Sesión
|
|
thread_hash CHAR(64), -- Hilo (nullable)
|
|
owner_id CHAR(64) NOT NULL, -- Emisor (→ ply)
|
|
players_id CHAR(64)[] DEFAULT '{}', -- Receptores (→ ply)
|
|
master_player CHAR(64), -- Líder/coordinador (→ ply)
|
|
role TEXT, -- Rol del emisor
|
|
content TEXT NOT NULL, -- Contenido del mensaje
|
|
attachments JSONB DEFAULT '{}', -- Adjuntos
|
|
prev_hash CHAR(64), -- Hash mensaje anterior
|
|
hashtags CHAR(64)[] DEFAULT '{}', -- Etiquetas (→ hst)
|
|
flag_id CHAR(64), -- Jurisdicción (→ flg)
|
|
master_item_id CHAR(64), -- Item principal (→ itm)
|
|
item_id CHAR(64)[] DEFAULT '{}', -- Items relacionados (→ itm)
|
|
loc_id CHAR(64), -- Ubicación (→ loc)
|
|
ambient JSONB, -- Contexto ambiental
|
|
created_at TIMESTAMPTZ DEFAULT NOW()
|
|
);
|
|
```
|
|
|
|
**Índices:**
|
|
- `session_hash` - Mensajes de una sesión
|
|
- `thread_hash` - Mensajes de un hilo
|
|
- `owner_id` - Mensajes enviados por
|
|
- `master_player` - Mensajes con líder
|
|
- `prev_hash` - Cadena de integridad
|
|
- `created_at` - Orden cronológico
|
|
- `hashtags` (GIN) - Búsqueda por etiquetas
|
|
- `players_id` (GIN) - Búsqueda por receptores
|
|
- `item_id` (GIN) - Búsqueda por items
|
|
- `flag_id` - Filtrar por jurisdicción
|
|
- `loc_id` - Filtrar por ubicación
|
|
|
|
---
|
|
|
|
### 2. `log.message_refs` - Referencias
|
|
|
|
Relaciona cada mensaje con su contexto y fuentes de conocimiento.
|
|
|
|
**Características:**
|
|
- Tabla relacional para evitar arrays largos de hashes
|
|
- Tres tipos de referencias: context, accountant, secretary
|
|
- Posición para ordenar el contexto
|
|
- Inmutable como log.messages
|
|
|
|
**Schema:**
|
|
```sql
|
|
CREATE TABLE log.message_refs (
|
|
id BIGSERIAL PRIMARY KEY,
|
|
message_hash CHAR(64) NOT NULL, -- Mensaje que se envía
|
|
ref_hash CHAR(64) NOT NULL, -- Hash de la referencia
|
|
ref_type log.ref_type NOT NULL, -- context|accountant|secretary
|
|
position INT NOT NULL, -- Orden de la referencia
|
|
thread_hash CHAR(64), -- Hilo (nullable)
|
|
UNIQUE(message_hash, ref_hash)
|
|
);
|
|
```
|
|
|
|
**Tipos de referencia:**
|
|
| Tipo | Descripción |
|
|
|------|-------------|
|
|
| `context` | Mensajes anteriores incluidos como contexto |
|
|
| `accountant` | Registros de libros contables (conocimiento financiero) |
|
|
| `secretary` | Registros de secretaría (conocimiento general) |
|
|
|
|
---
|
|
|
|
## Integración con Sistema de Componentes TZZR
|
|
|
|
El Context Manager referencia las tablas del Sistema de Componentes:
|
|
|
|
| Campo log.messages | Tabla TZZR | Descripción |
|
|
|-------------------|------------|-------------|
|
|
| `owner_id` | ply | Emisor del mensaje (usuario o agente) |
|
|
| `players_id[]` | ply | Receptores del mensaje |
|
|
| `master_player` | ply | Coordinador en sistemas multiagente |
|
|
| `hashtags[]` | hst | Etiquetas semánticas del mensaje |
|
|
| `flag_id` | flg | Jurisdicción o normativa aplicable |
|
|
| `master_item_id` | itm | Item principal relacionado |
|
|
| `item_id[]` | itm | Items adicionales relacionados |
|
|
| `loc_id` | loc | Ubicación física del contexto |
|
|
|
|
### Tablas del Sistema de Componentes
|
|
|
|
```
|
|
PLY (Players)
|
|
├── ply - Sistema (empresas, entidades oficiales)
|
|
├── plu - Usuario (contactos personales)
|
|
└── plx - Compartidos
|
|
|
|
HST (Hash Semantic Tagging)
|
|
├── hst - Tags del sistema (658)
|
|
├── spe - Especificaciones técnicas (145)
|
|
├── vsn - Visiones/escenas (84)
|
|
├── vue - Valores humanos (21)
|
|
└── hsu - Tags de usuario
|
|
|
|
FLG (Flags/Jurisdicciones)
|
|
├── flg - Sistema (65 países/normativas)
|
|
└── flu - Usuario
|
|
|
|
ITM (Items)
|
|
├── itm - Sistema
|
|
├── itu - Usuario
|
|
└── itx - Compartidos
|
|
|
|
LOC (Locations)
|
|
├── loc - Sistema
|
|
├── lou - Usuario
|
|
└── lox - Compartidos
|
|
```
|
|
|
|
---
|
|
|
|
## Cadena de Integridad
|
|
|
|
Cada mensaje incluye el hash del anterior, formando una cadena verificable:
|
|
|
|
```
|
|
msg1.hash = SHA256(msg1_data)
|
|
msg2.prev_hash = msg1.hash
|
|
msg2.hash = SHA256(msg2_data)
|
|
msg3.prev_hash = msg2.hash
|
|
...
|
|
```
|
|
|
|
**Primer mensaje de sesión:** `prev_hash = NULL`
|
|
|
|
**Función de hash:**
|
|
```sql
|
|
CREATE FUNCTION log.sha256(data TEXT) RETURNS CHAR(64) AS $$
|
|
BEGIN
|
|
RETURN encode(digest(data, 'sha256'), 'hex');
|
|
END;
|
|
$$ LANGUAGE plpgsql IMMUTABLE;
|
|
```
|
|
|
|
---
|
|
|
|
## Protección de Inmutabilidad
|
|
|
|
Triggers que previenen modificación:
|
|
|
|
```sql
|
|
-- Bloquear UPDATE
|
|
CREATE TRIGGER protect_messages_update
|
|
BEFORE UPDATE ON log.messages
|
|
FOR EACH ROW EXECUTE FUNCTION log.prevent_update();
|
|
|
|
-- Bloquear DELETE
|
|
CREATE TRIGGER protect_messages_delete
|
|
BEFORE DELETE ON log.messages
|
|
FOR EACH ROW EXECUTE FUNCTION log.prevent_delete();
|
|
|
|
-- Igual para message_refs
|
|
```
|
|
|
|
---
|
|
|
|
## Contexto Ambiental (ambient)
|
|
|
|
Campo JSONB para capturar estado del sistema en el momento del mensaje:
|
|
|
|
```json
|
|
{
|
|
"timezone": "Europe/Madrid",
|
|
"locale": "es-ES",
|
|
"working_directory": "/home/architect/project",
|
|
"git_branch": "main",
|
|
"active_services": ["gitea", "postgresql"],
|
|
"server": "ARCHITECT",
|
|
"timestamp_utc": "2026-01-01T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
Solo se incluye cuando es relevante (nullable en la mayoría de mensajes).
|
|
|
|
---
|
|
|
|
## Despliegue
|
|
|
|
**Servidores activos:**
|
|
|
|
| Servidor | IP | Base de Datos | Estado |
|
|
|----------|-----|---------------|--------|
|
|
| ARCHITECT | 69.62.126.110 | architect | ✅ Activo |
|
|
| DECK | 72.62.1.113 | tzzr | ✅ Activo |
|
|
| CORP | 92.112.181.188 | tzzr | ✅ Activo |
|
|
|
|
**Extensiones requeridas:**
|
|
- `pgcrypto` - Para función SHA-256
|
|
- `pgvector` - Para embeddings (opcional, instalado)
|
|
|
|
**Comando de aplicación:**
|
|
```bash
|
|
sudo -u postgres psql -d [database] -c "$(curl -s http://localhost:3000/admin/context-manager/raw/branch/main/schemas/04_log.sql)"
|
|
```
|
|
|
|
---
|
|
|
|
## Flujo de Trabajo
|
|
|
|
### 1. Insertar mensaje
|
|
|
|
```sql
|
|
INSERT INTO log.messages (
|
|
hash, session_hash, owner_id, players_id,
|
|
content, prev_hash, hashtags, created_at
|
|
) VALUES (
|
|
log.sha256(...), 'session_abc...', 'owner_hash...',
|
|
ARRAY['player1_hash...', 'player2_hash...'],
|
|
'Contenido del mensaje', 'prev_msg_hash...',
|
|
ARRAY['tag1_hash...'], NOW()
|
|
);
|
|
```
|
|
|
|
### 2. Añadir referencias de contexto
|
|
|
|
```sql
|
|
INSERT INTO log.message_refs (
|
|
message_hash, ref_hash, ref_type, position, thread_hash
|
|
) VALUES
|
|
('msg_hash...', 'context_msg_1...', 'context', 1, 'thread...'),
|
|
('msg_hash...', 'context_msg_2...', 'context', 2, 'thread...'),
|
|
('msg_hash...', 'accountant_record...', 'accountant', 3, 'thread...');
|
|
```
|
|
|
|
### 3. Consultar mensajes con contexto
|
|
|
|
```sql
|
|
SELECT
|
|
m.content,
|
|
m.owner_id,
|
|
array_agg(r.ref_hash ORDER BY r.position) as context_refs
|
|
FROM log.messages m
|
|
LEFT JOIN log.message_refs r ON m.hash = r.message_hash
|
|
WHERE m.session_hash = 'session_abc...'
|
|
GROUP BY m.id, m.content, m.owner_id
|
|
ORDER BY m.created_at;
|
|
```
|
|
|
|
---
|
|
|
|
## Ubicación de Documentación
|
|
|
|
| Ubicación | Ruta |
|
|
|-----------|------|
|
|
| Gitea | http://localhost:3000/admin/context-manager |
|
|
| R2 | s3://architect/system/context-manager/ |
|
|
| Skynet v8 | s3://architect/system/skynet v8/03_MODELO_DATOS/ |
|
|
|
|
---
|
|
|
|
## Historial de Cambios
|
|
|
|
| Versión | Fecha | Cambios |
|
|
|---------|-------|---------|
|
|
| 8.0 | 2025-12-30 | Versión inicial con 9 tablas |
|
|
| 8.1 | 2026-01-01 | Simplificación a 2 tablas (log.messages, log.message_refs). Integración con Sistema de Componentes TZZR. Nuevos campos: owner_id, players_id, master_player, flag_id, master_item_id, item_id, loc_id |
|
|
|
|
---
|
|
|
|
**Documento generado por:** ARCHITECT
|
|
**Timestamp:** 2026-01-01
|
|
**Versión:** Context Manager v8.1
|