@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-processors-working-memory-processor.md

@@ -0,0 +1,152 @@
+# WorkingMemory
+
+The `WorkingMemory` is an **input processor** that injects working memory data as a system message. It retrieves persistent information from storage and formats it as instructions for the LLM, enabling the agent to maintain context about users across conversations.
+
+## Usage example
+
+```typescript
+import { WorkingMemory } from '@mastra/core/processors'
+
+const processor = new WorkingMemory({
+  storage: memoryStorage,
+  scope: 'resource',
+  template: {
+    format: 'markdown',
+    content: `# User Profile
+- **Name**:
+- **Preferences**:
+- **Goals**:
+`,
+  },
+})
+```
+
+## Constructor parameters
+
+**options:** (`Options`): Configuration options for the working memory processor
+
+### Options
+
+**storage:** (`MemoryStorage`): Storage instance for retrieving working memory data
+
+**template?:** (`WorkingMemoryTemplate`): Template defining the format and structure of working memory
+
+**scope?:** (`'thread' | 'resource'`): Scope of working memory. 'thread' scopes to current thread, 'resource' shares across all threads for the resource
+
+**useVNext?:** (`boolean`): Use the next-generation instruction format with improved guidelines
+
+**readOnly?:** (`boolean`): When true, working memory is provided as read-only context. The data is injected into the conversation but without the updateWorkingMemory tool or update instructions. Useful for agents that should reference working memory without modifying it.
+
+**templateProvider?:** (`{ getWorkingMemoryTemplate(args: { memoryConfig?: MemoryConfig }): Promise<WorkingMemoryTemplate | null> }`): Dynamic template provider for runtime template resolution
+
+**logger?:** (`IMastraLogger`): Optional logger instance for structured logging
+
+### WorkingMemoryTemplate
+
+**format:** (`'markdown' | 'json'`): Format of the working memory content
+
+**content:** (`string`): Template content defining the structure of working memory data
+
+## Returns
+
+**id:** (`string`): Processor identifier set to 'working-memory'
+
+**name:** (`string`): Processor display name set to 'WorkingMemory'
+
+**defaultWorkingMemoryTemplate:** (`string`): The default markdown template used when no custom template is provided
+
+**processInput:** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Retrieves working memory and adds it as a system message to the message list
+
+## Extended usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { WorkingMemory, MessageHistory } from '@mastra/core/processors'
+import { PostgresStorage } from '@mastra/pg'
+
+const storage = new PostgresStorage({
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const agent = new Agent({
+  name: 'personalized-agent',
+  instructions: 'You are a helpful assistant that remembers user preferences',
+  model: 'openai:gpt-4o',
+  inputProcessors: [
+    new WorkingMemory({
+      storage,
+      scope: 'resource',
+      template: {
+        format: 'markdown',
+        content: `# User Information
+- **Name**:
+- **Location**:
+- **Preferences**:
+- **Communication Style**:
+- **Current Projects**:
+`,
+      },
+    }),
+    new MessageHistory({ storage, lastMessages: 50 }),
+  ],
+  outputProcessors: [new MessageHistory({ storage })],
+})
+```
+
+## JSON format example
+
+```typescript
+import { WorkingMemory } from '@mastra/core/processors'
+
+const processor = new WorkingMemory({
+  storage: memoryStorage,
+  scope: 'resource',
+  template: {
+    format: 'json',
+    content: JSON.stringify({
+      user: {
+        name: { type: 'string' },
+        preferences: { type: 'object' },
+        goals: { type: 'array' },
+      },
+    }),
+  },
+})
+```
+
+## Behavior
+
+### Input processing
+
+1. Retrieves `threadId` and `resourceId` from the request context
+
+2. Based on scope, fetches working memory from either:
+
+   - Thread metadata (`scope: 'thread'`)
+   - Resource record (`scope: 'resource'`)
+
+3. Resolves the template (from provider, options, or default)
+
+4. Generates system instructions based on mode:
+
+   - **Normal mode**: Includes guidelines for storing/updating information, template structure, and current data
+   - **Read-only mode** (`readOnly: true`): Includes only the current data as context without update instructions
+
+5. Adds the instruction as a system message with `source: 'memory'` tag
+
+### Working memory updates
+
+Working memory updates happen through the `updateWorkingMemory` tool provided by the Memory class, not through this processor. The processor only handles injecting the current working memory state into conversations.
+
+### Default template
+
+If no template is provided, the processor uses a default markdown template with fields for:
+
+- First Name, Last Name
+- Location, Occupation
+- Interests, Goals
+- Events, Facts, Projects
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)

package/dist/docs/references/reference-rag-database-config.md

@@ -0,0 +1,261 @@
+# DatabaseConfig
+
+The `DatabaseConfig` type allows you to specify database-specific configurations when using vector query tools. These configurations enable you to leverage unique features and optimizations offered by different vector stores.
+
+## Type Definition
+
+```typescript
+export type DatabaseConfig = {
+  pinecone?: PineconeConfig
+  pgvector?: PgVectorConfig
+  chroma?: ChromaConfig
+  [key: string]: any // Extensible for future databases
+}
+```
+
+## Database-Specific Types
+
+### PineconeConfig
+
+Configuration options specific to Pinecone vector store.
+
+**namespace?:** (`string`): Pinecone namespace for organizing and isolating vectors within the same index. Useful for multi-tenancy or environment separation.
+
+**sparseVector?:** (`{ indices: number[]; values: number[]; }`): objectindices:number\[]Array of indices for sparse vector componentsvalues:number\[]Array of values corresponding to the indices
+
+**Use Cases:**
+
+- Multi-tenant applications (separate namespaces per tenant)
+- Environment isolation (dev/staging/prod namespaces)
+- Hybrid search combining semantic and keyword matching
+
+### PgVectorConfig
+
+Configuration options specific to PostgreSQL with pgvector extension.
+
+**minScore?:** (`number`): Minimum similarity score threshold for results. Only vectors with similarity scores above this value will be returned.
+
+**ef?:** (`number`): HNSW search parameter that controls the size of the dynamic candidate list during search. Higher values improve accuracy at the cost of speed. Typically set between topK and 200.
+
+**probes?:** (`number`): IVFFlat probe parameter that specifies the number of index cells to visit during search. Higher values improve recall at the cost of speed.
+
+**Performance Guidelines:**
+
+- **ef**: Start with 2-4x your topK value, increase for better accuracy
+- **probes**: Start with 1-10, increase for better recall
+- **minScore**: Use values between 0.5-0.9 depending on your quality requirements
+
+**Use Cases:**
+
+- Performance optimization for high-load scenarios
+- Quality filtering to remove irrelevant results
+- Fine-tuning search accuracy vs speed tradeoffs
+
+### ChromaConfig
+
+Configuration options specific to Chroma vector store.
+
+**where?:** (`Record<string, any>`): Metadata filtering conditions using MongoDB-style query syntax. Filters results based on metadata fields.
+
+**whereDocument?:** (`Record<string, any>`): Document content filtering conditions. Allows filtering based on the actual document text content.
+
+**Filter Syntax Examples:**
+
+```typescript
+// Simple equality
+where: { "category": "technical" }
+
+// Operators
+where: { "price": { "$gt": 100 } }
+
+// Multiple conditions
+where: {
+  "category": "electronics",
+  "inStock": true
+}
+
+// Document content filtering
+whereDocument: { "$contains": "API documentation" }
+```
+
+**Use Cases:**
+
+- Advanced metadata filtering
+- Content-based document filtering
+- Complex query combinations
+
+## Usage Examples
+
+**Basic Usage**:
+
+### Basic Database Configuration
+
+```typescript
+import { createVectorQueryTool } from '@mastra/rag'
+
+const vectorTool = createVectorQueryTool({
+  vectorStoreName: 'pinecone',
+  indexName: 'documents',
+  model: embedModel,
+  databaseConfig: {
+    pinecone: {
+      namespace: 'production',
+    },
+  },
+})
+```
+
+**Runtime Override**:
+
+### Runtime Configuration Override
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+// Initial configuration
+const vectorTool = createVectorQueryTool({
+  vectorStoreName: 'pinecone',
+  indexName: 'documents',
+  model: embedModel,
+  databaseConfig: {
+    pinecone: {
+      namespace: 'development',
+    },
+  },
+})
+
+// Override at runtime
+const requestContext = new RequestContext()
+requestContext.set('databaseConfig', {
+  pinecone: {
+    namespace: 'production',
+  },
+})
+
+await vectorTool.execute({ queryText: 'search query' }, { mastra, requestContext })
+```
+
+**Multi-Database**:
+
+### Multi-Database Configuration
+
+```typescript
+const vectorTool = createVectorQueryTool({
+  vectorStoreName: 'dynamic', // Will be determined at runtime
+  indexName: 'documents',
+  model: embedModel,
+  databaseConfig: {
+    pinecone: {
+      namespace: 'default',
+    },
+    pgvector: {
+      minScore: 0.8,
+      ef: 150,
+    },
+    chroma: {
+      where: { type: 'documentation' },
+    },
+  },
+})
+```
+
+> **Note:** **Multi-Database Support**: When you configure multiple databases, only the configuration matching the actual vector store being used will be applied.
+
+**Performance Tuning**:
+
+### Performance Tuning
+
+```typescript
+// High accuracy configuration
+const highAccuracyTool = createVectorQueryTool({
+  vectorStoreName: 'postgres',
+  indexName: 'embeddings',
+  model: embedModel,
+  databaseConfig: {
+    pgvector: {
+      ef: 400, // High accuracy
+      probes: 20, // High recall
+      minScore: 0.85, // High quality threshold
+    },
+  },
+})
+
+// High speed configuration
+const highSpeedTool = createVectorQueryTool({
+  vectorStoreName: 'postgres',
+  indexName: 'embeddings',
+  model: embedModel,
+  databaseConfig: {
+    pgvector: {
+      ef: 50, // Lower accuracy, faster
+      probes: 3, // Lower recall, faster
+      minScore: 0.6, // Lower quality threshold
+    },
+  },
+})
+```
+
+## Extensibility
+
+The `DatabaseConfig` type is designed to be extensible. To add support for a new vector database:
+
+```typescript
+// 1. Define the configuration interface
+export interface NewDatabaseConfig {
+  customParam1?: string
+  customParam2?: number
+}
+
+// 2. Extend DatabaseConfig type
+export type DatabaseConfig = {
+  pinecone?: PineconeConfig
+  pgvector?: PgVectorConfig
+  chroma?: ChromaConfig
+  newdatabase?: NewDatabaseConfig
+  [key: string]: any
+}
+
+// 3. Use in vector query tool
+const vectorTool = createVectorQueryTool({
+  vectorStoreName: 'newdatabase',
+  indexName: 'documents',
+  model: embedModel,
+  databaseConfig: {
+    newdatabase: {
+      customParam1: 'value',
+      customParam2: 42,
+    },
+  },
+})
+```
+
+## Best Practices
+
+1. **Environment Configuration**: Use different namespaces or configurations for different environments
+2. **Performance Tuning**: Start with default values and adjust based on your specific needs
+3. **Quality Filtering**: Use minScore to filter out low-quality results
+4. **Runtime Flexibility**: Override configurations at runtime for dynamic scenarios
+5. **Documentation**: Document your specific configuration choices for team members
+
+## Migration Guide
+
+Existing vector query tools continue to work without changes. To add database configurations:
+
+```diff
+const vectorTool = createVectorQueryTool({
+  vectorStoreName: 'pinecone',
+  indexName: 'documents',
+  model: embedModel,
++ databaseConfig: {
++   pinecone: {
++     namespace: 'production'
++   }
++ }
+});
+```
+
+## Related
+
+- [createVectorQueryTool()](https://mastra.ai/reference/tools/vector-query-tool)
+- [Hybrid Vector Search](https://mastra.ai/docs/rag/retrieval)
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/dist/docs/references/reference-rag-embeddings.md

@@ -0,0 +1,92 @@
+# Embed
+
+Mastra uses the AI SDK's `embed` and `embedMany` functions to generate vector embeddings for text inputs, enabling similarity search and RAG workflows.
+
+## Single Embedding
+
+The `embed` function generates a vector embedding for a single text input:
+
+```typescript
+import { embed } from 'ai'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+
+const result = await embed({
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  value: 'Your text to embed',
+  maxRetries: 2, // optional, defaults to 2
+})
+```
+
+### Parameters
+
+**model:** (`EmbeddingModel`): The embedding model to use (e.g. openai.embedding('text-embedding-3-small'))
+
+**value:** (`string | Record<string, any>`): The text content or object to embed
+
+**maxRetries?:** (`number`): Maximum number of retries per embedding call. Set to 0 to disable retries. (Default: `2`)
+
+**abortSignal?:** (`AbortSignal`): Optional abort signal to cancel the request
+
+**headers?:** (`Record<string, string>`): Additional HTTP headers for the request (only for HTTP-based providers)
+
+### Return Value
+
+**embedding:** (`number[]`): The embedding vector for the input
+
+## Multiple Embeddings
+
+For embedding multiple texts at once, use the `embedMany` function:
+
+```typescript
+import { embedMany } from 'ai'
+
+const result = await embedMany({
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  values: ['First text', 'Second text', 'Third text'],
+  maxRetries: 2, // optional, defaults to 2
+})
+```
+
+### Parameters
+
+**model:** (`EmbeddingModel`): The embedding model to use (e.g. openai.embedding('text-embedding-3-small'))
+
+**values:** (`string[] | Record<string, any>[]`): Array of text content or objects to embed
+
+**maxRetries?:** (`number`): Maximum number of retries per embedding call. Set to 0 to disable retries. (Default: `2`)
+
+**abortSignal?:** (`AbortSignal`): Optional abort signal to cancel the request
+
+**headers?:** (`Record<string, string>`): Additional HTTP headers for the request (only for HTTP-based providers)
+
+### Return Value
+
+**embeddings:** (`number[][]`): Array of embedding vectors corresponding to the input values
+
+## Example Usage
+
+```typescript
+import { embed, embedMany } from 'ai'
+
+// Single embedding
+const singleResult = await embed({
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  value: 'What is the meaning of life?',
+})
+
+// Multiple embeddings
+const multipleResult = await embedMany({
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  values: [
+    'First question about life',
+    'Second question about universe',
+    'Third question about everything',
+  ],
+})
+```
+
+For more detailed information about embeddings in the Vercel AI SDK, see:
+
+- [AI SDK Embeddings Overview](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings)
+- [embed()](https://sdk.vercel.ai/docs/reference/ai-sdk-core/embed)
+- [embedMany()](https://sdk.vercel.ai/docs/reference/ai-sdk-core/embed-many)