Memory API

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",
});

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();

Message Operations

Save Messages

Save messages to memory:

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

Retrieve Thread Messages

Get messages associated with a memory thread:

// Get all messages in the thread
const { messages } = await thread.getMessages();

// Limit the number of messages retrieved
const { messages } = await thread.getMessages({ limit: 10 });

Delete a Message

Delete a specific message from a thread:

const result = await thread.deleteMessage("message-id");
// Returns: { success: true, message: "Message deleted successfully" }

Delete Multiple Messages

Delete multiple messages from a thread in a single operation:

const result = await thread.deleteMessages([
  "message-1",
  "message-2",
  "message-3",
]);
// Returns: { success: true, message: "3 messages 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: The current working memory content (string or null)
• source: Whether the memory is from "thread" or "resource" scope
• workingMemoryTemplate: The template used for working memory (if configured)
• threadExists: Whether the thread exists

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 }

Note: For resource-scoped working memory, you must provide the resourceId parameter. This allows the memory to persist across all conversation threads for that user.

Get Memory Status

Check the status of the memory system:

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