> 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/convai-unreal-engine-plugin/features/long-term-memory/how-long-term-memory-works.md).

# 长期记忆的工作原理

了解 Unreal 长期记忆如何使用角色设置、玩家身份和连接时参数来回忆先前交互。

长期记忆（LTM）会为 Convai 角色提供一个持久化记忆存储，范围限定为一名玩家和一个角色。只有在角色启用了 LTM，且聊天机器人在连接时发送稳定的 `EndUserID` 时，会话才能使用记忆。

### 关键术语

| 术语                | 说明                                                 | 由谁管理                                                                |
| ----------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
| `EndUserID`       | 连接时发送给 Convai 的玩家身份字符串。                            | 你的项目会在 `UConvaiChatbotComponent` 调用 `StartSession`.                 |
| `之前设置它。`          | SpeakerID                                          | 创建 Speaker ID 记录时由 Convai 返回的标识符。 `Convai 会返回该标识符；你的项目会保存它，并将其复用为`. |
| `EndUserMetadata` | 可选 JSON 上下文，与 `EndUserID` 一起在连接时发送。                | 你的项目会在聊天机器人组件上设置它。                                                  |
| `SessionID`       | 在 `UConvaiChatbotComponent`上的本地会话链接标记。默认值为 `"-1"`. | 插件会在本地管理它。WebRTC `StartSession`.                                    |

不会发送此标记。 `对于 WebRTC` StartSession `流程，插件会从` EndUserID `读取该值，并通过` UConvaiChatbotComponent `IConvaiConnectionInterface`传递。请在 `流程，插件会从` 调用 `对于 WebRTC`之前设置聊天机器人组件。此外，还要在 `UConvaiPlayerComponent` 上设置相同的值，以确保项目中的两个组件保持同步。

### 记忆正常工作所需的条件

角色要能够回忆起回访玩家的信息，必须满足以下两个条件：

1. **角色已启用 LTM。** Convai 控制面板中的新角色默认禁用 LTM。请在控制面板中启用，或在蓝图中使用 **Convai Set LTM Status** 启用。请参阅 [为角色配置记忆](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/configure-memory-for-a-character.md).
2. **连接时发送稳定的 `EndUserID` 。** Convai 会使用 `EndUserID` 和角色 ID 来加载正确范围的记忆。如果该值在不同会话之间发生变化，Convai 会将该玩家视为新用户。请参阅 [最终用户身份](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/end-user-identity.md).

### 连接时流程

在聊天机器人组件上设置身份，然后调用 `StartSession`。插件会构建连接参数并发送 `EndUserID` 以及可选的 `EndUserMetadata` 给 Convai。

```mermaid
sequenceDiagram
    participant Game as Unreal 项目
    participant Chatbot as UConvaiChatbotComponent
    参与方 Convai，作为 Convai

    Game->>Chatbot: 设置 EndUserID 和可选的 EndUserMetadata
    Game->>Chatbot: StartSession()
    Chatbot->>Convai: 使用角色 ID、EndUserID 和元数据建立连接
    Convai-->>Chatbot: 会话已连接，并载入记忆上下文
```

如果 `EndUserID` 在构建连接参数时为空，插件会调用 `UConvaiUtils::GetDeviceUniqueIdentifier()` 作为备用值。这适用于一台设备上的单个本地用户。但对于共享自助服务终端或基于账户的应用（其中每位用户都需要独立的记忆范围），这种做法并不合适。

### 数据分别存储在哪里

| 数据                | 存储方                       | 备注                                                             |
| ----------------- | ------------------------- | -------------------------------------------------------------- |
| 角色 LTM 启用状态       | Convai                    | 通过控制面板或 **Convai Set LTM Status**.                             |
| 说话人 ID 记录         | Convai                    | 通过 \`Convai 创建、列出和删除                                           |
| 记忆记录              | Convai                    | 启用 LTM 后，根据对话内容构建。插件不提供记忆记录的 CRUD 节点。                          |
| `EndUserID`       | 你的项目                      | 保存返回的 `SpeakerID`、账户 ID 或其他稳定标识符。                              |
| `EndUserMetadata` | 你的项目                      | 连接时发送的可选 JSON 字符串。                                             |
| `SessionID`       | `UConvaiChatbotComponent` | 本地对话链接标记。调用 `ResetConversation()`会清除此标记。WebRTC `StartSession`. |

`EndUserMetadata` 是一个 JSON 字符串。可用它提供显示名称或角色等补充上下文：

```json
{"name": "Alex", "role": "field technician", "training_module": "fire-safety"}
```

### 会话连续性与重置

`EndUserID` 决定加载谁的长期记忆。 `SessionID` 控制聊天机器人组件上的本地对话链接。

调用 `ResetConversation()` 设置 `SessionID` 返回到 `"-1"`。这会建立一个全新的本地对话链接，但不会删除玩家在 Convai 中的 Speaker ID 或个人记忆记录。长期事实仍与同一个 `EndUserID`.

### 常见设计选择

| 场景              | 推荐的身份标识                   | 原因                                |
| --------------- | ------------------------- | --------------------------------- |
| 在一台设备上运行的单人游戏项目 | 设备回退标识或 Speaker ID        | 设备回退标识无需保存数据；Speaker ID 则能明确标识记录。 |
| 共享的信息亭或培训工作站    | 为每位用户设置 Speaker ID 或账户 ID | 避免多个用户共用同一个 `EndUserID`.          |
| 经过身份验证的企业应用     | 账户系统中稳定的用户 ID             | 确保记忆与用户账户绑定，并可在不同设备间延续。           |

{% hint style="warning" %}
在聊天机器人组件上设置 `EndUserID` ，然后再调用 `StartSession`。会话开启后更改身份标识只会影响下一个会话，不会影响已建立的连接。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/ce3e385378b893a9b53a3930b98101901dc9d6d8" %}
[长期记忆快速开始](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/long-term-memory-quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/49e163546e7059153712733c44aa93aee597bbbe" %}
[终端用户身份](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/end-user-identity.md)
{% endcontent-ref %}

{% content-ref url="/pages/02906b279025410eed0c91dd64f1012b0304b626" %}
[为角色配置记忆](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/configure-memory-for-a-character.md)
{% endcontent-ref %}

{% content-ref url="/pages/490cd1c53fd291cb3dcb57f385b0eee013c3ae74" %}
[说话者 ID 管理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/speaker-id-management.md)
{% endcontent-ref %}

{% content-ref url="/pages/d52ddbffaafeb3f6c5f97016d40633bc7ea09f16" %}
[LTM Blueprint 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/ltm-blueprint-reference.md)
{% endcontent-ref %}


---

# 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/convai-unreal-engine-plugin/features/long-term-memory/how-long-term-memory-works.md?ask=<question>&goal=<user_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.
