代理内存

🌐 Agent memory

代理使用内存在互动中保持上下文。大型语言模型（LLM）是无状态的，调用之间不会保留信息，因此代理需要内存来跟踪消息历史并回忆相关信息。

🌐 Agents use memory to maintain context across interactions. LLMs are stateless and don't retain information between calls, so agents need memory to track message history and recall relevant information.

Mastra 代理可以配置为存储消息历史记录，并可选择使用工作内存来保持最近的上下文，或者使用语义回忆来根据意义检索过去的消息。

🌐 Mastra agents can be configured to store message history, with optional working memory to maintain recent context or semantic recall to retrieve past messages based on meaning.

何时使用内存

🌐 When to use memory

当你的代理需要保持多轮对话、参考之前的交流、回忆用户偏好或会话早期的事实，或在对话线程中随着时间建立上下文时，请使用内存。对于每次交互都是独立的单轮请求，请跳过使用内存。

🌐 Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges, recall user preferences or facts from earlier in a session, or build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.

设置内存

🌐 Setting up memory

要在 Mastra 中启用内存，请安装 @mastra/memory 软件包以及一个存储提供程序。

🌐 To enable memory in Mastra, install the @mastra/memory package along with a storage provider.

npm

npm install @mastra/memory@latest @mastra/libsql@latest

pnpm

pnpm add @mastra/memory@latest @mastra/libsql@latest

Yarn

yarn add @mastra/memory@latest @mastra/libsql@latest

Bun

bun add @mastra/memory@latest @mastra/libsql@latest

存储提供商

🌐 Storage providers

内存功能需要存储提供商来持久化消息历史，包括用户消息和代理响应。有关可用提供商以及 Mastra 中存储工作原理的更多详细信息，请参阅存储文档。

🌐 Memory requires a storage provider to persist message history, including user messages and agent responses. For more details on available providers and how storage works in Mastra, see the Storage documentation.

配置内存

🌐 Configuring memory

1. 通过创建一个 Memory 实例并将其传递给代理的 memory 选项来启用内存。

   🌐 Enable memory by creating a Memory instance and passing it to the agent’s memory option.

   src/mastra/agents/memory-agent.ts

   import { Agent } from "@mastra/core/agent";
   import { Memory } from "@mastra/memory";
   
   export const memoryAgent = new Agent({
     id: 'memory-agent',
     name: 'Memory Agent',
     memory: new Memory({
       options: {
         lastMessages: 20,
       },
     }),
   });

   info

   访问 Memory Class 获取完整的配置选项列表。

   🌐 Visit Memory Class for a full list of configuration options.

2. 向你的主 Mastra 实例添加存储提供程序，以便在所有已配置的代理之间启用内存功能。

   🌐 Add a storage provider to your main Mastra instance to enable memory across all configured agents.

   src/mastra/index.ts

   import { Mastra } from "@mastra/core";
   import { LibSQLStore } from "@mastra/libsql";
   
   export const mastra = new Mastra({
     storage: new LibSQLStore({
       id: 'mastra-storage',
       url: ":memory:",
     }),
   });

   info

   访问 libSQL Storage 查看完整的配置选项列表。

   🌐 Visit libSQL Storage for a full list of configuration options.

或者，直接向代理的内存添加存储，以保持数据分开，或者为每个代理使用不同的提供商。

🌐 Alternatively, add storage directly to an agent’s memory to keep data separate or use different providers per agent.

src/mastra/agents/memory-agent.ts

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/libsql";

export const memoryAgent = new Agent({
  id: 'memory-agent',
  name: 'Memory Agent',
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'mastra-storage',
      url: ":memory:",
    }),
  }),
});

Mastra Cloud Store limitation

Agent-level storage is not supported when using Mastra Cloud Store. If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.

消息记录

🌐 Message history

在代理调用期间包含一个 memory 对象，同时包含 resource 和 thread，以跟踪消息历史记录。

🌐 Include a memory object with both resource and thread to track message history during agent calls.

• resource：用户或实体的稳定标识符。
• thread：用于隔离特定对话或会话的 ID。

这些字段告诉代理在哪里存储和检索上下文，从而在整个对话中实现持久的、支持线程感知的内存。

🌐 These fields tell the agent where to store and retrieve context, enabling persistent, thread-aware memory across a conversation.

const response = await memoryAgent.generate(
  "Remember my favorite color is blue.",
  {
    memory: {
      resource: "user-123",
      thread: "conversation-123",
    },
  },
);

要回忆存储在内存中的信息，请使用原始对话中使用的相同 resource 和 thread 值调用代理。

🌐 To recall information stored in memory, call the agent with the same resource and thread values used in the original conversation.

const response = await memoryAgent.generate("What's my favorite color?", {
  memory: {
    resource: "user-123",
    thread: "conversation-123",
  },
});

warning

每个线程都有一个所有者（resourceId），创建后无法更改。避免将相同的线程 ID 用于不同所有者的线程，因为在查询时这会导致错误。

要了解有关内存的更多信息，请参阅 Memory 文档。

🌐 To learn more about memory see the Memory documentation.

使用 RequestContext

🌐 Using RequestContext

使用 RequestContext 访问特定于请求的值。这可以让你根据请求的上下文有条件地选择不同的内存或存储配置。

🌐 Use RequestContext to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.

src/mastra/agents/memory-agent.ts

export type UserTier = {
  "user-tier": "enterprise" | "pro";
};

const premiumMemory = new Memory();

const standardMemory = new Memory();

export const memoryAgent = new Agent({
  id: 'memory-agent',
  name: 'Memory Agent',
  memory: ({ requestContext }) => {
    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];

    return userTier === "enterprise" ? premiumMemory : standardMemory;
  },
});

info

请访问 Request Context 以获取更多信息。

🌐 Visit Request Context for more information.

相关

🌐 Related

• 工作内存
• 语义回忆
• 存储
• 请求上下文