@mastra/memory 1.0.0-beta.13 → 1.0.0-beta.15

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @mastra/memory
 
+## 1.0.0-beta.15
+
+### Minor Changes
+
+- Added new `listThreads` method for flexible thread filtering across all storage adapters. ([#11832](https://github.com/mastra-ai/mastra/pull/11832))
+
+  **New Features**
+  - Filter threads by `resourceId`, `metadata`, or both (with AND logic for metadata key-value pairs)
+  - All filter parameters are optional, allowing you to list all threads or filter as needed
+  - Full pagination and sorting support
+
+  **Example Usage**
+
+  ```typescript
+  // List all threads
+  const allThreads = await memory.listThreads({});
+
+  // Filter by resourceId only
+  const userThreads = await memory.listThreads({
+    filter: { resourceId: 'user-123' },
+  });
+
+  // Filter by metadata only
+  const supportThreads = await memory.listThreads({
+    filter: { metadata: { category: 'support' } },
+  });
+
+  // Filter by both with pagination
+  const filteredThreads = await memory.listThreads({
+    filter: {
+      resourceId: 'user-123',
+      metadata: { priority: 'high', status: 'open' },
+    },
+    orderBy: { field: 'updatedAt', direction: 'DESC' },
+    page: 0,
+    perPage: 20,
+  });
+  ```
+
+  **Security Improvements**
+  - Added validation to prevent SQL injection via malicious metadata keys
+  - Added pagination parameter validation to prevent integer overflow attacks
+
+### Patch Changes
+
+- Updated dependencies [[`ed3e3dd`](https://github.com/mastra-ai/mastra/commit/ed3e3ddec69d564fe2b125e083437f76331f1283), [`6833c69`](https://github.com/mastra-ai/mastra/commit/6833c69607418d257750bbcdd84638993d343539), [`47b1c16`](https://github.com/mastra-ai/mastra/commit/47b1c16a01c7ffb6765fe1e499b49092f8b7eba3), [`3a76a80`](https://github.com/mastra-ai/mastra/commit/3a76a80284cb71a0faa975abb3d4b2a9631e60cd), [`8538a0d`](https://github.com/mastra-ai/mastra/commit/8538a0d232619bf55dad7ddc2a8b0ca77c679a87), [`9312dcd`](https://github.com/mastra-ai/mastra/commit/9312dcd1c6f5b321929e7d382e763d95fdc030f5)]:
+  - @mastra/core@1.0.0-beta.25
+  - @mastra/schema-compat@1.0.0-beta.8
+
+## 1.0.0-beta.14
+
+### Patch Changes
+
+- Updated dependencies [[`1dbd8c7`](https://github.com/mastra-ai/mastra/commit/1dbd8c729fb6536ec52f00064d76b80253d346e9), [`c59e13c`](https://github.com/mastra-ai/mastra/commit/c59e13c7688284bd96b2baee3e314335003548de), [`f93e2f5`](https://github.com/mastra-ai/mastra/commit/f93e2f575e775e627e5c1927cefdd72db07858ed), [`f9a2509`](https://github.com/mastra-ai/mastra/commit/f9a25093ea72d210a5e52cfcb3bcc8b5e02dc25c), [`7a010c5`](https://github.com/mastra-ai/mastra/commit/7a010c56b846a313a49ae42fccd3d8de2b9f292d)]:
+  - @mastra/core@1.0.0-beta.24
+  - @mastra/schema-compat@1.0.0-beta.7
+
 ## 1.0.0-beta.13
 
 ### Major Changes

package/dist/docs/README.md

@@ -33,4 +33,4 @@ docs/
 ## Version
 
 Package: @mastra/memory
-Version: 1.0.0-beta.13
+Version: 1.0.0-beta.15

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/memory. Includes links to type definition
 
 # @mastra/memory Documentation
 
-> **Version**: 1.0.0-beta.13
+> **Version**: 1.0.0-beta.15
 > **Package**: @mastra/memory
 
 ## Quick Navigation

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.15",
   "package": "@mastra/memory",
   "exports": {
     "extractWorkingMemoryContent": {

package/dist/docs/agents/01-agent-memory.md

@@ -90,6 +90,9 @@ export const memoryAgent = new Agent({
 });
 ```
 
+> **Mastra Cloud Store limitation**
+Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/v1/mastra-cloud/deployment#using-mastra-cloud-store). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+
 ## Message history
 
 Include a `memory` object with both `resource` and `thread` to track message history during agent calls.
@@ -122,6 +125,9 @@ const response = await memoryAgent.generate("What's my favorite color?", {
 });
 ```
 
+> **Note:**
+Each thread has an owner (`resourceId`) that cannot be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
+
 To learn more about memory see the [Memory](../memory/overview) documentation.
 
 ## Using `RequestContext`

package/dist/docs/agents/03-agent-approval.md

@@ -64,6 +64,67 @@ const handleDecline = async () => {
 };
 ```
 
+## Tool approval with generate()
+
+Tool approval also works with the `generate()` method for non-streaming use cases. When using `generate()` with `requireToolApproval: true`, the method returns immediately when a tool requires approval instead of executing it.
+
+### How it works
+
+When a tool requires approval during a `generate()` call, the response includes:
+
+- `finishReason: 'suspended'` - indicates the agent is waiting for approval
+- `suspendPayload` - contains tool call details (`toolCallId`, `toolName`, `args`)
+- `runId` - needed to approve or decline the tool call
+
+### Approving tool calls
+
+To approve a tool call with `generate()`, use the `approveToolCallGenerate` method:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  console.log("Tool requires approval:", output.suspendPayload.toolName);
+  console.log("Arguments:", output.suspendPayload.args);
+
+  // Approve the tool call and get the final result
+  const result = await agent.approveToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log("Final result:", result.text);
+}
+```
+
+### Declining tool calls
+
+To decline a tool call, use the `declineToolCallGenerate` method:
+
+```typescript
+if (output.finishReason === "suspended") {
+  const result = await agent.declineToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  // Agent will respond acknowledging the declined tool
+  console.log(result.text);
+}
+```
+
+### Stream vs Generate comparison
+
+| Aspect | `stream()` | `generate()` |
+|--------|-----------|--------------|
+| Response type | Streaming chunks | Complete response |
+| Approval detection | `tool-call-approval` chunk | `finishReason: 'suspended'` |
+| Approve method | `approveToolCall({ runId })` | `approveToolCallGenerate({ runId, toolCallId })` |
+| Decline method | `declineToolCall({ runId })` | `declineToolCallGenerate({ runId, toolCallId })` |
+| Result | Stream to iterate | Full output object |
+
 ## Tool-level approval
 
 There are two types of tool call approval. The first uses `requireApproval`, which is a property on the tool definition, while `requireToolApproval` is a parameter passed to `agent.stream()`. The second uses `suspend` and lets the agent provide context or confirmation prompts so the user can decide whether the tool call should continue.

package/dist/docs/memory/02-storage.md

@@ -115,6 +115,9 @@ export const agent = new Agent({
 
 This is useful when different agents need to store data in separate databases for security, compliance, or organizational reasons.
 
+> **Mastra Cloud Store limitation**
+Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/v1/mastra-cloud/deployment#using-mastra-cloud-store). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+
 ## Threads and resources
 
 Mastra organizes memory into threads using two identifiers:
@@ -136,6 +139,21 @@ const stream = await agent.stream("message for agent", {
 > **Note:**
 [Studio](https://mastra.ai/docs/v1/getting-started/studio) automatically generates a thread and resource ID for you. Remember to  to pass these explicitly when calling `stream` or `generate` yourself.
 
+### Thread and resource relationship
+
+Each thread has an owner (its `resourceId`) that is set when the thread is created and cannot be changed. When you query a thread, you must use the correct owner's resource ID. Attempting to query a thread with a different resource ID will result in an error:
+
+```text
+Thread with id <thread_id> is for resource with id <resource_a>
+but resource <resource_b> was queried
+```
+
+Note that while each thread has one owner, messages within that thread can have different `resourceId` values. This is used for message attribution and filtering (e.g., distinguishing between different agents in a multi-agent system, or filtering messages for analytics).
+
+**Security:** Memory is a storage layer, not an authorization layer. Your application must implement access control before calling memory APIs. The `resourceId` parameter controls both validation and filtering - provide it to validate ownership and filter messages, or omit it for server-side access without validation.
+
+To avoid accidentally reusing thread IDs across different owners, use UUIDs: `crypto.randomUUID()`
+
 ### Thread title generation
 
 Mastra can automatically generate descriptive thread titles based on the user's first message.

package/dist/docs/memory/06-reference.md

@@ -224,7 +224,7 @@ async function manageClones() {
 - [cloneThread](https://mastra.ai/reference/v1/memory/cloneThread)
 - [Memory Class Reference](https://mastra.ai/reference/v1/memory/memory-class)
 - [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
-- [listThreadsByResourceId](https://mastra.ai/reference/v1/memory/listThreadsByResourceId)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
 
 ---
 
@@ -387,7 +387,7 @@ console.log(response.text);
 - [Memory Class Reference](https://mastra.ai/reference/v1/memory/memory-class)
 - [Getting Started with Memory](https://mastra.ai/docs/v1/memory/overview) (Covers threads concept)
 - [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
-- [listThreadsByResourceId](https://mastra.ai/reference/v1/memory/listThreadsByResourceId)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
 - [recall](https://mastra.ai/reference/v1/memory/recall)
 
 ---
@@ -413,21 +413,70 @@ await memory?.getThreadById({ threadId: "thread-123" });
 - [Memory Class Reference](https://mastra.ai/reference/v1/memory/memory-class)
 - [Getting Started with Memory](https://mastra.ai/docs/v1/memory/overview) (Covers threads concept)
 - [createThread](https://mastra.ai/reference/v1/memory/createThread)
-- [listThreadsByResourceId](https://mastra.ai/reference/v1/memory/listThreadsByResourceId)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
 
 ---
 
-## Reference: Memory.listThreadsByResourceId()
+## Reference: Memory.listThreads()
 
-> Documentation for the `Memory.listThreadsByResourceId()` method in Mastra, which retrieves threads associated with a specific resource ID with pagination support.
+> Documentation for the `Memory.listThreads()` method in Mastra, which retrieves threads with optional filtering by resourceId and/or metadata.
 
-The `.listThreadsByResourceId()` method retrieves threads associated with a specific resource ID with pagination support.
+The `listThreads()` method retrieves threads with pagination support and optional filtering by `resourceId`, `metadata`, or both.
 
-## Usage Example
+## Usage Examples
+
+### List all threads with pagination
 
 ```typescript
-await memory.listThreadsByResourceId({
-  resourceId: "user-123",
+const result = await memory.listThreads({
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Fetch all threads without pagination
+
+Use `perPage: false` to retrieve all matching threads at once.
+
+> **Note:**
+
+Generally speaking it's recommended to use pagination, especially for large datasets. Use this option cautiously.
+
+```typescript
+const result = await memory.listThreads({
+  filter: { resourceId: "user-123" },
+  perPage: false,
+});
+```
+
+### Filter by resourceId
+
+```typescript
+const result = await memory.listThreads({
+  filter: { resourceId: "user-123" },
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Filter by metadata
+
+```typescript
+const result = await memory.listThreads({
+  filter: { metadata: { category: "support", priority: "high" } },
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Combined filter (resourceId & metadata)
+
+```typescript
+const result = await memory.listThreads({
+  filter: {
+    resourceId: "user-123",
+    metadata: { status: "active" },
+  },
   page: 0,
   perPage: 10,
 });
@@ -438,8 +487,9 @@ await memory.listThreadsByResourceId({
 ## Returns
 
 The return object contains:
+
 - `threads`: Array of thread objects
-- `total`: Total number of threads for this resource
+- `total`: Total number of threads matching the filter
 - `page`: Current page number (same as the input `page` parameter)
 - `perPage`: Items per page (same as the input `perPage` parameter)
 - `hasMore`: Boolean indicating if more results are available
@@ -456,9 +506,13 @@ let currentPage = 0;
 const perPage = 25;
 let hasMorePages = true;
 
+// Fetch all active threads for a user, sorted by creation date
 while (hasMorePages) {
-  const result = await memory?.listThreadsByResourceId({
-    resourceId: "user-123",
+  const result = await memory?.listThreads({
+    filter: {
+      resourceId: "user-123",
+      metadata: { status: "active" },
+    },
     page: currentPage,
     perPage: perPage,
     orderBy: { field: "createdAt", direction: "ASC" },
@@ -478,6 +532,24 @@ while (hasMorePages) {
 }
 ```
 
+## Metadata Filtering
+
+The metadata filter uses AND logic - all specified key-value pairs must match for a thread to be included in the results:
+
+```typescript
+// This will only return threads where BOTH conditions are true:
+// - category === 'support'
+// - priority === 'high'
+await memory.listThreads({
+  filter: {
+    metadata: {
+      category: "support",
+      priority: "high",
+    },
+  },
+});
+```
+
 ## Related
 
 - [Memory Class Reference](https://mastra.ai/reference/v1/memory/memory-class)
@@ -609,7 +681,7 @@ export const agent = new Agent({
 - [createThread](https://mastra.ai/reference/v1/memory/createThread)
 - [recall](https://mastra.ai/reference/v1/memory/recall)
 - [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
-- [listThreadsByResourceId](https://mastra.ai/reference/v1/memory/listThreadsByResourceId)
+- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
 - [deleteMessages](https://mastra.ai/reference/v1/memory/deleteMessages)
 - [cloneThread](https://mastra.ai/reference/v1/memory/cloneThread)
 - [Clone Utility Methods](https://mastra.ai/reference/v1/memory/clone-utilities)

package/dist/index.cjs

@@ -14722,9 +14722,9 @@ var Memory = class extends memory.MastraMemory {
     const memoryStore = await this.getMemoryStore();
     return memoryStore.getThreadById({ threadId });
   }
-  async listThreadsByResourceId(args) {
+  async listThreads(args) {
     const memoryStore = await this.getMemoryStore();
-    return memoryStore.listThreadsByResourceId(args);
+    return memoryStore.listThreads(args);
   }
   async handleWorkingMemoryFromMetadata({
     workingMemory,
@@ -15572,8 +15572,8 @@ ${template.content !== this.defaultWorkingMemoryTemplate ? `- Only store informa
       }
       targetResourceId = sourceThread.resourceId;
     }
-    const { threads } = await this.listThreadsByResourceId({
-      resourceId: targetResourceId,
+    const { threads } = await this.listThreads({
+      filter: { resourceId: targetResourceId },
       perPage: false
       // Get all threads
     });