Memory Processors
Use memory processors to filter, transform, or limit recalled messages before they are passed to the agent. These examples demonstrates how to apply token limits, exclude tool calls, and implement a custom processor.
Prerequisites
This example uses the openai model. Make sure to add OPENAI_API_KEY to your .env file.
OPENAI_API_KEY=<your-api-key>And install the following package:
npm install @mastra/libsqlAdding memory to an agent
To add LibSQL memory to an agent, use the Memory class and pass a storage instance using LibSQLStore. The url can point to a remote location or local file.
Memory processor configuration
Enable working memory by setting workingMemory.enabled to true. This allows the agent to remember structured information between interactions. This example also uses memory processors to limit the number of recalled tokens with TokenLimiter and filter out tool calls using ToolCallFilter.
import { Memory } from "@mastra/memory";
import { TokenLimiter, ToolCallFilter } from "@mastra/memory/processors";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { LibSQLStore } from "@mastra/libsql";
export const memoryProcessorAgent = new Agent({
name: "memory-processor-agent",
instructions: "You are an AI agent with the ability to automatically recall memories from previous interactions.",
model: openai("gpt-4o"),
memory: new Memory({
storage: new LibSQLStore({
url: "file:memory-processor.db"
}),
processors: [new TokenLimiter(127000), new ToolCallFilter()],
options: {
workingMemory: {
enabled: true
},
threads: {
generateTitle: true
}
}
})
});Using token limiters
Token limiters control how many tokens are passed to the agent by trimming recalled messages. This helps manage context size and avoid exceeding model limits.
import { Memory } from "@mastra/memory";
import { TokenLimiter } from "@mastra/memory/processors";
export const memoryProcessorAgent = new Agent({
// ...
memory: new Memory({
// ...
processors: [new TokenLimiter(127000)],
}),
});Using token encoding
You can customize how tokens are counted by providing a specific encoding, such as cl100k_base from the js-tiktoken package. This ensures accurate token limits for different models.
import { Memory } from "@mastra/memory";
import { TokenLimiter } from "@mastra/memory/processors";
import cl100k_base from "js-tiktoken/ranks/cl100k_base";
export const memoryProcessorAgent = new Agent({
// ...
memory: new Memory({
// ...
processors: [
new TokenLimiter({
limit: 16000,
encoding: cl100k_base,
}),
],
}),
});Filtering tool calls
The ToolCallFilter processor removes specific tool calls and their results from memory. Filtering out tools like logging or image generation helps reduce noise and keeps the agent focused.
import { Memory } from "@mastra/memory";
import { ToolCallFilter } from "@mastra/memory/processors";
export const memoryProcessorAgent = new Agent({
// ...
memory: new Memory({
// ...
processors: [
new ToolCallFilter({
exclude: ["exampleLoggerTool", "exampleImageGenTool"],
}),
],
}),
});Creating custom processors
Custom memory processors can be created by extending the MemoryProcessor class, allowing custom logic to be applied to the list of recalled messages before they are sent to the agent.
import { MemoryProcessor } from "@mastra/core/memory";
import type { CoreMessage } from "@mastra/core";
export class RecentMessagesProcessor extends MemoryProcessor {
private limit: number;
constructor(limit: number = 10) {
super({ name: "RecentMessagesProcessor" });
this.limit = limit;
}
process(messages: CoreMessage[]): CoreMessage[] {
return messages.slice(-this.limit);
}
}Custom processor usage
This example uses the RecentMessagesProcessor with a limit of 5 to return only the last five messages from memory.
import { Memory } from "@mastra/memory";
import { ToolCallFilter } from "@mastra/memory/processors";
import { RecentMessagesProcessor } from "../processors/example-recent-messages-processor";
export const memoryProcessorAgent = new Agent({
// ...
memory: new Memory({
// ...
processors: [new RecentMessagesProcessor(5)],
}),
});