> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-es/agente/chat-history-and-memory.md).

# Historial de chat y memoria

Aprende cómo Neuron AI gestiona conversaciones de múltiples turnos.

Neuron AI te proporciona un sistema integrado para gestionar la memoria de una sesión de chat que realizas con el agente.

En muchas aplicaciones de preguntas y respuestas puedes mantener una conversación de ida y vuelta con el LLM, lo que significa que la aplicación necesita algún tipo de "memoria" de preguntas y respuestas anteriores, y alguna lógica para incorporarlas en su razonamiento actual.

Por ejemplo, si haces una pregunta de seguimiento como "¿Puedes ampliar el segundo punto?", esto no puede entenderse sin el contexto de los mensajes anteriores.

En el ejemplo siguiente puedes ver cómo el Agente no conoce mi nombre al principio:

```php
use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;

$message = Agent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("¿Cómo me llamo?"))
    ->getMessage();

echo $message->getContent();
// Lo siento, no conozco tu nombre. ¿Quieres contarme más sobre ti?
```

Claramente, el Agente no tiene ningún contexto sobre mí. Ahora intento presentarme en el primer mensaje, y luego preguntar por mi nombre:

```php
use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;

$agent = Agent::make()->setThreadId('chat_id');

$message = $agent->chat(new UserMessage("¡Hola, me llamo Valerio!"))->getMessage();
echo $message->getContent();
// Hola Valerio, encantado de conocerte, ¿en qué puedo ayudarte hoy?

$message = $agent->chat(new UserMessage("¿Recuerdas mi nombre?"))->getMessage();
echo $message->getContent();
// Claro, ¡tu nombre es Valerio!
```

### Alimentar una conversación previa

A veces ya tienes una representación de la conversación entre usuario y asistente y necesitas una forma de alimentar al agente con mensajes anteriores.

Solo puedes pasar un array de mensajes al `chat()` método. Esta conversación se cargará automáticamente en la memoria del agente y podrás seguir iterando sobre ella.

```php
use NeuronAI\Chat\Enums\MessageRole;
use NeuronAI\Chat\Messages\Message;

$message = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat([
        new Message(MessageRole::USER, "Hola, mi empresa se llama Inspector.dev"),
        new Message(MessageRole::ASSISTANT, "Genial, ¿en qué puedo ayudarte hoy?"),
        new Message(MessageRole::USER, "¿Cómo se llama la empresa para la que trabajo?"),
    ])
    ->getMessage();
    
echo $message->getContent();
// Trabajas para Inspector.dev
```

El último mensaje de la lista se considerará el más reciente.

## Cómo funciona el historial de chat

Neuron Agent toma la lista de mensajes intercambiados entre tu aplicación y el LLM y la convierte en un objeto llamado Historial de Chat. Es una parte crucial del framework porque el historial de chat debe gestionarse según la ventana de contexto del LLM subyacente.

Es importante devolver al LLM los mensajes anteriores para mantener el contexto de la conversación, pero si la lista de mensajes crece lo suficiente como para superar la ventana de contexto del modelo, la solicitud será rechazada por el proveedor de IA con un error grave.

Al gestionar los mensajes, el historial de chat intenta minimizar la pérdida de contexto. El recortador interno puede identificar un punto de corte ligeramente menos agresivo que el identificado inicialmente. Así que, para asegurarte de que la conversación del agente se mantenga dentro del límite, **deberías configurar la ventana de contexto en el historial de chat del agente con un margen del 5%-10% respecto al límite real del modelo subyacente**.

Si tu modelo trabaja con una ventana de contexto de 200K, podrías instanciar tu historial de chat con 190K, por ejemplo.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Chat\History\ChatHistoryInterface;
use NeuronAI\Chat\History\InMemoryChatHistory;

// Como propiedad interna
class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        ...
    }
    
    protected function contextWindow(): int
    {
        return 190_000;
    }
}

// Establece la ventana de contexto en tiempo de ejecución
$agent->setContextWondow(190_000);
```

## Almacén de mensajes

El almacén de mensajes es el componente responsable de almacenar mensajes. Es lo que puedes implementar o extender para adaptarlo a las necesidades de tu aplicación.

### Registrar un almacén de mensajes

Por defecto, Neuron usa un almacén de mensajes "en memoria". Eso significa que conserva los mensajes solo durante el ciclo de ejecución actual. Pero, si quieres persistir los mensajes entre sesiones, puedes decirle al agente que use un componente diferente implementando el `chatHistory` método en la clase Agent.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Chat\History\ChatHistoryInterface;
use NeuronAI\Chat\History\InMemoryChatHistory;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        ...
    }
    
    protected function messageStore(): ChatHistoryInterface
    {
        return new InMemoryMessageStore();
    }
}
```

### InMemoryMessageStore

Simplemente almacena la lista de mensajes en un array. Se mantiene en memoria solo durante la ejecución actual. Se usa por defecto si no registras explícitamente otro componente.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\History\MessageStoreInterface;
use NeuronAI\Chat\History\InMemoryMessageStore;

class MyAgent extends Agent
{
    ...
    
    protected function messageStore(): MessageStoreInterface
    {
        return new InMemoryMessageStore();
    }
}
```

### FileMessageStore

Este componente te permite persistir la conversación en curso con el agente en un archivo y reanudarla más tarde. Para crear una instancia de `FileChatHistory` necesitas pasar la ruta absoluta del `directorio` donde quieres almacenar las conversaciones, y la única `clave` para la conversación actual.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\History\MessageStoreInterface;
use NeuronAI\Chat\History\FileMessageStore;

class MyAgent extends Agent
{
    ...
    
    protected function messageStore(): MessageStoreInterface
    {
        return new FileMessageStore(
            directory: '/home/app/storage/neuron',
        );
    }
}
```

El `clave` El parámetro te permite almacenar distintos archivos para separar conversaciones. Puedes usar una clave única para cada usuario, o el ID de un hilo, para que los usuarios puedan almacenar múltiples conversaciones.

### SQLMessageStore

Este componente te permite almacenar la conversación en curso en una base de datos SQL. Antes de usar este componente debes crear la tabla en tu base de datos para almacenar mensajes. Aquí tienes el script SQL:

```sql
CREATE TABLE chat_messages (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    thread_id VARCHAR(255) NOT NULL,
    message_id VARCHAR(64) NOT NULL,
    role VARCHAR(32) NOT NULL,
    content LONGTEXT NULL,
    meta LONGTEXT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    INDEX idx_thread_id (thread_id),
    UNIQUE INDEX idx_thread_message (thread_id, message_id)
);
```

Puedes personalizar esta tabla añadiendo más columnas, eventualmente para agregar una relación con tus usuarios o casos de uso similares. También puedes personalizar el nombre de la tabla pasando uno propio al crear la instancia.

Para crear una instancia de `SQLChatHistory` necesitas pasar el `thread_id` para separar distintos hilos de conversación, y la `PDO` conexión a la base de datos.

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\History\MessageStoreInterface;
use NeuronAI\Chat\History\SQLMessageStore;

class MyAgent extends Agent
{
    ...
    
    protected function messageStore(): MessageStoreInterface
    {
        return new SQLMessageStore(
            pdo: new \PDO("mysql:host=localhost;dbname=DB_NAME;charset=utf8mb4", "DB_USER", "DB_PASS"),
            table: 'chat_history',
        );
    }
}
```

Si tu aplicación está construida sobre un marco de trabajo, puedes obtener fácilmente la conexión PDO desde el ORM. Aquí tienes un par de ejemplos en el contexto de aplicaciones Laravel o Symfony.

#### Laravel

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\History\MessageStoreInterface;
use NeuronAI\Chat\History\SQLMessageStore;

class MyAgent extends Agent
{
    ...
    
    protected function messageStore(): MessageStoreInterface
    {
        return new SQLMessageStore(
            pdo: \DB::connection()->getPdo(),
            table: 'chat_history',
        );
    }
}
```

#### Symfony

Puedes registrar tu agente como un servicio con una instancia de `Doctrine\DBAL\Connection` como dependencia del constructor:

```php
namespace App\Neuron;

use Doctrine\DBAL\Connection;
use NeuronAI\Agent\Agent;
use NeuronAI\Chat\History\MessageStoreInterface;
use NeuronAI\Chat\History\SQLMessageStore;

class MyAgent extends Agent
{
    public function __construct(protected Connection $connection)
    {
        parent::__construct();
    }
    
    protected function messageStore(): MessageStoreInterface
    {
        return new SQLMessageStore(
            pdo: $this->connection->getNativeConnection(),
            table: 'chat_history',
        );
    }
}
```

### EloquentMessageStore

Deberías crear tu propio modelo Eloquent y pasar la cadena de la clase como argumento del constructor. El modelo puede tener relaciones, scopes, atributos, etc. personalizados, pero la estructura básica debe basarse en este script de migración:

```bash
php artisan make:migration create_chat_messages_table --create=chat_messages
```

```php
Schema::create('chat_messages', function (Blueprint $table) {
     $table->id();
     $table->string('thread_id')->index();
     $table->string('message_id');
     $table->string('role');
     $table->json('content');
     $table->json('meta')->nullable();
     $table->datetime('archived_at')->nullable();
     $table->timestamps();

     $table->unique(['thread_id', 'message_id']);
     $table->index(['thread_id', 'id']); // Para ordenar y recortar de forma eficiente
});
```

#### Ejemplo del modelo ChatMessage

```php
class ChatMessage extends Model
{
    protected $fillable = [
        'thread_id', 'message_id', 'role', 'archived_at', 'content', 'meta'
    ];
    
    protected $casts = [
        'archived_at' => 'datetime',
        'content' => 'array', 
        'meta' => 'array'
    ];
    
    /**
     * devuelve BelongsTo<Conversation, $this>
     */
    public function conversation(): BelongsTo
    {
        return $this->belongsTo(Conversation::class, 'thread_id');
    }
}
```

Úsalo en tu agente:

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\History\MessageStoreInterface;
use NeuronAI\Chat\History\EloquentMessageStore;

class MyAgent extends Agent
{
    ...
    
    protected function messageStore(): MessageStoreInterface
    {
        return new EloquentMessageStore(ChatMessage::class);
    }
}
```

## Implementar un historial de chat personalizado

Puedes crear una implementación personalizada del historial de chat para admitir una capa persistente diferente, simplemente implementando `AbstractChatHistory`. Te permite heredar varios comportamientos para la gestión interna del historial, por lo que solo tienes que implementar un par de métodos para guardar mensajes en el sistema de almacenamiento que quieras usar.

```php
interface MessageStoreInterface
{
    /**
     * El contexto activo del modelo del hilo, en orden de inserción.
     *
     * @return Message[]
     */
    public function loadActive(string $threadId): array;

    /**
     * Cada mensaje del hilo, incluidos los archivados, en orden de inserción. Con un
     * límite, solo los $limit mensajes más recientes antes de $before (el más reciente cuando
     * es null). Un $before desconocido para el hilo no devuelve mensajes.
     *
     * @return Message[]
     */
    public function loadAll(string $threadId, ?int $limit = null, ?string $before = null): array;

    /**
     * Idempotente: se omite un mensaje cuyo ID ya esté almacenado en el hilo.
     */
    public function append(string $threadId, Message $message): void;

    /**
     * Archiva los $count mensajes activos más antiguos del hilo.
     */
    public function archive(string $threadId, int $count): void;

    /**
     * Elimina el hilo, incluidos los mensajes archivados.
     */
    public function clear(string $threadId): void;
}
```

### Serializar/Deserializar mensajes

Cuando el ChatHistory necesita almacenar un mensaje, este debe serializarse. Del mismo modo, cuando se instancia el componente ChatHistory, debería cargar todos los mensajes anteriores desde el almacenamiento subyacente (base de datos, caché, etc.) y deserializarlos al tipo de mensaje original.

Para serializar/deserializar mensajes de forma consistente, el `AbstractChatHistory` te proporciona `serializeMessage()` y `deserializeMessage()` métodos. Aquí tienes un ejemplo de cómo usarlos en una implementación hipotética de historial de chat basada en base de datos:

```php
<?php

namespace NeuronAI\Chat\History;

use NeuronAI\Chat\Messages\Message;

class DatabaseChatHistory extends AbstractChatHistory
{
    public function __construct(protected \PDO $db) 
    {
        // Recuperar la conversación actual del almacenamiento subyacente
        $messages = $this->db->select(...);
        
        // Deserializar para inicializar correctamente los tipos de mensaje correctos con los datos correctos.
        $this->history = $this->deserializeMessages($messages);
    }

    protected function onNewMessage(Message $message): void
    {
        // Almacenar la versión serializada.
        $this->db->insert($message->jsonSerialize());
    }

    ...
}
```

## Memoria semántica a largo plazo

Gracias a la extensión RAG puedes habilitar el almacenamiento y la recuperación de recuerdos a lo largo de múltiples conversaciones. Así, los usuarios con varios hilos activos pueden ver cómo el agente recuerda sus conversaciones y preferencias anteriores.

<a href="https://docs.neuron-ai.dev/neuron-v3-es/rag/retrieval.md#semantic-memory" class="button primary" data-icon="arrow-right-long">Memoria semántica</a>
