@mastra/memory 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

package/dist/docs/references/reference-memory-listThreads.md

@@ -0,0 +1,147 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.listThreads()
+
+The `listThreads()` method retrieves threads with pagination support and optional filtering by `resourceId`, `metadata`, or both.
+
+## Usage examples
+
+### List all threads with pagination
+
+```typescript
+const result = await memory.listThreads({
+  page: 0,
+  perPage: 10,
+})
+```
+
+### Fetch all threads without pagination
+
+Use `perPage: false` to retrieve all matching threads at once.
+
+> **Warning:** 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,
+})
+```
+
+## Parameters
+
+**filter** (`{ resourceId?: string; metadata?: Record<string, unknown> }`): Optional filter object. resourceId filters threads by resource ID. metadata filters threads by metadata key-value pairs (AND logic - all must match)
+
+**page** (`number`): Page number (0-indexed) to retrieve
+
+**perPage** (`number | false`): Maximum number of threads to return per page, or false to fetch all
+
+**orderBy** (`{ field: 'createdAt' | 'updatedAt', direction: 'ASC' | 'DESC' }`): Sort configuration with field and direction (defaults to { field: 'createdAt', direction: 'DESC' })
+
+## Returns
+
+**result** (`Promise<StorageListThreadsOutput>`): A promise that resolves to paginated thread results with metadata
+
+The return object contains:
+
+- `threads`: Array of thread objects
+- `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
+
+## Extended usage example
+
+```typescript
+import { mastra } from './mastra'
+
+const agent = mastra.getAgent('agent')
+const memory = await agent.getMemory()
+
+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?.listThreads({
+    filter: {
+      resourceId: 'user-123',
+      metadata: { status: 'active' },
+    },
+    page: currentPage,
+    perPage: perPage,
+    orderBy: { field: 'createdAt', direction: 'ASC' },
+  })
+
+  if (!result) {
+    console.log('No threads')
+    break
+  }
+
+  result.threads.forEach(thread => {
+    console.log(`Thread: ${thread.id}, Created: ${thread.createdAt}`)
+  })
+
+  hasMorePages = result.hasMore
+  currentPage++ // Move to next page
+}
+```
+
+## 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/memory/memory-class)
+- [Getting Started with Memory](https://mastra.ai/docs/memory/overview)
+- [createThread](https://mastra.ai/reference/memory/createThread)
+- [getThreadById](https://mastra.ai/reference/memory/getThreadById)

package/dist/docs/references/reference-memory-memory-class.md

@@ -0,0 +1,148 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory class
+
+The `Memory` class provides a reliable system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
+
+## Usage example
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+
+export const agent = new Agent({
+  id: 'test-agent',
+  name: 'test-agent',
+  instructions: 'You are an agent with memory.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    options: {
+      workingMemory: {
+        enabled: true,
+      },
+    },
+  }),
+})
+```
+
+> **Note:** To enable `workingMemory` on an agent, you’ll need a storage provider configured on your main Mastra instance. See [Mastra class](https://mastra.ai/reference/core/mastra-class) for more information.
+
+## Constructor parameters
+
+**storage** (`MastraCompositeStore`): Storage implementation for persisting memory data. Defaults to new DefaultStorage({ config: { url: "file:memory.db" } }) if not provided.
+
+**vector** (`MastraVector | false`): Vector store for semantic search capabilities. Set to false to disable vector operations.
+
+**embedder** (`EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder instance for vector embeddings. Required when semantic recall is enabled.
+
+**options** (`MemoryConfig`): Memory configuration options.
+
+**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option.
+
+**options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
+
+**options.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured. Default topK is 4, default messageRange is {before: 1, after: 1}.
+
+**options.workingMemory** (`WorkingMemory`): Configuration for working memory feature. Can be { enabled: boolean; template?: string; schema?: ZodObject\<any> | JSONSchema7; scope?: 'thread' | 'resource' } or { enabled: boolean } to disable.
+
+**options.observationalMemory** (`boolean | ObservationalMemoryOptions`): Enable Observational Memory for long-context agentic memory. Set to true for defaults, or pass a config object to customize token budgets, models, and scope. See Observational Memory reference for configuration details.
+
+**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the conversation transcript. Can be a boolean or an object with custom model and instructions.
+
+## Returns
+
+**memory** (`Memory`): A new Memory instance with the specified configuration.
+
+## Extended usage example
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+export const agent = new Agent({
+  name: 'test-agent',
+  instructions: 'You are an agent with memory.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'test-agent-storage',
+      url: 'file:./working-memory.db',
+    }),
+    vector: new LibSQLVector({
+      id: 'test-agent-vector',
+      url: 'file:./vector-memory.db',
+    }),
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+        scope: 'resource',
+      },
+      workingMemory: {
+        enabled: true,
+      },
+      generateTitle: true,
+    },
+  }),
+})
+```
+
+## PostgreSQL with index configuration
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+import { PgStore, PgVector } from '@mastra/pg'
+
+export const agent = new Agent({
+  name: 'pg-agent',
+  instructions: 'You are an agent with optimized PostgreSQL memory.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage: new PgStore({
+      id: 'pg-agent-storage',
+      connectionString: process.env.DATABASE_URL,
+    }),
+    vector: new PgVector({
+      id: 'pg-agent-vector',
+      connectionString: process.env.DATABASE_URL,
+    }),
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      lastMessages: 20,
+      semanticRecall: {
+        topK: 5,
+        messageRange: 3,
+        scope: 'resource',
+        indexConfig: {
+          type: 'hnsw', // Use HNSW for better performance
+          metric: 'dotproduct', // Optimal for OpenAI embeddings
+          m: 16, // Number of bi-directional links
+          efConstruction: 64, // Construction-time candidate list size
+        },
+      },
+      workingMemory: {
+        enabled: true,
+      },
+    },
+  }),
+})
+```
+
+### Related
+
+- [Getting Started with Memory](https://mastra.ai/docs/memory/overview)
+- [Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)
+- [Working Memory](https://mastra.ai/docs/memory/working-memory)
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
+- [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
+- [createThread](https://mastra.ai/reference/memory/createThread)
+- [recall](https://mastra.ai/reference/memory/recall)
+- [getThreadById](https://mastra.ai/reference/memory/getThreadById)
+- [listThreads](https://mastra.ai/reference/memory/listThreads)
+- [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)
+- [cloneThread](https://mastra.ai/reference/memory/cloneThread)
+- [Clone Utility Methods](https://mastra.ai/reference/memory/clone-utilities)