记忆管理 API

使用 ConvaiRestClient.Memory 为用户-角色对列出、添加、检索和删除记忆记录——包括设置、全部五个方法、响应类型和错误处理。

内存管理 API 让你可以直接读写内存记录——无需等待对话生成它们。可用它来审计角色对某个用户所知的信息、在首次会话前预置事实，或移除不再准确的特定记忆。

Beta 版 API。 方法签名是稳定的，但在未来的 SDK 更新中可能会发生变化。请在生产环境中固定你的 SDK 版本，并在升级前查看更新日志。

所有内存操作都可在 ConvaiRestClient.Memory。该 ConvaiRestClient 上使用；它是一个独立于实时会话的 REST 客户端——你可以在任何时候调用它，包括在编辑器脚本中、Play Mode 之外。

---

初始化客户端

初始化 ConvaiRestClient 并传入你的 API 密钥。该客户端是 IDisposable ——务必使用 使用 语句或调用 Dispose() 在完成后释放。

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

每个内存操作都需要两个标识符：

• characterId ——来自 ConvaiCharacter Inspector
• endUserId ——由你的 IEndUserIdentityProvider 返回的标识符（或来自 PlayerPrefs 中的 GUID，如果使用默认的 DeviceEndUserIdProvider)

---

MemoryRecord 数据模型

每条已存储的事实都是一个 MemoryRecord:

属性	类型	说明
Id	string	此内存记录的唯一标识符
Memory	string	以自然语言句子形式保存的事实
CreatedAt	string	事实首次保存时的 ISO 8601 时间戳
UpdatedAt	string	最后更新时间的 ISO 8601 时间戳
Metadata	Dictionary<string, object>	附加到此记录的可选键值数据

示例 Memory 值： “用户的名字是 Alex。”, “Alex 于 2025-03-12 完成了受限空间安全模块。”, “Alex 更喜欢逐步讲解，而不是摘要。”

有关包含响应模型的完整类型参考，请参见 长期记忆脚本参考.

---

记忆 CRUD 操作

列出记忆

检索某个用户-角色对的所有已存储记忆记录。结果是分页的——使用 page 是位于 pageSize 来遍历大量数据。

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

public class MemoryInspector : MonoBehaviour
{
    [ContextMenu("List All Memories")]
    private async void ListAllMemories()
    {
        string characterId = "your-character-id";
        string endUserId = "target-end-user-id";

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

        int page = 1;
        bool hasMore = true;
        var allMemories = new List<MemoryRecord>();

        while (hasMore)
        {
            var response = await client.Memory.ListAsync(characterId, endUserId, page, pageSize: 50);
            allMemories.AddRange(response.Memories);
            hasMore = response.HasMore;
            page++;
        }

        foreach (var record in allMemories)
        {
            Debug.Log($"[{record.Id}] {record.Memory}");
        }
    }
}

MemoryListResponse 字段：

属性	类型	说明
Memories	List<MemoryRecord>	此页上的记录
TotalCount	int	已存储记录总数
Page	int	当前页码
PageSize	int	每页记录数
HasMore	bool	是否存在更多页面

---

获取单条记忆

按 ID 检索一条特定记录。

var record = await client.Memory.GetAsync(characterId, endUserId, memoryId);
Debug.Log($"Memory: {record.Memory}");

---

添加记忆

以自然语言字符串注入一条或多条事实。Convai 会对重叠事实进行去重——添加一个与现有事实语义等价的事实时，会更新现有记录，而不是创建重复项。

var facts = new List<string>
{
    "Jordan 是 Northfield 设施的夜班安全官员。",
    "Jordan 已完成受限空间进入认证。",
    "Jordan 更喜欢实用示例，而不是理论性很强的讲解。"
};

var response = await client.Memory.AddAsync(characterId, endUserId, facts);

foreach (var result in response.Memories)
{
    Debug.Log($"[{result.Event}] {result.Memory} (id: {result.Id})");
}

AddMemoriesResponse 是位于 MemoryAddResult 字段：

AddAsync 返回 AddMemoriesResponse，其中包含一个 List<MemoryAddResult>。每个结果对应一条提交的事实：

属性	类型	说明
Id	string	已创建或已更新记录的 ID
Event	string	“add” 用于新记录， “update” 用于去重后的更新
Memory	string	由 Convai 存储的标准化事实文本

---

删除单条记忆

按 ID 移除一条特定记录。

var result = await client.Memory.DeleteAsync(characterId, endUserId, memoryId);
Debug.Log($"Deleted: {result.Deleted}");

---

删除所有记忆

DeleteAllAsync 会永久移除 所有 指定用户-角色对的记忆记录。这无法撤销。在任何面向用户的流程中调用此操作前，务必先实现确认步骤。

var result = await client.Memory.DeleteAllAsync(characterId, endUserId);
Debug.Log($"All memories deleted for user {result.EndUserId} on character {result.CharacterId}.");

---

处理 API 错误

将所有异步内存调用包裹在 try/catch中。失败的操作会抛出 ConvaiRestException 并带有 HTTP 状态码。

try
{
    var response = await client.Memory.ListAsync(characterId, endUserId);
    // 处理响应
}
catch (ConvaiRestException ex)
{
    Debug.LogError($"Memory API error {ex.StatusCode}: {ex.Message}");
}

请参见 长期记忆故障排除 以获取完整的 HTTP 状态码参考。

---

下一步

长期记忆使用示例管理最终用户记录