长期记忆

Convai 可以跨会话记住有关用户的信息。当你提供 `endUserId` 时，角色会自动构建并回忆长期记忆。

启用记忆

这是一个基于角色的功能。前往你的 Convai 仪表板 -> Character -> Memory 标签页 -> Memory Settings -> 启用长期记忆

传入 endUserId 连接时：

const client = useConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  endUserId: 'a1b2c3d4-...',  // 任意字符串——优先使用（UUID 或电子邮件），例如 '[e-mail]'
});

client.memoryManager 在成功连接后可用。

访问管理器

const memory = client.memoryManager;

if (!memory) {
  // 未提供 endUserId，或者客户端尚未连接
  return;
}

---

列出记忆

const result = await memory.listMemories({ page: 1, pageSize: 50 });

console.log(`总数：${result.total_count}`);
console.log(`是否还有更多：${result.has_more}`);

result.memories.forEach(m => {
  console.log(`[${m.id}] ${m.memory}`);
  // m.created_at、m.updated_at（ISO 时间戳）
});

// 如有需要，可进行分页
if (result.has_more) {
  const page2 = await memory.listMemories({ page: 2, pageSize: 50 });
}

参数

字段	类型	默认值	范围
页码	数字	1	1–1000
每页数量	数字	50	1–100

---

添加记忆

传入一个或多个字符串作为记忆添加：

const result = await memory.addMemories([
  '用户偏好深色模式界面。',
  '用户正在学习西班牙语。',
  '用户把弹吉他作为爱好。',
]);

result.memories.forEach(m => {
  console.log(`已添加：${m.id} → ${m.memory}`);
});

角色将在未来的对话中自动使用这些内容。

---

获取单条记忆

const m = await memory.getMemory('f4cbdb08-7062-4f3e-8eb2-9f5c80dfe64c');

console.log(m.memory);      // “用户偏好深色模式界面。”
console.log(m.created_at);  // ISO 时间戳
console.log(m.updated_at);  // ISO 时间戳

---

删除一条记忆

const result = await memory.deleteMemory('f4cbdb08-7062-4f3e-8eb2-9f5c80dfe64c');

if (result.deleted) {
  console.log('已删除：', result.memory_id);
}

---

删除所有记忆

移除（角色，用户）对的所有记忆。删除在服务器端是异步的。

const result = await memory.deleteAllMemories();
console.log(result.message); // “记忆删除正在进行中...”

// 稍等片刻并验证
await new Promise(r => setTimeout(r, 2000));
const check = await memory.listMemories();
console.log('剩余：', check.total_count);

---

独立使用

MemoryManager 可以独立于客户端使用（例如在后端管理工具中）：

import { MemoryManager } from '@convai/web-sdk/core';

const manager = new MemoryManager(
  'YOUR_API_KEY',      // 或认证令牌
  'CHARACTER_ID',
  'END_USER_ID',
);

const memories = await manager.listMemories();

---

Memory 对象结构

interface Memory {
  id: string;          // UUID
  memory: string;      // 文本内容
  created_at: string;  // ISO 8601 时间戳
  updated_at: string;  // ISO 8601 时间戳
}

---

自动记忆如何工作

当 endUserId 设置后，Convai 后端会从每段对话中提取有意义的事实并将它们存储为记忆。在以后与 相同， endUserId连接时，这些记忆会被注入到角色的上下文中，让它“记住”用户。这就是为什么该值必须对每个用户保持稳定且唯一——UUID 或电子邮件地址都很适合。

为此你无需调用任何 Memory API 方法。显式的 CRUD 方法用于从你的应用中读取、初始化或清理记忆。