使用示例

四种常见长期记忆场景的完整可运行代码：自动持久化、按账户范围的身份、首次会话前的记忆注入，以及有针对性的重置。

长期记忆实战

本页提供了最常见的长期记忆场景的完整可运行代码。每个示例都是自包含的，可直接放入 MonoBehaviour 中。示例采用安全培训模拟的场景——由一名指导受训者完成流程评估的讲师 NPC——但同样的模式适用于任何应用领域。

示例 1：零配置自动持久化

长期记忆开箱即用，适用于大多数项目。无需编写脚本。

场景： 一个消防安全培训模块，讲师角色会记住每位受训者的姓名以及两次会话之间的进度。

操作步骤：

在角色上启用记忆

在 Convai 控制台中，进入你的角色 → 记忆 → 记忆设置 → 启用 长期记忆。参见在角色上启用记忆以获取完整操作流程。

按常规方式设置场景

添加 ConvaiManager 和 ConvaiCharacter 到你的场景中，并提供有效的角色 ID。长期记忆不需要额外的组件或配置。

运行模拟

进入播放模式。 DeviceEndUserIdProvider 会在每次会话连接时自动发送一个稳定的设备标识。第一次对话后，后端会存储其提取到的任何事实。在之后的每次会话中，这些记忆会在第一次回复之前被注入。

无需实现任何内容。 身份提供器会自动注册，会话连接流程会发送 end_user_id ，无需任何额外设置。

在 Unity 编辑器中，所有播放模式会话共用一个 end_user_id ——一个持久化在 PlayerPrefs中的 GUID。启动播放模式、进行对话、停止，然后再次启动，以验证角色是否记得之前的交流。

示例 2：用于已认证用户的自定义身份提供器

场景： 一个企业入职模拟场景，员工使用公司凭据登录。记忆必须跟随账户而不是设备，因此当员工切换机器时，体验也能继续。

using System;
using System.Collections.Generic;
using Convai.Domain.Identity;
using Convai.Runtime.Components;
using UnityEngine;

// --- 身份提供器 ---
// 返回服务器分配的账户 ID，它在不同设备和重新登录之间保持稳定。

public class EmployeeIdentityProvider : IEndUserIdentityProvider
{
    private readonly string _accountId;

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

    public string GetEndUserId() => _accountId;
}

// --- 元数据提供器 ---
// 将姓名和部门附加到最终用户记录。
// “name” 键会显示在编辑器的长期记忆选项卡中。

public class EmployeeMetadataProvider : IEndUserMetadataProvider
{
    private readonly string _name;
    private readonly string _department;

    public EmployeeMetadataProvider(string name, string department)
    {
        _name = name;
        _department = department;
    }

    public IReadOnlyDictionary<string, object> GetEndUserMetadata()
    {
        return new Dictionary<string, object>
        {
            { "name", _name },
            { "department", _department }
        };
    }
}

// --- 场景设置 ---

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

    // 在你的身份验证层解析出已登录员工后调用。
    // 必须在 ConvaiManager 打开会话之前调用。
    public void OnEmployeeSignedIn(string accountId, string fullName, string department)
    {
        _convaiManager.SetEndUserIdentityProvider(
            new EmployeeIdentityProvider(accountId));

        _convaiManager.SetEndUserMetadataProvider(
            new EmployeeMetadataProvider(fullName, department));
    }
}

要点：

SetEndUserIdentityProvider 和 SetEndUserMetadataProvider 必须在之前首次会话连接前调用。若在会话已打开后再调用，它们在会话重启前不会生效。
请使用你的身份验证系统分配的服务器账户 ID 作为 accountId。避免使用电子邮件地址或显示名称——它们可能会变化。
若要读取 end_user_id 你的提供器返回的内容（供 MemoryService使用），请直接调用 provider.GetEndUserId() ，并使用同一个提供器实例。

示例 3：在首次会话前预置记忆

场景： 一个危险材料评估场景，讲师角色必须在第一次对话开始前知道受训者之前的认证历史。

你不是等待 AI 在多次会话中自然提取这些信息，而是在受训者进入体验之前以程序方式注入它。

此示例直接调用 ConvaiRestClient 并使用你的 API 密钥。 切勿将此代码随面向玩家的版本一起发布。 API 密钥会被嵌入到应用程序中并可能被提取。请在服务器端脚本、编辑器工具或仅供管理员使用的构建版本中运行记忆预置。

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

public class TraineeMemorySeeder : MonoBehaviour
{
    [SerializeField] private string _characterId;

    private ConvaiRestClient _client;

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

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

    // 在身份验证解析出受训者的账户 ID 后调用，
    // 在受训者进入模拟场景之前调用。
    public async void SeedTraineeHistory(
        string endUserId,
        TraineeCertificationRecord record,
        CancellationToken cancellationToken = default)
    {
        try
        {
            var facts = new List<string>
            {
                $"受训者已完成模块 1（消防安全），得分为 {record.Module1Score}%.",
                $"受训者在灭火器分类（模块 1，问题 4）上回答错误。",
                $"受训者已完成 {record.CompletedModules} / {record.TotalModules} 个必需模块。"
            };

            AddMemoriesResponse response = await _client.Memory.AddAsync(
                _characterId,
                endUserId,
                facts,
                metadata: null,
                cancellationToken);

            Debug.Log($"已为受训者 {endUserId} 预置了 {response.Memories.Count} 条记忆记录。");
        }
        catch (Exception e)
        {
            Debug.LogError($"[LTM] 预置记忆失败：{e.Message}");
        }
    }
}

[System.Serializable]
public class TraineeCertificationRecord
{
    public int Module1Score;
    public int CompletedModules;
    public int TotalModules;
}

要点：

该 endUserId 必须 完全相同 于你的会话身份提供器为同一受训者返回的值。如果你使用的是自定义提供器（见示例 2），请使用相同的账户 ID。
服务器会对重叠的事实进行去重。如果角色在之前的会话中已经有关于模块 1 的记忆，则返回的 事件 将是 "UPDATE" 而不是 "ADD".
要从默认提供器获取当前 end_user_id ： new DeviceEndUserIdProvider().GetEndUserId() （在主线程上调用）。

示例 4：重置用户以进行全新的模拟运行

场景： 一个重新认证工作流，要求受训者像第一次一样重新完成整个安全模块。必须清除所有先前记忆，以便讲师不会引用之前的尝试。

using System;
using System.Threading;
using Convai.RestAPI;
using Convai.RestAPI.Internal;
using UnityEngine;

public class SimulationResetManager : MonoBehaviour
{
    [SerializeField] private string _characterId;

    private ConvaiRestClient _client;

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

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

    // 仅清除此角色上该受训者的所有记忆。
    // 保留最终用户记录（身份和元数据）。
    public async void ResetTraineeMemory(
        string endUserId,
        CancellationToken cancellationToken = default)
    {
        try
        {
            MemoryDeleteAllResponse response = await _client.Memory.DeleteAllAsync(
                _characterId,
                endUserId,
                cancellationToken);

            Debug.Log($"记忆重置完成 — 用户：{response.EndUserId}，角色：{response.CharacterId}。");
        }
        catch (Exception e)
        {
            Debug.LogError($"[LTM] 重置记忆失败：{e.Message}");
        }
    }

    // 删除最终用户记录以及所有角色下的全部记忆。
    // 仅在彻底停用该受训者账户时使用。
    public async void DeleteTraineeRecord(
        string endUserId,
        CancellationToken cancellationToken = default)
    {
        try
        {
            EndUserDeleteResponse response = await _client.EndUsers.DeleteAsync(
                endUserId,
                cancellationToken);

            Debug.Log($"受训者记录已删除：{response.Deleted}");
        }
        catch (Exception e)
        {
            Debug.LogError($"[LTM] 删除受训者失败：{e.Message}");
        }
    }
}

选择正确的重置方法：

目标

方法

仅清除此角色的记忆；保留用户记录

MemoryService.DeleteAllAsync(characterId, endUserId)

移除用户记录以及所有角色下的全部记忆

EndUsersService.DeleteAsync(endUserId)

这两种删除方法都是 不可逆的。API 不提供确认或撤销。请在应用 UI 中先实现确认步骤，再调用任一方法。

结论

这四种模式覆盖了长期记忆用例的完整范围：无需代码的自动持久化、面向已认证用户的账户级身份、首次接触前的程序化记忆预置，以及用于重新运行体验的定向重置。如果某些内容未按预期工作，请参见故障排查与诊断以获取逐步诊断指南。

最后更新于 1个月前

这有帮助吗？