# 🧠 Sistema de Memoria de Conversación - NexusChat

## ✅ Estado: IMPLEMENTADO Y FUNCIONAL

---

## 📊 Características Implementadas

### 1. 🗄️ Conversaciones Independientes por Agente/Just Chat
- **Cada agente mantiene su propio historial de conversación**
- **Just Chat tiene su conversación independiente**
- **Conversaciones almacenadas en PostgreSQL** con persistencia completa

### 2. 🧠 Memoria de Contexto Continuo
- Al enviar un mensaje, el servidor **carga TODO el historial previo** de la conversación
- El historial completo se **envía al modelo de IA** para mantener contexto
- **Continuidad de conversación** entre sesiones (cerrar/abrir aplicación)

### 3. 📝 Auto-titulado de Conversaciones
- Primera pregunta del usuario se usa como **título automático**
- Títulos generados de los **primeros 60 caracteres** del mensaje
- Facilita identificación de conversaciones en historial

### 4. 💾 Persistencia en Base de Datos
- **Tabla `conversations`**: Conversaciones por usuario/agente
- **Tabla `messages`**: Todos los mensajes con timestamp
- **Tabla `agents`**: Agentes configurables
- **Relaciones**: User → Conversations → Messages

### 5. 🔄 Carga Automática al Cambiar Contexto
- Al seleccionar un agente: carga su conversación activa desde BD
- Al seleccionar Just Chat: carga conversación de Just Chat desde BD
- Sincronización automática sin intervención del usuario

---

## 🔌 API REST para Conversaciones

### Endpoints Disponibles:

```bash
# Listar todas las conversaciones
GET /api/conversations?agentId=xxx
GET /api/conversations?isJustChat=true

# Obtener conversación activa
GET /api/conversations/active?agentId=xxx
GET /api/conversations/active?isJustChat=true

# Obtener mensajes de una conversación
GET /api/conversations/:conversationId/messages
```

### Respuestas:

```json
{
  "success": true,
  "data": {
    "id": "cmlqv9qz600025p1onk963r19",
    "userId": "cmlqv8y0800005p1omor7yqxz",
    "title": "What is TypeScript?",
    "agentId": null,
    "modelId": "gpt-4o",
    "providerId": "openai",
    "createdAt": "2026-02-17T17:18:02.705Z",
    "updatedAt": "2026-02-17T18:25:15.123Z",
    "messages": [
      {
        "id": "msg1",
        "role": "user",
        "content": "What is TypeScript?",
        "createdAt": "2026-02-17T17:18:02.705Z"
      },
      {
        "id": "msg2",
        "role": "assistant",
        "content": "TypeScript is...",
        "createdAt": "2026-02-17T17:18:05.123Z"
      }
    ]
  }
}
```

---

## 📋 Flujo de Conversación con Memoria

```
1️⃣  Usuario selecciona agente o Just Chat
     ↓
2️⃣  Cliente llama a API: GET /api/conversations/active
     ↓
3️⃣  Cliente carga todos los mensajes históricos en UI
     ↓
4️⃣  Usuario envía nuevo mensaje
     ↓
5️⃣  Servidor busca/crea conversación en BD
     ↓
6️⃣  Servidor carga TODOS los mensajes previos de la BD
     ↓
7️⃣  Servidor construye array de contexto:
     [System Prompt] + [Mensaje 1] + [Respuesta 1] + ... + [Nuevo Mensaje]
     ↓
8️⃣  Servidor envía array completo al modelo de IA
     ↓
9️⃣  IA responde CON CONOCIMIENTO de toda la conversación previa
     ↓
🔟  Ambos mensajes (usuario + IA) se guardan en BD
     ↓
1️⃣1️⃣ Si es primer mensaje: título se auto-genera
```

---

## 🎯 Ejemplo de Uso Real

### Escenario: Conversación sobre TypeScript

```typescript
// 1. Usuario abre "Just Chat"
// → Se carga historial previo de Just Chat desde BD (vacío si es primera vez)

// 2. Usuario pregunta:
"What is TypeScript?"

// → Se crea nueva conversación con título: "What is TypeScript?"
// → IA responde explicando TypeScript
// → Ambos mensajes guardados en BD

// 3. Usuario pregunta (en la MISMA conversación):
"Give me a code example"

// → Servidor carga historial completo:
//   [
//     { role: 'user', content: 'What is TypeScript?' },
//     { role: 'assistant', content: 'TypeScript is...' },
//     { role: 'user', content: 'Give me a code example' }
//   ]

// → IA recibe TODO el contexto
// → IA responde con ejemplo de TypeScript (sabe que está hablando de TS)
// → Mensaje guardado en BD

// 4. Usuario cierra aplicación
// → Todo guardado en PostgreSQL

// 5. Usuario reabre aplicación y selecciona "Just Chat"
// → Historial completo se carga desde BD
// → Conversación continúa exactamente donde quedó
```

---

## 🧹 Función de Limpiar Conversación

```typescript
// En useChat hook:
const { clearConversation } = useChat();

// Usar en UI:
<button onClick={clearConversation}>
  Start New Conversation
</button>

// Efecto:
// - Limpia mensajes en memoria
// - Limpia localStorage
// - Próximo mensaje creará nueva conversación en BD
```

---

## 🗂️ Estructura de Base de Datos

```sql
-- Tabla de Usuarios
users (
  id: cuid PRIMARY KEY,
  email: VARCHAR UNIQUE,
  name: VARCHAR,
  password: VARCHAR,
  created_at: TIMESTAMP,
  updated_at: TIMESTAMP
)

-- Tabla de Agentes
agents (
  id: cuid PRIMARY KEY,
  user_id: cuid → users(id),
  name: VARCHAR,
  emoji: VARCHAR,
  role: VARCHAR,
  description: TEXT,
  status: VARCHAR,
  created_at: TIMESTAMP,
  updated_at: TIMESTAMP
)

-- Tabla de Conversaciones
conversations (
  id: cuid PRIMARY KEY,
  user_id: cuid → users(id),
  agent_id: cuid → agents(id) NULLABLE,
  title: VARCHAR,
  model_id: VARCHAR,
  provider_id: VARCHAR,
  created_at: TIMESTAMP,
  updated_at: TIMESTAMP
)

-- Tabla de Mensajes
messages (
  id: cuid PRIMARY KEY,
  conversation_id: cuid → conversations(id),
  role: VARCHAR (user|assistant|system),
  content: TEXT,
  tokens_used: INTEGER,
  model: VARCHAR,
  created_at: TIMESTAMP
)
```

---

## 🔧 Archivos Clave

### Backend:
- `src/server/WebServer.ts` - Manejo de socket con carga de historial
- `src/server/routes/conversations.ts` - API REST de conversaciones
- `src/server/routes/agents.ts` - CRUD de agentes
- `src/db/prisma.ts` - Cliente Prisma
- `prisma/schema.prisma` - Esquema de base de datos

### Frontend:
- `client/src/hooks/useChat.ts` - Gestión de mensajes y carga desde BD
- `client/src/hooks/useAgents.ts` - Gestión de agentes con API
- `client/src/components/LobeChatArea.tsx` - Área de chat
- `client/src/components/AgentList.tsx` - Lista de agentes

---

## 🚀 Servidor en Ejecución

```bash
# Backend
URL: http://localhost:3000
Estado: ✅ Running
PID: [Ver con: lsof -i:3000]

# Base de datos
Type: PostgreSQL
Host: 192.168.1.20:5433
Database: nexus
Estado: ✅ Connected

# Frontend (Vite dev)
URL: http://localhost:3002
Estado: ✅ Running
```

---

## 🧪 Comandos de Prueba

```bash
# 1. Verificar servidor
curl http://localhost:3000/health

# 2. Listar agentes
curl http://localhost:3000/api/agents | jq '.'

# 3. Crear agente
curl -X POST http://localhost:3000/api/agents \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Agent","emoji":"🤖","description":"Test agent"}' \
  | jq '.'

# 4. Obtener conversación activa de Just Chat
curl "http://localhost:3000/api/conversations/active?isJustChat=true" | jq '.'

# 5. Obtener conversación activa de un agente
curl "http://localhost:3000/api/conversations/active?agentId=AGENT_ID" | jq '.'

# 6. Listar todas las conversaciones
curl "http://localhost:3000/api/conversations" | jq '.'
```

---

## 📈 Beneficios del Sistema

✅ **Persistencia Total**: Nunca se pierde el historial de conversación  
✅ **Contexto Continuo**: IA recuerda toda la conversación previa  
✅ **Multi-sesión**: Cerrar y abrir la app no afecta el contexto  
✅ **Organización**: Cada agente tiene su propio historial  
✅ **Escalabilidad**: PostgreSQL soporta miles de conversaciones  
✅ **Auto-guardado**: No hay botones "Save", todo se guarda automáticamente  
✅ **Títulos Inteligentes**: Fácil identificar conversaciones antiguas  

---

## 🎓 Conceptos Implementados

- **Persistencia de Estado**: PostgreSQL + Prisma ORM
- **Context Window Management**: Envío de historial completo al LLM
- **Relational Data Modeling**: Users → Agents → Conversations → Messages
- **Real-time Streaming**: Socket.IO con chunks
- **API REST**: Express con TypeScript
- **React Hooks**: Custom hooks para gestión de estado
- **Optimistic UI**: Actualización inmediata en cliente
- **Fallback Strategy**: localStorage como backup si falla API

---

## 🔮 Próximas Mejoras Sugeridas

1. **Paginación de Historial**: Cargar solo últimos N mensajes para performance
2. **Búsqueda de Conversaciones**: Buscar por contenido o título
3. **Exportar Conversaciones**: Descargar como JSON/Markdown
4. **Compartir Conversaciones**: Link público a conversación
5. **Etiquetas/Tags**: Organizar conversaciones por categorías
6. **Archivar Conversaciones**: Ocultar conversaciones antiguas
7. **Borrar Conversaciones**: Eliminar historial permanentemente
8. **Context Window Optimization**: Comprimir mensajes antiguos (summarization)

---

## ✅ Estado Final

**Sistema completamente funcional** con:
- ✅ Persistencia en PostgreSQL
- ✅ Memoria de conversación continua
- ✅ Streaming de respuestas
- ✅ Auto-guardado automático
- ✅ API REST completa
- ✅ UI integrada con Lobe UI
- ✅ Compilación sin errores
- ✅ Servidor en ejecución

**Todo listo para uso en producción** 🎉