> 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-unity-sdk/features/long-term-memory/how-long-term-memory-works.md).

# 长期记忆的工作原理

了解长期记忆的会话生命周期、记忆如何按用户和角色作用域划分，以及事实如何被提取、去重和注入。

长期记忆（LTM）为 Convai 角色提供一个持久的、按用户划分的知识存储，可跨独立对话会话保留。安全培训讲师记得某位学员上周通过了第 3 模块。企业入职助手知道某位员工已经查看过哪些政策。医疗培训指南会记住某位用户更喜欢详细解释而不是摘要。本页说明其底层机制——LTM 存储什么、如何按用户范围划分记忆，以及事实何时在会话中流入和流出。

### 会话生命周期

每个 LTM 会话经历四个阶段：

```mermaid
sequenceDiagram
    参与方 App 作为你的应用程序
    参与方 SDK 作为 Convai Unity SDK
    参与方 Convai 作为 Convai

    App->>SDK: SetEndUserIdentityProvider(provider)
    App->>SDK: ConnectAsync()
    SDK->>Convai: connect(end_user_id, character_id)
    Convai-->>SDK: inject stored memories into context
    Note over SDK,Convai: 对话在记忆上下文中继续
    SDK->>Convai: session ends
    Convai-->>Convai: extract and store new facts
```

**连接：** SDK 会发送 `end_user_id` 和 `character_id` 到 Convai，在会话开始时。Convai 会将该组合解析为已存储的记忆集，并在生成第一条回复之前将任何现有事实注入角色的上下文中。

**对话：** 角色会基于已注入的事实进行回应——它不需要被告知用户的姓名、角色或历史，因为这些上下文已经存在。对话中共享的新信息不会实时存储；它会保留在会话缓冲区中。

**会话结束：** 当会话关闭时，Convai 会处理对话记录，并将有意义的事实（姓名、角色、偏好、已完成的任务、明确说明的历史）提取为自然语言 `MemoryRecord` 条目。这些内容会存储在 `end_user_id + character_id` 键下。

**下一次连接：** 在下一次会话中，这些新事实将可用，并会与之前存储的内容一起注入。

### 记忆范围

每条记忆记录都严格限定于一个用户–角色配对。

```
end_user_id + character_id → MemoryRecord 条目集合
```

为用户存储的事实 `一个` 在角色 `X` 对用户始终不可见 `B` 或对角色 `Y`。如果你的应用使用多个角色，则每个角色都会为每个用户构建自己的独立记忆集。不存在跨角色的记忆共享。

该 `end_user_id` 是由你的 `IEndUserIdentityProvider` （或由默认的 `DeviceEndUserIdProvider`）提供的稳定字符串标识符。如果该标识符在会话之间发生变化——例如，因为 `PlayerPrefs` 已被清除——Convai 会将新值视为新用户。之前标识符中的记忆不会继承过来。

### 记忆记录

每条已存储的事实都是一个 `MemoryRecord` ，带有一个自然语言 `Memory` 字符串和一个自动分配的 `Id`.

示例 `Memory` 取值：

* `“用户的名字是 Jordan。”`
* `“Jordan 已于 2025-03-12 完成受限空间进入认证。”`
* `“Jordan 更喜欢逐步解释而不是摘要。”`

事实由 Convai 以第三人称写入。角色将它们用作背景上下文，而不是逐字背诵的脚本。

### 去重

当新会话产生的事实在语义上与现有记忆等同时，Convai 会更新现有的 `MemoryRecord` ，而不是创建重复项。例如，如果用户将自己的名字从 `“Jordan”` 到 `“Jordan Kim”`更正为“Jordan Kim”，现有的姓名记录会直接原地更新。 `事件` 字段在 `MemoryAddResult` 返回 `"update"` 用于去重写入，而 `"add"` 用于新记录。

### LTM 不做什么

了解 LTM 的局限性可以避免错误假设：

* **LTM 不支持实时查询。** 记忆注入发生在连接时，而不是在对话过程中按需触发。角色无法在会话中途查询记忆存储。
* **LTM 不保证每个口述细节都会被存储。** Convai 会提取它判断为有意义且持久的事实。简短的、附带性的言论可能不会被保留。
* **LTM 不会在不同角色之间共享记忆。** 每个角色都会为每个用户拥有独立的记忆集。
* **LTM 默认未启用。** 记忆已禁用（`MemorySettings.IsEnabled = false`），直到你在 Convai 控制台中或通过脚本 API 显式启用它。

### 下一步

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

{% content-ref url="/pages/c12fc9539ece3543a049cf5c334655c9bb0a6a3c" %}
[终端用户身份](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/end-user-identity.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-unity-sdk/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.