Nexus/CONVERSATION_MEMORY.md

🧠 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:

# 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:

{
  "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

// 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

// 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

-- 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

# 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

# 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 🎉