为角色启用记忆

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

在角色上启用和禁用记忆

长期记忆是一项可选择启用的功能，由角色级别控制。禁用记忆的角色不会积累或回忆任何事实，无论它参与多少会话。此页说明如何切换记忆的开关——通过 Convai 控制台完成常规流程，或者通过 CharacterService 脚本 API，当你需要通过程序进行控制时使用。

记忆默认关闭

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

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

通过 Convai 控制台启用

对于大多数项目，推荐通过 Convai 控制台中的角色设置页面启用记忆。无需编写代码，变更会立即对后续所有会话生效。有关控制台 UI 的详细步骤，请参阅 记忆设置文档.

1

在 Convai 控制台中打开你的角色

在以下位置登录 convai.com 并选择你要配置的角色。

2

导航到记忆设置

在角色编辑器中，选择 Memory 记忆 记忆设置 选项卡。

3

启用长期记忆

切换 长期记忆 并将其打开。该更改会立即在服务器端生效——无需更新 SDK 或重新编译。

通过脚本 API 启用

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

设置 ConvaiRestClient

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

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();
    }
}

ConvaiSettings 是用于存储你项目的 Convai API 密钥的 ScriptableObject。只需在 工具 → Convai → 配置. ConvaiSettings.Instance 中配置一次，它就会在运行时从 Resources 文件夹自动加载。

ConvaiRestClient 实现 IDisposable。完成后请始终将其释放，或者将其作为长期存在的单例进行管理，而不要为每次调用都创建一个新实例。

查找你的角色 ID： 角色 ID 是 角色 ID 上的字段值，位于你的 ConvaiCharacter 组件中的该字段，在 Inspector 面板里。它也会显示在角色页面的 Convai 仪表板.

检查记忆是否已启用

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 当角色从未配置过记忆时返回，与默认状态一致。

启用记忆

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}");
    }
}

禁用记忆

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}");
    }
}

禁用记忆不会 不是 删除已存储的记忆。现有的记忆记录会保留在分区中，如果之后重新启用记忆，它们仍会被回忆起来。若要在禁用前删除某个特定用户的所有存储记忆，请调用 MemoryService.DeleteAllAsync 第一步。

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将介绍如何通过程序读取、添加和删除单个记忆记录。