> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/memory-management-api.md).

# 记忆管理 API

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

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

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

***

### 初始化客户端

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

```csharp
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 更喜欢逐步讲解，而不是摘要。”`

有关包含响应模型的完整类型参考，请参见 [长期记忆脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/long-term-memory-scripting-reference.md).

***

### 记忆 CRUD 操作

#### 列出记忆

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

```csharp
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 检索一条特定记录。

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

***

#### 添加记忆

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

```csharp
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 移除一条特定记录。

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

***

#### 删除所有记忆

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

```csharp
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 状态码。

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

请参见 [长期记忆故障排除](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/troubleshooting-and-diagnostics.md) 以获取完整的 HTTP 状态码参考。

***

### 下一步

{% content-ref url="/pages/d41fbdd4f21a090aa6d7e39be7a7eb215d0435c2" %}
[长期记忆使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/49cef55d22f33c0ffdf4893701cd5a6686bd7590" %}
[管理终端用户记录](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/end-user-management.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/long-term-memory/memory-management-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.