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 result = await mastraClient.saveMessageToMemory({
  messages: [
    {
      role: "user",
      content: "Hello!",
      id: "1",
      threadId: "thread-1",
      resourceId: "resource-1",
      createdAt: new Date(),
      format: 2,
    },
  ],
  agentId: "agent-1",
});

// result.messages contains the saved messages
console.log(result.messages);

Retrieve Thread Messages

Get messages associated with a memory thread:

// Get all messages in the thread (paginated)
const result = await thread.listMessages();
console.log(result.messages); // Array of messages
console.log(result.total); // Total count
console.log(result.hasMore); // Whether more pages exist

// Get messages with pagination
const result = await thread.listMessages({
  page: 0,
  perPage: 20
});

// Get messages with ordering
const result = await thread.listMessages({
  orderBy: { field: 'createdAt', direction: 'ASC' }
});

Delete Messages

Delete one or more messages from a thread:

// Delete a single message
const result = await thread.deleteMessages("message-id");

// Delete multiple messages
const result = await thread.deleteMessages([
  "message-1",
  "message-2",
  "message-3",
]);

// Returns: { success: true, message: "Message 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");