For the complete documentation index, see llms.txt. This page is also available as Markdown.

记忆管理 API

为单个玩家列出、添加、检索和删除角色的记忆记录,包含设置、每个方法、响应类型和错误处理。

Memory Management API 允许你直接读取和写入记忆记录——无需等待对话生成它们。可用它来审计某个角色了解了用户什么、在首次会话前预置事实,或移除不再准确的特定记忆。

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


初始化客户端

初始化 ConvaiRestClient ,使用你的 API 密钥。该客户端 IDisposable ——始终使用 使用 语句或调用 Dispose() 完成后。

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

每个记忆操作都需要两个标识符:

  • characterId ——来自 ConvaiCharacter Inspector

  • endUserId ——由你的 IEndUserIdentityProvider (或者来自 PlayerPrefs ,如果使用默认的 DeviceEndUserIdProvider)


MemoryRecord 数据模型

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

属性
类型
说明

Id

string

此记忆记录的唯一标识符

记忆

string

以自然语言句子形式存储的事实

CreatedAt

string

事实首次存储时的 ISO 8601 时间戳

UpdatedAt

string

最后一次更新的 ISO 8601 时间戳

Metadata

Dictionary<string, object>

附加到此记录的可选键值数据

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

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


记忆 CRUD 操作

列出记忆

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

MemoryListResponse 字段:

属性
类型
说明

Memories

List<MemoryRecord>

此页上的记录

TotalCount

int

存储记录总数

页码

int

当前页码

PageSize

int

每页记录数

HasMore

bool

是否存在更多页面


获取单条记忆

通过其 ID 检索一条特定记录。


添加记忆

以自然语言字符串的形式注入一条或多条事实。Convai 会对重叠事实去重——添加一条在语义上等同于现有事实的新事实时,会更新现有记录,而不是创建重复项。

AddMemoriesResponse 和 MemoryAddResult 字段:

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

属性
类型
说明

Id

string

已创建或更新记录的 ID

事件

string

“add” 用于新记录, “update” 用于去重后的更新

记忆

string

Convai 存储的规范化事实文本


删除单条记忆

通过其 ID 移除一条特定记录。


删除所有记忆


处理 API 错误

将所有异步记忆调用包装在 try/catch中。失败的操作会抛出 ConvaiRestException 并附带一个 HTTP 状态码。

参见 排查长期记忆问题 以查看完整的 HTTP 状态码参考。


下一步

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

最后更新于

这有帮助吗?