记忆管理 API
为单个玩家列出、添加、检索和删除角色的记忆记录,包含设置、每个方法、响应类型和错误处理。
Memory Management API 允许你直接读取和写入记忆记录——无需等待对话生成它们。可用它来审计某个角色了解了用户什么、在首次会话前预置事实,或移除不再准确的特定记忆。
所有记忆操作都可在 ConvaiRestClient.Memory。 ConvaiRestClient 中使用——它是一个独立于实时会话的 REST 客户端——你可以在任何时候调用它,包括在编辑器脚本中、Play Mode 之外。
初始化客户端
初始化 ConvaiRestClient ,使用你的 API 密钥。该客户端 IDisposable ——始终使用 使用 语句或调用 Dispose() 完成后。
using var client = new ConvaiRestClient(ConvaiSettings.Instance.ApiKey);每个记忆操作都需要两个标识符:
characterId——来自ConvaiCharacterInspectorendUserId——由你的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 状态码参考。
下一步
长期记忆使用示例管理终端用户记录最后更新于
这有帮助吗?