> 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).

# 长期记忆的工作原理

长期记忆（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** 在 Blueprints 中。参见 [为角色配置记忆](/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
    participant Game 作为 Unreal 项目
    participant 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": "fire-safety"}
```

### 会话连续性与重置

`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" %}
[Speaker 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 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/convai-unreal-engine-plugin/features/long-term-memory/how-long-term-memory-works.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.