内存 API

🌐 Memory API

Memory API 提供了在 Mastra 中管理对话线程和消息历史的方法。

🌐 The Memory API provides methods to manage conversation threads and message history in Mastra.

获取所有线程

🌐 Get All Threads

检索特定资源的所有内存线程：

🌐 Retrieve all memory threads for a specific resource:

const threads = await mastraClient.getMemoryThreads({
  resourceId: "resource-1",
  agentId: "agent-1", // Optional - can be omitted if storage is configured
});

当省略 agentId 并且在服务器上配置了存储时，将直接使用存储来检索线程。这在多个代理共享相同线程时非常有用（例如，在具有多个代理步骤的工作流中）。

🌐 When agentId is omitted and storage is configured on the server, threads will be retrieved using storage directly. This is useful when multiple agents share the same threads (e.g., in workflows with multiple agent steps).

创建新主题

🌐 Create a New Thread

创建新的内存线程：

🌐 Create a new memory thread:

const thread = await mastraClient.createMemoryThread({
  title: "New Conversation",
  metadata: { category: "support" },
  resourceId: "resource-1",
  agentId: "agent-1",
});

处理特定线程

🌐 Working with a Specific Thread

获取特定内存线程的实例：

🌐 Get an instance of a specific memory thread:

const thread = mastraClient.getMemoryThread({ threadId: "thread-id", agentId: "agent-id" });

线程方法

🌐 Thread Methods

获取线程详情

🌐 Get Thread Details

检索有关特定线程的详细信息：

🌐 Retrieve details about a specific thread:

const details = await thread.get();

更新主题

🌐 Update Thread

更新线程属性：

🌐 Update thread properties:

const updated = await thread.update({
  title: "Updated Title",
  metadata: { status: "resolved" },
  resourceId: "resource-1",
});

删除主题

🌐 Delete Thread

删除一个主题及其消息：

🌐 Delete a thread and its messages:

await thread.delete();

克隆线程

🌐 Clone Thread

创建一个包含所有消息的线程副本：

🌐 Create a copy of a thread with all its messages:

const { thread: clonedThread, clonedMessages } = await thread.clone();

克隆选项：

🌐 Clone with options:

const { thread: clonedThread, clonedMessages } = await thread.clone({
  newThreadId: "custom-clone-id",
  title: "Cloned Conversation",
  metadata: { branch: "experiment-1" },
  options: {
    messageLimit: 10, // Only clone last 10 messages
  },
});

带消息过滤的克隆：

🌐 Clone with message filtering:

const { thread: clonedThread } = await thread.clone({
  options: {
    messageFilter: {
      startDate: new Date("2024-01-01"),
      endDate: new Date("2024-01-31"),
    },
  },
});

克隆响应包括：

🌐 The clone response includes:

• thread：带有克隆元数据的新创建克隆线程
• clonedMessages：带有新 ID 的克隆消息数组

消息操作

🌐 Message Operations

保存消息

🌐 Save Messages

将消息保存到内存：

🌐 Save messages to memory:

const result = await mastraClient.saveMessageToMemory({
  messages: [
    {
      role: "user",
      content: "Hello!",
      id: "1",
      threadId: "thread-1",
      resourceId: "resource-1",
      createdAt: new Date(),
      format: 2,
    },
  ],
  agentId: "agent-1",
});

// result.messages contains the saved messages
console.log(result.messages);

获取线程消息

🌐 Retrieve Thread Messages

获取与内存线程相关的消息：

🌐 Get messages associated with a memory thread:

// Get all messages in the thread (paginated)
const result = await thread.listMessages();
console.log(result.messages); // Array of messages
console.log(result.total); // Total count
console.log(result.hasMore); // Whether more pages exist

// Get messages with pagination
const result = await thread.listMessages({
  page: 0,
  perPage: 20
});

// Get messages with ordering
const result = await thread.listMessages({
  orderBy: { field: 'createdAt', direction: 'ASC' }
});

删除消息

🌐 Delete Messages

从对话中删除一条或多条消息：

🌐 Delete one or more messages from a thread:

// Delete a single message
const result = await thread.deleteMessages("message-id");

// Delete multiple messages
const result = await thread.deleteMessages([
  "message-1",
  "message-2",
  "message-3",
]);

// Returns: { success: true, message: "Message deleted successfully" }

工作内存

🌐 Working Memory

工作内存使代理能够在多次交互中保持关于用户的持续信息。它可以作用于特定的线程，也可以作用于某个资源（用户）的所有线程。

🌐 Working memory allows agents to maintain persistent information about users across interactions. It can be scoped to either a specific thread or across all threads for a resource (user).

获取工作内存

🌐 Get Working Memory

获取线程的当前工作内存：

🌐 Retrieve the current working memory for a thread:

const workingMemory = await mastraClient.getWorkingMemory({
  agentId: "agent-1",
  threadId: "thread-1",
  resourceId: "user-123", // Optional, required for resource-scoped memory
});

响应包括：

🌐 The response includes:

• workingMemory：当前工作内存内容（字符串或空）
• source：无论内存来自 "thread" 还是 "resource" 范围
• workingMemoryTemplate：用于工作内存的模板（如果已配置）
• threadExists：线程是否存在

更新工作内存

🌐 Update Working Memory

更新线程的工作内存内容：

🌐 Update the working memory content for a thread:

await mastraClient.updateWorkingMemory({
  agentId: "agent-1",
  threadId: "thread-1",
  workingMemory: `# User Profile
- Name: John Doe
- Location: New York
- Preferences: Prefers formal communication
`,
  resourceId: "user-123", // Optional, required for resource-scoped memory
});

// Returns: { success: true }

注意： 对于资源范围的工作内存，你必须提供 resourceId 参数。这允许内存在该用户的所有对话线程中持续存在。

获取内存状态

🌐 Get Memory Status

检查内存系统的状态：

🌐 Check the status of the memory system:

const status = await mastraClient.getMemoryStatus("agent-id");