# Context System

**Versión:** 0.1  
**Estado:** Especificación inicial

---

## Descripción

Herramienta local para gestionar el contexto de trabajo con modelos de IA. Funciona de forma idéntica en cualquier servidor. No depende de servicios externos.

---

## Principios

1. **Local first** - Todo funciona sin conexión a servicios externos
2. **Inmutabilidad del log** - El historial nunca se modifica
3. **Control del usuario** - El usuario decide qué contexto envía
4. **Independencia** - Cada componente funciona por separado
5. **Portabilidad** - La misma herramienta en cualquier servidor

---

## Componentes

### 1. Log Inmutable

Registro de TODOS los mensajes de conversaciones con IA.

| Característica | Valor |
|----------------|-------|
| Editable | NO |
| Borrable | NO |
| Ubicación | Local (PostgreSQL) |

**Contenido:**
- Cada mensaje enviado a la IA
- Cada respuesta recibida
- Timestamp
- Identificador de sesión

### 2. Gestor de Contexto

| Característica | Valor |
|----------------|-------|
| Editable | Sí |
| Borrable | Sí |
| Ubicación | Local |

**Contenido:**
- Bloques de contexto reutilizables
- Configuración de qué se incluye en cada sesión
- Prioridades y orden

### 3. Dataset del Usuario

| Característica | Valor |
|----------------|-------|
| Editable | Sí |
| Borrable | Sí |
| Ubicación | Local |

**Contenido:**
- Referencias a archivos, documentos, datos
- Metadatos para búsqueda y acceso
- Estructura del espacio de trabajo

### 4. Buzón de Entrada

| Característica | Valor |
|----------------|-------|
| Editable | Según implementación |
| Ubicación | Local |

**Contenido:**
- Resultados que el usuario quiere persistir
- Datos que entran al sistema
- Conexión con almacenamiento externo

---

## Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                    SERVIDOR (local)                             │
│                                                                 │
│  ┌─────────────────┐       ┌─────────────────┐                 │
│  │  1. LOG         │       │  2. GESTOR      │                 │
│  │  INMUTABLE      │       │  DE CONTEXTO    │                 │
│  │  [NO editable]  │       │  [Editable]     │                 │
│  └─────────────────┘       └─────────────────┘                 │
│                                                                 │
│  ┌─────────────────┐       ┌─────────────────┐                 │
│  │  3. DATASET     │       │  4. BUZÓN       │                 │
│  │  DEL USUARIO    │       │  DE ENTRADA     │                 │
│  │  [Editable]     │       │  [E/S datos]    │                 │
│  └─────────────────┘       └─────────────────┘                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   IA EXTERNA    │
                    │  (no en local)  │
                    └─────────────────┘
```

---

## Módulo Grafo (Kuzu)

Capa de selección dinámica de contexto. El grafo no almacena datos primarios — es una proyección reconstruible del log.

```
LOG (inmutable)  →  GRAFO (derivado)  →  Contexto seleccionado
   fuente de verdad    caché relaciones      input para LLM
```

### Tecnología: Kuzu

| Criterio | Kuzu |
|----------|------|
| Instalación | `pip install kuzu` |
| Dependencias | Ninguna |
| Servidor | No requiere |
| Persistencia | Carpeta local |
| Licencia | MIT |

### Uso Básico

```python
import kuzu

db = kuzu.Database("./grafo_contexto")
conn = kuzu.Connection(db)

# Crear esquema
conn.execute("CREATE NODE TABLE Mensaje(id INT64, hash STRING, PRIMARY KEY(id))")
conn.execute("CREATE NODE TABLE Concepto(nombre STRING, PRIMARY KEY(nombre))")
conn.execute("CREATE REL TABLE Menciona(FROM Mensaje TO Concepto)")
```

### Mantenimiento

| Tarea | Comando |
|-------|---------|
| Backup | `cp -r ./grafo_contexto ./backup` |
| Borrar | `rm -rf ./grafo_contexto` |
| Regenerar | Script desde log |