存储处理器

🌐 Memory Processors

内存处理器在消息通过启用内存的代理时对其进行转换和筛选。它们管理上下文窗口的限制，删除不必要的内容，并优化发送给语言模型的信息。

🌐 Memory processors transform and filter messages as they pass through an agent with memory enabled. They manage context window limits, remove unnecessary content, and optimize the information sent to the language model.

当在代理上启用内存时，Mastra 会在代理的处理器管道中添加内存处理器。这些处理器会检索消息历史、工作内存以及语义相关的消息，然后在模型响应后保存新消息。

🌐 When memory is enabled on an agent, Mastra adds memory processors to the agent's processor pipeline. These processors retrieve message history, working memory, and semantically relevant messages, then persist new messages after the model responds.

内存处理器是专门处理与内存相关的消息和状态的处理器。

🌐 Memory processors are processors that operate specifically on memory-related messages and state.

内置内存处理器

🌐 Built-in Memory Processors

当启用内存时，Mastra 会自动添加这些处理器：

🌐 Mastra automatically adds these processors when memory is enabled:

MessageHistory

检索消息历史并保存新消息。

🌐 Retrieves message history and persists new messages.

当你配置时：

memory: new Memory({
  lastMessages: 10,
});

Mastra 内部:

1. 创建一个带有 limit: 10 的 MessageHistory 处理器
2. 将其添加到代理的输入处理器中（在 LLM 之前运行）
3. 将其添加到代理的输出处理器中（在大型语言模型之后运行）

它的作用:

• 输入：从存储中获取最后 10 条消息，并将它们添加到对话前面
• 输出：在模型响应后将新消息保存到存储中

示例:

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

const agent = new Agent({
  id: "test-agent",
  name: "Test Agent",
  instructions: "You are a helpful assistant",
  model: 'openai/gpt-4o',
  memory: new Memory({
    storage: new LibSQLStore({
      id: "memory-store",
      url: "file:memory.db",
    }),
    lastMessages: 10, // MessageHistory processor automatically added
  }),
});

SemanticRecall

根据当前输入检索语义相关的消息，并为新消息创建嵌入。

🌐 Retrieves semantically relevant messages based on the current input and creates embeddings for new messages.

当你配置时：

memory: new Memory({
  semanticRecall: { enabled: true },
  vector: myVectorStore,
  embedder: myEmbedder,
});

Mastra 内部:

1. 创建一个 SemanticRecall 处理器
2. 将其添加到代理的输入处理器中（在 LLM 之前运行）
3. 将其添加到代理的输出处理器中（在大型语言模型之后运行）
4. 需要同时配置向量存储和嵌入器

它的作用:

• 输入：执行向量相似度搜索以查找相关的过去消息，并将其添加到对话开头
• 输出：为新消息创建嵌入，并将其存储在向量库中以便将来检索

示例:

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/libsql";
import { PineconeVector } from "@mastra/pinecone";
import { OpenAIEmbedder } from "@mastra/openai";
import { openai } from "@ai-sdk/openai";

const agent = new Agent({
  name: "semantic-agent",
  instructions: "You are a helpful assistant with semantic memory",
  model: 'openai/gpt-4o',
  memory: new Memory({
    storage: new LibSQLStore({
      id: "memory-store",
      url: "file:memory.db",
    }),
    vector: new PineconeVector({
      id: "memory-vector",
      apiKey: process.env.PINECONE_API_KEY!,
    }),
    embedder: new OpenAIEmbedder({
      model: "text-embedding-3-small",
      apiKey: process.env.OPENAI_API_KEY!,
    }),
    semanticRecall: { enabled: true }, // SemanticRecall processor automatically added
  }),
});

WorkingMemory

管理跨对话的工作内存状态。

🌐 Manages working memory state across conversations.

当你配置时：

memory: new Memory({
  workingMemory: { enabled: true },
});

Mastra 内部:

1. 创建一个 WorkingMemory 处理器
2. 将其添加到代理的输入处理器中（在 LLM 之前运行）
3. 需要配置存储适配器

它的作用:

• 输入：检索当前线程的工作内存状态并将其添加到对话开头
• 输出：无需输出处理

示例:

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

const agent = new Agent({
  name: "working-memory-agent",
  instructions: "You are an assistant with working memory",
  model: 'openai/gpt-4o',
  memory: new Memory({
    storage: new LibSQLStore({
      id: "memory-store",
      url: "file:memory.db",
    }),
    workingMemory: { enabled: true }, // WorkingMemory processor automatically added
  }),
});

手动控制与去重

🌐 Manual Control and Deduplication

如果你手动向 inputProcessors 或 outputProcessors 添加内存处理器，Mastra 不会 自动添加它。这让你可以完全控制处理器的顺序：

🌐 If you manually add a memory processor to inputProcessors or outputProcessors, Mastra will not automatically add it. This gives you full control over processor ordering:

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { MessageHistory } from "@mastra/core/processors";
import { TokenLimiter } from "@mastra/core/processors";
import { LibSQLStore } from "@mastra/libsql";
import { openai } from "@ai-sdk/openai";

// Custom MessageHistory with different configuration
const customMessageHistory = new MessageHistory({
  storage: new LibSQLStore({ id: "memory-store", url: "file:memory.db" }),
  lastMessages: 20,
});

const agent = new Agent({
  name: "custom-memory-agent",
  instructions: "You are a helpful assistant",
  model: 'openai/gpt-4o',
  memory: new Memory({
    storage: new LibSQLStore({ id: "memory-store", url: "file:memory.db" }),
    lastMessages: 10, // This would normally add MessageHistory(10)
  }),
  inputProcessors: [
    customMessageHistory, // Your custom one is used instead
    new TokenLimiter({ limit: 4000 }), // Runs after your custom MessageHistory
  ],
});

处理器执行顺序

🌐 Processor Execution Order

在将保护措施与内存结合使用时，理解执行顺序非常重要：

🌐 Understanding the execution order is important when combining guardrails with memory:

输入处理器

🌐 Input Processors

[Memory Processors] → [Your inputProcessors]

1. 内存处理器先运行：WorkingMemory、MessageHistory、SemanticRecall
2. 你的输入处理器在以下之后运行：保护措施、过滤器、验证器

这意味着在你的处理器能够验证或过滤输入之前，内存会加载消息历史记录。

🌐 This means memory loads message history before your processors can validate or filter the input.

输出处理器

🌐 Output Processors

[Your outputProcessors] → [Memory Processors]

1. 你的输出处理器首先运行：防护措施、过滤器、验证器
2. 内存处理器在以下操作之后运行：SemanticRecall（嵌入），MessageHistory（持久化）

此排序设计为默认安全：如果你的输出保护调用了abort()，内存处理器将不会运行，并且不会保存任何消息。

🌐 This ordering is designed to be safe by default: if your output guardrail calls abort(), the memory processors never run and no messages are saved.

护栏与内存

🌐 Guardrails and Memory

默认执行顺序提供了安全防护行为：

🌐 The default execution order provides safe guardrail behavior:

输出护栏（推荐）

🌐 Output guardrails (recommended)

输出护栏会在内存处理器保存消息之前运行。如果护栏中止:

🌐 Output guardrails run before memory processors save messages. If a guardrail aborts:

• 绊线被触发了
• 内存处理器已跳过
• 没有消息被存储

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";

// Output guardrail that blocks inappropriate content
const contentBlocker = {
  id: "content-blocker",
  processOutputResult: async ({ messages, abort }) => {
    const hasInappropriateContent = messages.some((msg) =>
      containsBadContent(msg)
    );
    if (hasInappropriateContent) {
      abort("Content blocked by guardrail");
    }
    return messages;
  },
};

const agent = new Agent({
  name: "safe-agent",
  instructions: "You are a helpful assistant",
  model: 'openai/gpt-4o',
  memory: new Memory({ lastMessages: 10 }),
  // Your guardrail runs BEFORE memory saves
  outputProcessors: [contentBlocker],
});

// If the guardrail aborts, nothing is saved to memory
const result = await agent.generate("Hello");
if (result.tripwire) {
  console.log("Blocked:", result.tripwire.reason);
  // Memory is empty - no messages were persisted
}

输入防护措施

🌐 Input guardrails

输入护栏在内存处理器加载历史记录之后运行。如果护栏中止：

🌐 Input guardrails run after memory processors load history. If a guardrail aborts:

• 绊线被触发了
• LLM 从未被调用
• 跳过输出处理器（包括内存持久化）
• 没有消息被存储

// Input guardrail that validates user input
const inputValidator = {
  id: "input-validator",
  processInput: async ({ messages, abort }) => {
    const lastUserMessage = messages.findLast((m) => m.role === "user");
    if (isInvalidInput(lastUserMessage)) {
      abort("Invalid input detected");
    }
    return messages;
  },
};

const agent = new Agent({
  name: "validated-agent",
  instructions: "You are a helpful assistant",
  model: 'openai/gpt-4o',
  memory: new Memory({ lastMessages: 10 }),
  // Your guardrail runs AFTER memory loads history
  inputProcessors: [inputValidator],
});

摘要

🌐 Summary

护栏类型	运行时间	中止时情况
输入	内存加载历史后	未调用大语言模型，未保存任何内容
输出	内存保存前	未保存到存储

这两种情况都是安全的——保护措施可以防止不适当的内容被保存在内存中

🌐 Both scenarios are safe - guardrails prevent inappropriate content from being persisted to memory

相关文档

🌐 Related documentation

• 处理器 - 一般处理器概念及自定义处理器创建
• 护栏 - 安全与验证处理器
• 内存概览 - 内存类型和配置

在创建自定义处理器时，避免直接修改输入的 messages 数组或其对象。

🌐 When creating custom processors avoid mutating the input messages array or its objects directly.