> 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
    participant App as 你的应用程序
    participant SDK as Convai Unity SDK
    participant Convai as 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：会话结束
    Convai-->>Convai：提取并存储新事实
```

**连接：** SDK 会在会话开始时向 Convai 发送 `end_user_id` 和 `character_id` 。Convai 会根据这对标识找到已存储的记忆集，并在生成第一个回复之前，将其中已有的事实注入角色的上下文。

**对话：** 角色会结合注入的事实作出回应——由于相关上下文已就绪，因此无需再告知它用户的姓名、角色或经历。对话期间分享的新信息不会实时存储，而是保存在会话缓冲区中。

**会话结束：** 会话结束时，Convai 会处理对话记录，并将有意义的信息（姓名、角色、偏好、已完成的任务、陈述的经历）提取为自然语言形式的 `MemoryRecord` 条目。这些条目存储在以下键名下： `end_user_id + character_id` 。

**下次连接：** 在下一次会话中，新信息即可使用，并会与之前存储的信息一同注入。

### 记忆范围

每条记忆记录的范围都严格限定为一个用户与角色的组合。

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

为用户存储的事实 `A` 对角色可见 `X` 对用户永远不可见 `B` 对角色也不可见 `Y`。如果你的应用使用多个角色，每个角色都会为每位用户建立各自独立的记忆集合。不同角色之间不会共享记忆。

该 `end_user_id` 是由您的 `IEndUserIdentityProvider` （或默认的 `DeviceEndUserIdProvider`）提供的稳定字符串标识符。如果该标识符在不同会话之间发生变化（例如，因为 `PlayerPrefs` 被清除），Convai 会将新值视为新用户。之前标识符对应的记忆不会延续到新标识符。

### 记忆记录

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

示例 `Memory` 值：

* `"The user's name is Jordan."`
* `"Jordan completed confined-space entry certification on 2025-03-12."`
* `"Jordan prefers step-by-step explanations over summaries."`

Convai 会用第三人称记录事实。角色将其用作背景信息，而不是照本宣科。

### 去重

当新会话产生的事实与现有记忆在语义上等同时，Convai 会更新现有的 `MemoryRecord` ，而不是创建重复记录。例如，如果用户将自己的姓名从 `"Jordan"` 更正为 `"Jordan Kim"`，现有的姓名记录会原位更新。 `Event` 字段在 `MemoryAddResult` 中返回 `"update"` 表示写入时进行了去重，返回 `"add"` 则表示新增记录。

### LTM 不会做什么

了解 LTM 的局限性，有助于避免产生错误的预期：

* **LTM 不支持实时查询。** 记忆会在连接时注入，而非在对话过程中按需注入。角色无法在会话中途查询记忆存储。
* **LTM 不保证存储每个谈话细节。** Convai 会提取其判定为有意义且持久的事实。简短、偶然提及的内容可能不会被保留。
* **LTM 不会在不同角色之间共享记忆。** 每个角色针对每位用户都有独立的记忆集。
* **LTM 默认未启用。** 记忆处于禁用状态（`MemorySettings.IsEnabled = false`），除非你在 Convai 控制面板中或通过脚本 API 明确启用它。

### 后续步骤

{% content-ref url="/pages/d051c20fa3bb87461147abd07ac16642c7956362" %}
[长期记忆快速开始](https://docs.convai.com/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" %}
[终端用户身份](https://docs.convai.com/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.
