> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/long-term-memory.md).

# 长期记忆

## 跨会话的持久角色记忆

长期记忆（LTM）使 Convai 角色能够在不同的游玩会话之间记住关于单个用户的事实。与每次都从头开始不同，启用了 LTM 的角色可以回忆之前的交流，随着时间推移调整其行为，并与每位玩家建立关系。

记忆存储在 Convai 后端，按用户和按角色分区，并在每次新会话开始时自动注入 AI 的上下文中。SDK 的作用是在每次连接时发送一个稳定的用户标识符，然后为需要以编程方式控制记住哪些内容的应用程序提供脚本 API。

## 工作原理

当会话开始时，SDK 会发送一个 `end_user_id` 到 Convai 服务器，并附带常规的连接请求。服务器将该标识符解析为内部说话者记录，然后查找存储在键 `speaker_id:character_id`。如果为该角色启用了记忆，则这些记忆会在生成第一条回复之前被注入到 AI 上下文中。

在对话结束时，后端会从交流中提取新事实，并将它们追加到记忆存储中。这个循环在每次会话中重复，使角色对每个单独用户的了解自然增长。

```mermaid
flowchart TD
    A([应用程序启动]) --> B[SDK 从身份提供者\n读取 end_user_id]
    B --> C[会话连接请求\n附加 end_user_id]
    C --> D{该角色\n已启用记忆？}
    D -- 否 --> E[正常会话，\n无记忆上下文]
    D -- 是 --> F[后端解析\nend_user_id → speaker_id]
    F --> G[加载记忆\nspeaker_id : character_id]
    G --> H[将记忆上下文\n注入 AI 提示]
    H --> I[对话进行中]
    I --> J[后端提取\n新事实]
    J --> K[追加到记忆存储]
    K --> L([会话结束])
    E --> L
```

## 关键概念

| 概念                          | 描述                                                                            |
| --------------------------- | ----------------------------------------------------------------------------- |
| **end\_user\_id**           | 应用程序为每个最终用户提供的稳定字符串标识符。在每次连接时发送到 Convai 服务器。默认使用设备标识符或持久化的 GUID。              |
| **记忆分区**                    | 特定用户-角色对的服务器端存储桶，在内部按以下键标识 `speaker_id:character_id`。该对的所有记忆都存放在这里。           |
| **MemoryRecord**            | 分区中存储的一条事实。具有一个 `Id`，一个 `Memory` 字符串（自然语言事实文本）、时间戳，以及一个可选的元数据字典。              |
| **最终用户元数据**                 | 应用程序可在连接时附加到用户的任意键值数据（姓名、角色、区域设置等）。存储在服务器上，并可通过脚本 API 访问。                     |
| **DeviceEndUserIdProvider** | 默认的身份提供者。玩家构建中使用设备的唯一标识符，Unity 编辑器中使用持久化的 GUID。无需配置。                          |
| **MemoryService**           | 在以下位置公开的 REST API 服务： `ConvaiRestClient.Memory`。提供对记忆记录的添加、列出、获取和删除操作。        |
| **EndUsersService**         | 在以下位置公开的 REST API 服务： `ConvaiRestClient.EndUsers`。提供对最终用户记录的列出、获取、更新元数据和删除操作。 |

## 本节内容

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>快速入门</strong></td><td>为角色启用记忆，并在无需编写任何代码的情况下验证跨会话回忆。</td></tr><tr><td><strong>最终用户身份</strong></td><td>最终用户如何在会话之间被识别，以及如何提供你自己的标识符。</td></tr><tr><td><strong>为角色启用记忆</strong></td><td>通过 Convai 控制台或脚本 API 打开或关闭长期记忆。</td></tr><tr><td><strong>记忆管理 API</strong></td><td>以编程方式添加、列出、检索和删除单个记忆记录。</td></tr><tr><td><strong>最终用户管理</strong></td><td>使用编辑器工具或脚本 API 浏览和管理最终用户记录。</td></tr><tr><td><strong>使用示例</strong></td><td>常见长期记忆场景的完整代码示例。</td></tr><tr><td><strong>故障排查与诊断</strong></td><td>诊断记忆为何未能持久化，解决身份问题，并修复 API 错误。</td></tr></tbody></table>

## 结论

长期记忆将自然对话与持久的用户历史连接起来——角色会自动积累知识，而 SDK 在你需要时为你提供编程控制。先从快速入门开始，为角色启用记忆，并查看它端到端地工作。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/long-term-memory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.