> 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).
# 长期记忆
让你的 Convai 角色跨会话持久记住各个用户。了解该功能如何工作，并浏览完整参考文档。
## 会话间持久的角色记忆
长期记忆（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** | 在 `ConvaiRestClient.Memory`上暴露的 REST API 服务。提供对记忆记录的添加、列出、获取和删除操作。 |
| **EndUsersService** | 在 `ConvaiRestClient.EndUsers`。提供对最终用户记录的列出、获取、更新元数据和删除操作。 |
## 本节内容
快速开始
为角色启用记忆，并在不编写任何代码的情况下验证跨会话回忆。
最终用户身份
最终用户如何在会话之间被识别，以及如何提供你自己的标识符。
为角色启用记忆
通过 Convai 仪表板或脚本 API 打开或关闭长期记忆。
记忆管理 API
以编程方式添加、列出、检索和删除单个记忆记录。
最终用户管理
使用编辑器工具或脚本 API 浏览和管理最终用户记录。
使用示例
常见长期记忆场景的完整代码示例。
故障排除与诊断
诊断记忆为何没有持久化，解决身份问题，并修复 API 错误。
## 结论
长期记忆将自然对话与持久化的用户历史连接起来——角色会自动积累知识，而在你需要时，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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/long-term-memory.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.