Memory

Memory gives your agent coherence across interactions and allows it to improve over time by retaining relevant information from past conversations.

Topics

• Overview - Introduction to memory
• Storage - Configure memory storage
• Message History - Manage conversation history
• Observational Memory - Learn from interactions
• Working Memory - Short-term context
• Semantic Recall - Retrieve relevant memories
• Memory Processors - Transform memory data

Memory Overview

Memory enables agents to maintain context across conversations and learn from past interactions.

Memory Types

• Episodic Memory - Stores conversation history
• Semantic Memory - Stores facts and knowledge
• Working Memory - Active context during interactions
• Observational Memory - Learns from interactions

Enabling Memory

export const mastra = new Mastra({
  agents: {
    myAgent: {
      name: 'My Agent',
      memory: {
        type: 'episodic',
        storage: myVectorStore,
      },
    },
  },
});

Memory Retention

Configure how long and what to retain:

const memoryConfig = {
  retention: {
    maxMessages: 100,
    maxAge: '30d',
  },
};

Memory Storage

Configure where and how memory is stored.

Storage Options

• Vector stores - For semantic search (Pinecone, Qdrant, etc.)
• Database storage - PostgreSQL, MongoDB, etc.
• Cloud storage - Cloudflare D1, Upstash, etc.

Configuration

export const mastra = new Mastra({
  memory: {
    storage: {
      type: 'vector',
      provider: 'pinecone',
      index: 'memory-index',
    },
  },
});

Hybrid Storage

Combine multiple storage types:

const memoryConfig = {
  storage: {
    episodic: vectorStore,
    semantic: databaseStore,
  },
};

Message History

Message history stores the complete conversation between users and agents.

Configuration

export const mastra = new Mastra({
  memory: {
    messageHistory: {
      maxMessages: 100,
      includeSystemMessages: true,
      truncateAt: 'user',
    },
  },
});

Retrieving History

const agent = mastra.getAgent('myAgent');
const history = await agent.getMemory().getHistory();

for (const message of history.messages) {
  console.log(`${message.role}: ${message.content}`);
}

Managing History

• Truncation - Limit stored messages
• Summarization - Compress old messages
• Filtering - Exclude certain message types

Observational Memory

Observational memory learns from interactions without explicit training.

How It Works

1. Agent observes user interactions
2. Relevant patterns are identified
3. Knowledge is extracted and stored
4. Agent uses learned knowledge in future interactions

Configuration

export const mastra = new Mastra({
  memory: {
    observational: {
      enabled: true,
      learningRate: 0.1,
      minObservations: 5,
    },
  },
});

What Gets Learned

• User preferences
• Common tasks
• Communication patterns
• Domain-specific knowledge

Working Memory

Working memory holds active context during agent interactions.

Purpose

• Maintain current task context
• Hold intermediate results
• Track sub-goals in complex tasks

Configuration

export const mastra = new Mastra({
  memory: {
    working: {
      maxItems: 10,
      ttl: '1h',
    },
  },
});

Using Working Memory

const agent = mastra.getAgent('myAgent');

// Set working memory
await agent.getMemory().setWorking('currentTask', {
  goal: 'Research AI',
  progress: '50%',
  subtasks: ['search', 'summarize'],
});

// Get working memory
const context = await agent.getMemory().getWorking('currentTask');

Semantic Recall

Semantic recall retrieves relevant memories based on meaning, not just keywords.

How It Works

1. Memories are embedded as vectors
2. New queries are embedded
3. Similar memories are retrieved using vector similarity

Configuration

export const mastra = new Mastra({
  memory: {
    semanticRecall: {
      enabled: true,
      topK: 5,
      threshold: 0.8,
    },
  },
});

Usage

const agent = mastra.getAgent('myAgent');

const relevantMemories = await agent.getMemory().recall(
  'What did the user say about their project?'
);

Best Practices

• Use descriptive memory content
• Set appropriate similarity thresholds
• Limit retrieved memories to prevent context overflow

Memory Processors

Memory processors transform and filter memory data.

Built-in Processors

• SemanticRecallProcessor - Semantic search for memories
• SkillSearchProcessor - Find relevant skills
• ToolSearchProcessor - Find relevant tools

Creating Custom Processors

import { MemoryProcessor } from '@mastra/core';

const customProcessor = new MemoryProcessor({
  name: 'customMemoryProcessor',
  process: async (memory, context) => {
    // Transform or filter memory
    return processedMemory;
  },
});

Applying Processors

export const mastra = new Mastra({
  memory: {
    processors: [customProcessor],
  },
});