> 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/unity-plugin-beta-overview/features/long-term-memory/enabling-memory-on-characters.md).

# 为角色启用记忆

通过 Convai 仪表板或 CharacterService 脚本 API 为每个角色启用或禁用长期记忆。默认关闭——需显式启用。

## 在角色上启用和禁用记忆

长期记忆是一项可选择启用的功能，由角色级别控制。无论参与多少次会话，记忆被禁用的角色都不会积累或回忆任何事实。本页说明如何打开或关闭记忆——对于典型工作流，可通过 Convai 仪表板；或者通过 `CharacterService` 脚本 API，在需要程序化控制时使用。

## 记忆默认关闭

每个角色在开始时都处于记忆禁用状态（`MemorySettings.IsEnabled = false`）。在你明确启用之前，不会存储或检索任何内容。这个默认设置是有意为之：记忆会以某些方式改变角色的行为，可能并不适合每一种部署，而且启用它会对该角色的所有会话全局生效——不仅仅是某一个场景或构建。

{% hint style="warning" %}
记忆设置是 **角色作用域，而不是项目作用域**。为某个角色启用记忆会影响连接到该角色 ID 的每个应用、SDK 版本和部署。如果该角色被多个项目或团队共享，请在启用前做好协调。
{% endhint %}

## 通过 Convai 仪表板启用

对于大多数项目，推荐通过 Convai 仪表板上的角色设置页面来启用记忆。无需编写代码，且更改会立即对后续所有会话生效。有关仪表板界面的详细演示，请参阅 [记忆设置文档](https://docs.convai.com/api-docs/convai-playground/character-customization/memory#memory-settings).

{% stepper %}
{% step %}
**在 Convai 仪表板中打开你的角色**

在 [convai.com](https://convai.com) 并选择你想要配置的角色。
{% endstep %}

{% step %}
**导航到记忆设置**

在角色编辑器中，从左侧面板选择 **记忆** 部分，然后打开 **记忆设置** 选项卡。
{% endstep %}

{% step %}
**启用长期记忆**

切换 **长期记忆** 开关。更改会立即在服务器端应用——无需更新 SDK 或重新编译。
{% endstep %}
{% endstepper %}

## 通过脚本 API 启用

使用 `CharacterService` 当你需要从代码中启用或禁用记忆时——例如在编辑器工具、管理员脚本或自动化测试套件中。

### 设置 ConvaiRestClient

所有程序化的角色操作都通过 `ConvaiRestClient`进行，它必须使用你的 API 密钥进行身份验证。

```csharp
using System;
using Convai.RestAPI;
using UnityEngine;

public class MemoryConfigurator : MonoBehaviour
{
    private ConvaiRestClient _client;

    private void Awake()
    {
        _client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);
    }

    private void OnDestroy()
    {
        _client?.Dispose();
    }
}
```

{% hint style="info" %}
`ConvaiSettings` 是存储你项目 Convai API 密钥的 ScriptableObject。请在 **工具 → Convai → 配置**. `ConvaiSettings.Instance` 下进行一次配置，它会在运行时自动从 `Resources` 文件夹中加载。
{% endhint %}

{% hint style="info" %}
`ConvaiRestClient` 实现了 `IDisposable`。完成后务必将其释放，或者将其作为长生命周期的单例来管理，而不是每次调用都创建一个新实例。
{% endhint %}

{% hint style="info" %}
**查找你的角色 ID：** 角色 ID 是 **角色 ID** 字段中的值，位于你的 `ConvaiCharacter` 组件在 Inspector 中的显示项里。它也会出现在角色页面的 [Convai 仪表板](https://convai.com).
{% endhint %}

### 检查记忆是否已启用

```csharp
using System;
using System.Threading;
using UnityEngine;

public async void CheckMemoryState(string characterId)
{
    try
    {
        bool isEnabled = await _client.Characters.GetMemoryEnabledAsync(characterId);
        Debug.Log($"角色 {characterId} 的记忆已启用：{isEnabled}");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] 读取记忆状态失败：{e.Message}");
    }
}
```

`GetMemoryEnabledAsync` 读取 `memory_settings.enabled` 标志位，来自角色记录。当角色从未配置过记忆时，它会返回 `false` ，与默认状态一致。

### 启用记忆

```csharp
public async void EnableMemory(string characterId, CancellationToken cancellationToken = default)
{
    try
    {
        await _client.Characters.SetMemoryEnabledAsync(characterId, enabled: true, cancellationToken);
        Debug.Log($"角色 {characterId} 的记忆已启用。");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] 启用记忆失败：{e.Message}");
    }
}
```

### 禁用记忆

```csharp
public async void DisableMemory(string characterId, CancellationToken cancellationToken = default)
{
    try
    {
        await _client.Characters.SetMemoryEnabledAsync(characterId, enabled: false, cancellationToken);
        Debug.Log($"角色 {characterId} 的记忆已禁用。");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] 禁用记忆失败：{e.Message}");
    }
}
```

{% hint style="warning" %}
禁用记忆并不会 **包含** 删除已存储的记忆。现有的记忆记录会保留在分区中，如果之后重新启用记忆，它们仍会被回忆出来。在禁用之前，如果要删除某个特定用户的所有已存储记忆，请调用 `MemoryService.DeleteAllAsync` 第一步。
{% endhint %}

## API 参考

所有方法都在 `ConvaiRestClient.Characters` (`CharacterService`).

| 方法                      | 签名                                                                   | 返回           |
| ----------------------- | -------------------------------------------------------------------- | ------------ |
| `GetMemoryEnabledAsync` | `(string characterId, CancellationToken ct = default)`               | `Task<bool>` |
| `SetMemoryEnabledAsync` | `(string characterId, bool enabled, CancellationToken ct = default)` | `Task`       |

## 结论

记忆由角色级别控制，并且默认关闭。对于最简单的工作流，请通过 Convai 仪表板启用它；或者在需要从代码中切换时使用 `CharacterService` 。一旦启用记忆，SDK 会在每次会话期间自动积累事实。下一页， [记忆管理 API](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/long-term-memory/memory-management-api.md)介绍如何以编程方式读取、添加和删除单个记忆记录。


---

# 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/unity-plugin-beta-overview/features/long-term-memory/enabling-memory-on-characters.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.