排查长期记忆问题

诊断长期记忆为何未能持久化，验证终端用户身份在会话间是否稳定，并解决 Memory Management API 的 HTTP 错误。

大多数 LTM 问题可归为三类：记忆在会话之间没有持久化、错误的用户收到了记忆，以及 API 调用因 HTTP 错误而失败。请先按照下面的诊断流程排查，再查看参考表。

---

第一线排查

在检查其他任何内容之前，请按顺序完成以下三个步骤：

1. 确认角色已启用记忆

在以下位置登录 convai.com，打开角色，并验证 Memory 选项卡显示 长期记忆：开启。记忆默认是禁用的——这是 LTM 看起来不起作用的最常见原因。

2. 验证终端用户 ID 在各会话之间保持稳定

将下面的诊断脚本添加到你的场景中。运行 Play Mode，停止，然后再次运行。两次记录的 ID 必须完全相同。

using Convai.Runtime.Identity;
using UnityEngine;

public class EndUserIdDebug : MonoBehaviour
{
    private void Start()
    {
        var provider = new DeviceEndUserIdProvider();
        string id = provider.GetEndUserId();
        Debug.Log($"[LTM] 本次会话的 end_user_id: {id}");
    }
}

如果两次会话之间 ID 发生变化，记忆就无法累积——服务器会把每个新 ID 当作新用户。

3. 确认会话已成功连接

检查 Console 中的 Convai 启动消息。连接失败（无效 API 密钥、网络错误）会阻止所有 LTM 操作，无论已存储的数据如何。

---

决策流程

当记忆没有持久化时，请使用此流程：

---

常见问题

症状	可能原因	修复
角色从不引用之前的会话	角色未启用 LTM	在角色的 Memory 选项卡中启用它，位于 convai.com
在编辑器中有效，但在构建中无效	DeviceEndUserIdProvider 在编辑器和构建中返回不同的值	预期行为——编辑器使用 PlayerPrefs GUID；构建使用设备 ID。确保构建中的设备 ID 稳定。要实现跨上下文一致性，请实现自定义 IEndUserIdentityProvider.
重装后记忆丢失	PlayerPrefs 在重新安装时被清除	请通过自定义提供程序使用服务器分配的账户 ID。基于设备和基于 GUID 的 ID 不会在重新安装后保留。
同一设备上的不同用户共享记忆	多个用户共用一台设备	每个用户都必须获得唯一的 end_user_id。如果 DeviceEndUserIdProvider 正在使用时，设备范围的 GUID 会被共享。请实现一个自定义提供程序，返回每个用户的账户 ID。
自定义提供程序未生效	提供程序在之后注册 ConnectAsync	请在 Awake()中注册，早于 ConvaiRoomManager.Start() 完成。如果 ConvaiCharacter 具有 自动连接 已启用， Start() 可能已经太晚了。
记忆事实看起来不正确或已过时	测试记录残留	使用 client.Memory.DeleteAllAsync 在开始新的评估之前清除测试数据。
GetEndUserId() 返回空字符串	自定义提供程序返回 null 或空白	SDK 在发送前会将 null/空白规范化为 null ，从而导致匿名会话。请确保你的提供程序始终返回非空值。

---

运行时诊断

列出某用户的所有记忆

使用此脚本确认服务器已存储的内容。通过在 Inspector 中右键 → 列出记忆.

using Convai.RestAPI;
using Convai.RestAPI.Internal;
using Convai.Runtime.Identity;
using UnityEngine;

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

    [ContextMenu("列出记忆")]
    private async void ListMemories()
    {
        var provider = new DeviceEndUserIdProvider();
        string endUserId = provider.GetEndUserId();

        Debug.Log($"[LTM] 正在查询 end_user_id 的记忆：{endUserId}");

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

        int page = 1;
        bool hasMore = true;

        while (hasMore)
        {
            var response = await client.Memory.ListAsync(_characterId, endUserId, page);

            Debug.Log($"[LTM] 第 {page} 页 — {response.Memories.Count} 条记录（总计：{response.TotalCount}）");

            foreach (MemoryRecord record in response.Memories)
                Debug.Log($"  [{record.Id}] {record.Memory}");

            hasMore = response.HasMore;
            page++;
        }

        if (page == 1)
            Debug.Log("[LTM] 未找到此用户-角色组合的记忆记录。");
    }
}

检查记忆启用状态

以编程方式确认角色当前是否已启用 LTM。

[ContextMenu("检查记忆是否启用")]
private async void CheckMemoryEnabled()
{
    using var client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);

    bool isEnabled = await client.Characters.GetMemoryEnabledAsync(_characterId);
    Debug.Log($"[LTM] 角色 '{_characterId}' 已启用记忆：{isEnabled}");
}

---

API 错误代码

所有 Memory Management API 错误都会抛出 ConvaiRestException。该 StatusCode 属性对应下面的原因。

HTTP 状态码	原因	修复
400 错误请求	缺少必需参数（character_id, end_user_id，或 memories)	在调用之前，请确认所有必需参数都非空且非空字符串
401 未授权	API 密钥无效或缺失	重新配置你的 API 密钥——请参阅 配置 API 密钥
403 禁止访问	该角色不属于拥有该 API 密钥的账户	验证角色 ID 是否属于与你的 API 密钥关联的账户
404 未找到	无效的角色 ID、终端用户 ID 或记忆 ID	请对照 Convai 仪表板仔细核对这些 ID。如果按 memoryId查询，请从之前的 ListAsync 调用。
429 请求过多	超过速率限制	请实现指数退避。例如：在 2^attempt 秒后重试，配合 CancellationToken 在达到最大重试次数后中止。
500 内部服务器错误	瞬时服务器错误	请在短暂延迟后重试请求。如果错误持续存在，请查看 Convai 状态页面，并携带你的角色 ID 和时间戳联系支持。

指数退避模式

using System;
using System.Threading;
using System.Threading.Tasks;
using Convai.RestAPI;

public static class MemoryRetryHelper
{
    public static async Task<T> WithRetry<T>(
        Func<Task<T>> operation,
        int maxAttempts = 3,
        CancellationToken cancellationToken = default)
    {
        for (int attempt = 0; attempt < maxAttempts; attempt++)
        {
            try
            {
                return await operation();
            }
            catch (ConvaiRestException ex) when (ex.StatusCode == 429 || ex.StatusCode == 500)
            {
                if (attempt == maxAttempts - 1) throw;

                int delayMs = (int)Math.Pow(2, attempt) * 1000;
                await Task.Delay(delayMs, cancellationToken);
            }
        }

        throw new InvalidOperationException("无法到达。");
    }
}

---

下一步

长期记忆脚本参考为角色配置记忆