> 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-zh/dai-li/chat-history-and-memory.md).

# 聊天历史与记忆

了解 Neuron AI 如何管理多轮对话。

Neuron AI 为你提供了一个内置系统，用于管理你与代理进行的聊天会话的记忆。

在许多问答应用中，你可以与 LLM 进行来回对话，这意味着应用需要某种过去问题和答案的“记忆”，以及将这些内容纳入当前思考的逻辑。

例如，如果你问一个后续问题，比如“你能详细解释第二点吗？”，如果没有前面消息的上下文，这句话是无法理解的。

在下面的示例中，你可以看到 Agent 起初并不知道我的名字：

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

$message = Agent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("我叫什么名字？"))
    ->getMessage();

echo $message->getContent();
// 抱歉，我不知道你的名字。你想多告诉我一些关于你自己的信息吗？
```

显然，Agent 对我没有任何上下文。现在我先在第一条消息里介绍自己，然后再问它我的名字：

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

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

$message = $agent->chat(new UserMessage("嗨，我叫 Valerio！"))->getMessage();
echo $message->getContent();
// 嗨，Valerio，很高兴认识你，今天我能帮你什么？

$message = $agent->chat(new UserMessage("你还记得我的名字吗？"))->getMessage();
echo $message->getContent();
// 当然，你的名字是 Valerio！
```

### 提供一段先前的对话

有时你已经有一份用户与助手对话的表示形式，你需要一种方式把先前的消息提供给代理。

你只需向 `chat()` 方法传入一个消息数组即可。该对话会自动加载到代理记忆中，你可以继续在其基础上迭代。

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

$message = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat([
        new Message(MessageRole::USER, "嗨，我的公司叫 Inspector.dev"),
        new Message(MessageRole::ASSISTANT, "太好了，今天我能帮你什么？"),
        new Message(MessageRole::USER, "我工作的公司叫什么名字？"),
    ])
    ->getMessage();
    
echo $message->getContent();
// 你为 Inspector.dev 工作
```

列表中的最后一条消息将被视为最新消息。

## 聊天历史的工作原理

Neuron Agent 会把你的应用与 LLM 之间交换的消息列表放入一个名为 Chat History 的对象中。它是框架中至关重要的一部分，因为聊天历史需要根据底层 LLM 的上下文窗口来管理。

将过去的消息发送回 LLM 以保持对话上下文非常重要，但如果消息列表增长到超过模型的上下文窗口，请求就会因硬错误被 AI 提供商拒绝。

在管理消息时，聊天历史会尽量减少上下文丢失。内部的裁剪器可以识别一个比最初识别点稍微不那么激进的切断点。因此，为了确保代理对话保持在限制范围内， **你应该在代理聊天历史中将上下文窗口配置为比底层模型实际限制小 5%-10% 的余量**.

例如，如果你的模型使用 200K 的上下文窗口，你可以把聊天历史实例化为 190K。

```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 contextWindow(): int
    {
        return 190_000;
    }
}

// 在运行时设置上下文窗口
$agent->setContextWondow(190_000);
```

## 消息存储

消息存储是负责保存消息的组件。你可以实现或扩展它，以满足你的应用需求。

### 注册消息存储

默认情况下，Neuron 使用“内存中”的消息存储。这意味着它只会在当前执行周期内保留消息。但是，如果你想跨会话持久化消息，可以通过实现 `chatHistory` 方法来告诉 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

它只是将消息列表存储到数组中。它仅在当前执行期间保留在内存中。如果你没有显式注册其他组件，它会被默认使用。

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

这个组件让你能够将与代理的持续对话持久化到文件中，并在之后恢复它。要创建 `FileChatHistory` 的实例，你需要传入 `目录` 的绝对路径，以及当前对话的唯一 `键` 。

```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',
        );
    }
}
```

该 `键` 参数允许你把不同的文件用于分离不同的对话。你可以为每个用户使用唯一键，或者使用线程 ID，这样用户就可以保存多个对话。

### SQLMessageStore

这个组件允许你将持续进行的对话存储到 SQL 数据库中。在使用该组件之前，你必须先在数据库中创建用于存储消息的表。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)
);
```

你可以自定义这张表，最终添加更多列，例如关联到用户或类似用例。你也可以在创建实例时传入自定义表名来进行自定义。

要创建 `SQLChatHistory` 的实例，你需要传入 `thread_id` ，用于区分不同的会话线程，以及 `PDO` 与数据库的连接。

```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',
        );
    }
}
```

如果你的应用构建在某个框架之上，你可以很容易地从 ORM 获取 PDO 连接。下面是在 Laravel 或 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

你可以将你的代理注册为一个服务，并将 `Doctrine\DBAL\Connection` 的实例作为构造函数依赖：

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

你应该创建自己的 Eloquent 模型，并将类字符串作为构造函数参数传入。该模型可以有自定义关系、作用域、属性等，但基础结构必须基于这个迁移脚本：

```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']); // 为了高效排序和裁剪
});
```

#### 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'
    ];
    
    /**
     * return BelongsTo<Conversation, $this>
     */
    public function conversation(): BelongsTo
    {
        return $this->belongsTo(Conversation::class, 'thread_id');
    }
}
```

在你的代理中使用：

```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);
    }
}
```

## 实现自定义聊天历史

你可以通过实现 `AbstractChatHistory`来创建聊天历史的自定义实现，以支持不同的持久化层。它允许你继承内部历史管理的若干行为，因此你只需实现少数几个方法，就能将消息保存到你想使用的存储系统中。

```php
interface MessageStoreInterface
{
    /**
     * 线程中当前模型上下文，按插入顺序。
     *
     * @return Message[]
     */
    public function loadActive(string $threadId): array;

    /**
     * 线程中的每条消息，包括已归档的消息，按插入顺序。带有
     * limit 时，仅返回 before 之前最新的 $limit 条消息（如果
     * 为 null，则为最新的消息）。线程中未知的 before 不会返回任何消息。
     *
     * @return Message[]
     */
    public function loadAll(string $threadId, ?int $limit = null, ?string $before = null): array;

    /**
     * 幂等：ID 已经存储在该线程中的消息会被跳过。
     */
    public function append(string $threadId, Message $message): void;

    /**
     * 归档该线程中最旧的 $count 条活动消息。
     */
    public function archive(string $threadId, int $count): void;

    /**
     * 删除线程，包括已归档消息。
     */
    public function clear(string $threadId): void;
}
```

### 序列化/反序列化消息

当 ChatHistory 需要存储一条消息时，必须先对其进行序列化。同样，当 ChatHistory 组件被实例化时，它应当从底层存储（数据库、缓存等）中加载所有先前消息，并将它们反序列化为原始消息类型。

为了统一地序列化/反序列化消息， `AbstractChatHistory` 为你提供了 `serializeMessage()` 和 `deserializeMessage()` 方法。下面是一个在假设的数据库聊天历史实现中如何使用它们的示例：

```php
<?php

namespace NeuronAI\Chat\History;

use NeuronAI\Chat\Messages\Message;

class DatabaseChatHistory extends AbstractChatHistory
{
    public function __construct(protected \PDO $db) 
    {
        // 从底层存储中获取当前对话
        $messages = $this->db->select(...);
        
        // 反序列化后正确初始化带有正确数据的消息类型。
        $this->history = $this->deserializeMessages($messages);
    }

    protected function onNewMessage(Message $message): void
    {
        // 存储序列化后的版本。
        $this->db->insert($message->jsonSerialize());
    }

    ...
}
```

## 长期语义记忆

得益于 RAG 扩展，你可以启用跨多个对话的记忆存储和召回。因此，拥有多个活跃线程的用户可以看到代理记住他们过去的对话和偏好。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/rag/retrieval.md#semantic-memory" class="button primary" data-icon="arrow-right-long">语义记忆</a>
