> 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 返回它；您的项目保存它并将其重新用作 `EndUserID`.             |
| `EndUserMetadata` | 随同发送的可选 JSON 上下文 `EndUserID` 在连接时。                  | 您的项目在聊天机器人组件上分配它。                                  |
| `SessionID`       | 一个本地会话链接标记，位于 `UConvaiChatbotComponent`。默认为 `"-1"`. | 插件在本地管理它。WebRTC 不会发送它 `StartSession`.              |

对于 WebRTC `StartSession` 流程，插件会读取 `EndUserID` 来自 `UConvaiChatbotComponent` 到 `IConvaiConnectionInterface`。将聊天机器人 `EndUserID` 之前 `StartSession`。还要在 `UConvaiPlayerComponent` 上设置相同的值，这样两个组件在您的项目中保持同步。

### 记忆生效前必须满足什么条件

角色要回忆起回归玩家之前，必须满足两个条件：

1. **已启用角色 LTM。** Convai 仪表板中新角色的 LTM 默认是禁用的。请在仪表板上或通过 **Convai Set LTM Status** 在蓝图中启用。参见 [为角色配置记忆](/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 会将该玩家视为新人。参见 [终端用户身份](/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
    参与者 Game 作为 Unreal 项目
    参与者 Chatbot 作为 UConvaiChatbotComponent
    participant Convai as Convai

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

如果 `EndUserID` 在构建连接参数时为空，插件会调用 `UConvaiUtils::GetDeviceUniqueIdentifier()` 作为回退方案。这适用于同一设备上的单个本地用户。它不适用于共享自助终端或基于账户的应用场景，在这些场景中每个用户都需要独立的记忆范围。

### 内容持久存储于何处

| Data              | 由谁存储                      | 备注                                                              |
| ----------------- | ------------------------- | --------------------------------------------------------------- |
| 角色 LTM 启用状态       | Convai                    | 通过仪表板或 **Convai Set LTM Status**.                               |
| Speaker ID 记录     | Convai                    | 通过 \`Convai                                                     |
| 记忆记录              | Convai                    | 在启用 LTM 时根据对话内容构建。插件不提供记忆记录的 CRUD 节点。                           |
| `EndUserID`       | 您的项目                      | 保存返回的 `SpeakerID`、账户 ID 或其他稳定标识符。                               |
| `EndUserMetadata` | 您的项目                      | 在连接时发送的可选 JSON 字符串。                                             |
| `SessionID`       | `UConvaiChatbotComponent` | 本地会话链接标记。由 `ResetConversation()`清除。WebRTC 不会发送它 `StartSession`. |

`EndUserMetadata` 是一个 JSON 字符串。可将其用于附加上下文，例如显示名称或角色：

```json
{"name": "Alex", "role": "现场技术员", "training_module": "消防安全"}
```

### 会话连续性与重置

`EndUserID` 控制加载哪一个长期记忆。 `SessionID` 控制聊天机器人组件上的本地会话链接。

调用 `ResetConversation()` 将 `SessionID` 改回 `"-1"`。这会启动一个新的本地会话链接。它不会删除玩家的 Speaker ID 或 Convai 中的单条记忆记录。长期事实仍然与同一个 `EndUserID`.

### 常见设计选择

| 场景         | 推荐的身份标识                  | 为什么                           |
| ---------- | ------------------------ | ----------------------------- |
| 单人设备上的单人项目 | 设备回退或 Speaker ID         | 设备回退无需保存数据；Speaker ID 提供明确记录。 |
| 共享自助终端或培训站 | 每个用户使用 Speaker ID 或账户 ID | 避免多个用户共享同一个 `EndUserID`.      |
| 经过认证的企业应用  | 您账户系统中的稳定用户 ID           | 让记忆在不同设备间始终与用户账户绑定。           |

{% hint style="warning" %}
设置 `EndUserID` 在聊天机器人组件上于……之前 `StartSession`。在会话打开后更改身份会影响下一次会话，而不会影响已经打开的连接。
{% endhint %}

### 下一步

{% content-ref url="/pages/ce3e385378b893a9b53a3930b98101901dc9d6d8" %}
[长期记忆快速开始](/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" %}
[终端用户身份](/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" %}
[为角色配置记忆](/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 管理](/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 参考](/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.