> 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，当你需要通过程序进行控制时使用。

## 记忆默认关闭

每个角色一开始记忆都是禁用的（`MemorySettings.IsEnabled = false`）。在你显式启用之前，不会存储或检索任何内容。这个默认设置是有意为之：记忆会以某些方式改变角色的行为，未必适合每一种部署，而且启用后会全局影响该角色的所有会话——不只是某个场景或某个构建。

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

## 通过 Convai 控制台启用

对于大多数项目，推荐通过 Convai 控制台中的角色设置页面启用记忆。无需编写代码，变更会立即对后续所有会话生效。有关控制台 UI 的详细步骤，请参阅 [记忆设置文档](https://docs.convai.com/api-docs/convai-playground/character-customization/memory#memory-settings).

{% stepper %}
{% step %}
**在 Convai 控制台中打开你的角色**

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

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

在角色编辑器中，选择 **Memory** 记忆 **记忆设置** 选项卡。
{% 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($"Memory enabled for {characterId}: {isEnabled}");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] Failed to read memory state: {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($"Memory enabled for character {characterId}.");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] Failed to enable memory: {e.Message}");
    }
}
```

### 禁用记忆

```csharp
public async void DisableMemory(string characterId, CancellationToken cancellationToken = default)
{
    try
    {
        await _client.Characters.SetMemoryEnabledAsync(characterId, enabled: false, cancellationToken);
        Debug.Log($"Memory disabled for character {characterId}.");
    }
    catch (Exception e)
    {
        Debug.LogError($"[LTM] Failed to disable memory: {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 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/unity-plugin-beta-overview/features/long-term-memory/enabling-memory-on-characters.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.