@mastra/core 1.6.0 → 1.7.0

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

@@ -1,154 +0,0 @@
-# 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

@@ -1,264 +0,0 @@
-# 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

@@ -1,92 +0,0 @@
-# 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)