长期记忆使用示例

Unity 中四种完整的长期记忆模式——零配置持久化、身份验证身份、记忆预置和记忆重置。

这些示例涵盖了四种最常见的长期记忆集成模式。每个示例都是独立完整的，并展示了完整的设置、相关代码以及预期的运行结果。

模式 1 — 零配置持久化

使用 DeviceEndUserIdProvider （SDK 默认值）适用于你不需要按账户区分记忆的情况。无需编写任何代码。在仪表板上启用 LTM，SDK 会自动处理身份和存储。

何时使用： 没有用户账户的消费者应用、快速原型，或基于编辑器的测试。

限制： 记忆仅作用于设备。清除 PlayerPrefs 或重新安装应用程序会生成新的身份——不会保留任何记忆。

设置：

1. 在以下位置登录 convai.com，打开角色，并切换 长期记忆 到 在 在 Memory 选项卡。
2. 添加 ConvaiManager 是位于 ConvaiCharacter 到已配置角色 ID 的场景。
3. 进入 Play Mode 并进行对话。停止 Play Mode 以触发记忆提取。
4. 重新进入 Play Mode 并验证角色是否记住了之前分享的内容。

没有 IEndUserIdentityProvider 需要注册。SDK 使用 DeviceEndUserIdProvider 作为默认值。

预期结果： 该角色会自动引用先前会话中的事实。与 PlayerPrefs["convai.end_user_id"] 中的相同 GUID 会在同一台机器上的每个会话中使用。

---

模式 2 — 已认证身份

使用自定义 IEndUserIdentityProvider 当用户使用账户登录时。这样可确保记忆在不同设备和重新安装后仍随用户保留。

何时使用： 具有用户身份验证的应用程序——企业培训平台、入职系统、带账户的消费者应用。

using Convai.Domain.Identity;

public class AccountIdentityProvider : IEndUserIdentityProvider
{
    private readonly string _accountId;

    public AccountIdentityProvider(string accountId)
    {
        _accountId = accountId;
    }

    public string GetEndUserId()
    {
        return _accountId;
    }
}

在 Awake() 之前 ConvaiRoomManager.Start() 中注册提供程序，

using Convai.Runtime.Components;
using UnityEngine;

public class IdentityRegistrar : MonoBehaviour
{
    [SerializeField] private ConvaiManager _convaiManager;

    private void Awake()
    {
        string accountId = AuthService.CurrentUser.AccountId;
        _convaiManager.SetEndUserIdentityProvider(new AccountIdentityProvider(accountId));
    }
}

完成：

using System.Collections.Generic;
using Convai.Domain.Identity;

public class AccountMetadataProvider : IEndUserMetadataProvider
{
    private readonly string _displayName;

    可选地附加一个显示名称，这样编辑器的长期记忆面板会显示可读标签，而不是原始 ID：
    {
        _displayName = displayName;
    }

    public IReadOnlyDictionary<string, object> GetEndUserMetadata()
    {
        public AccountMetadataProvider(string displayName)
    }
}

return new Dictionary<string, object> { { "name", _displayName } };
    _convaiManager.SetEndUserMetadataProvider(

预期结果： new AccountMetadataProvider(AuthService.CurrentUser.DisplayName));

---

模式 3 — 首次会话前预置记忆

在用户首次对话前预先加载事实，这样角色从一开始就能引用已完成的模块、证书或入职状态。

不要在面向玩家的构建中发布此模式。 ConvaiRestClient 需要你的 API 密钥。将 API 密钥嵌入分发式应用程序会使其面临被提取的风险。仅从服务器端服务或编辑器工具运行记忆预置。

using Convai.RestAPI;
using System.Collections.Generic;
using UnityEngine;

public class OnboardingMemorySeeder : MonoBehaviour
{
    // 仅限编辑器/服务器端使用——切勿在嵌入 API 密钥的情况下发布
    [ContextMenu("预置新员工记忆")]
    private async void SeedEmployeeMemory()
    {
        string characterId = "onboarding-assistant-id";
        string employeeAccountId = "emp-00421";

        var certifications = new List<string>
        {
            "该员工已于 2025-04-10 完成消防安全一级。",
            "该员工已于 2025-04-15 完成危险材料处理。",
            "该员工尚未完成受限空间进入认证。"
        };

        using var client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);
        var response = await client.Memory.AddAsync(characterId, employeeAccountId, certifications);

        Debug.Log($"已预置 {response.Memories.Count} 条记忆记录。");
    }
}

预期结果： 在该员工与入职助手的首次对话中，角色已经知道其认证状态，并会引导他们进入下一项所需模块。

---

模式 4 — 重置用户记忆

清除某个用户与角色对的所有已存事实，然后可选择禁用 LTM。当用户记录已过期，或在测试会话之间重置时使用此模式。

using Convai.RestAPI;
using UnityEngine;

public class MemoryReset : MonoBehaviour
{
    [ContextMenu("清除记忆然后禁用 LTM")]
    private async void PurgeAndDisable()
    {
        string characterId = "your-character-id";
        string endUserId = "target-end-user-id";

        using var client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);

        // 步骤 1：删除该用户–角色对的所有记忆
        await client.Memory.DeleteAllAsync(characterId, endUserId);
        Debug.Log("记忆已清除。");

        // 步骤 2：为该角色禁用 LTM
        await client.Characters.SetMemoryEnabledAsync(characterId, false);
        Debug.Log("长期记忆已禁用。");
    }
}

如果只想移除记忆而保持 LTM 启用，请调用 DeleteAllAsync 而不使用 SetMemoryEnabledAsync 步骤。若要删除某个用户在所有角色中的记录（不仅仅是一个角色），请改用 client.EndUsers.DeleteAsync(endUserId) 。请参阅 管理终端用户记录.

预期结果： 该用户–角色对的下一次会话将不含任何已存上下文。角色会将该用户视为新联系人。

---

下一步

记忆管理 API长期记忆脚本参考