@mastra/libsql 0.0.0-knowledge-studio-20261029065150 → 0.0.0-knowledge-alpha-studio-20261030162625

package/dist/docs/references/docs-memory-overview.md

@@ -164,6 +164,9 @@ const response = await memoryAgent.generate('Remember my favorite color is blue.
 Scopes can also come from the agent and from the request context. Mastra combines all three sources:
 
 ```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
 export const memoryAgent = new Agent({
   id: 'memory-agent',
   name: 'Memory Agent',
@@ -271,6 +274,9 @@ Open [Studio](https://mastra.ai/docs/studio/overview) and select the **Observabi
 Use [`RequestContext`](https://mastra.ai/docs/server/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
 
 ```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
 export type UserTier = {
   'user-tier': 'enterprise' | 'pro'
 }

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -4,7 +4,11 @@
 
 # Semantic recall
 
-If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
+Semantic recall is a built-in form of Retrieval-Augmented Generation (RAG) for agent memory. When a user sends a message, Mastra searches earlier messages for ones with a similar meaning and adds the most relevant ones to the agent's context.
+
+Matching on meaning matters because people often remember the idea behind something, not the exact words they used. A user might ask "What did we decide about the refund?" after originally writing "Let's give them their money back." A keyword search misses that connection, but semantic recall finds it.
+
+Use semantic recall when your agent needs details from earlier in a long conversation, or from a user's other conversations, that are no longer in [recent message history](https://mastra.ai/docs/memory/message-history).
 
 > **📹 Watch:** Watch [Mastra semantic recall](https://www.youtube.com/watch?v=UVZtK8cK8xQ\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents retrieve relevant messages from past conversations.
 
@@ -452,8 +456,10 @@ const agent = new Agent({
         indexConfig: {
           type: 'hnsw', // Use HNSW for better performance
           metric: 'dotproduct', // Best for OpenAI embeddings
-          m: 16, // Number of bi-directional links (default: 16)
-          efConstruction: 64, // Size of candidate list during construction (default: 64)
+          hnsw: {
+            m: 16, // Number of bi-directional links (default: 16)
+            efConstruction: 64, // Size of candidate list during construction (default: 64)
+          },
         },
       },
     },

package/dist/docs/references/integrations-databases-dynamodb.md

@@ -50,7 +50,7 @@ bun add @mastra/dynamodb@latest
 
 Before using this package, you **must** create a DynamoDB table with a specific structure, including primary keys and Global Secondary Indexes (GSIs). This adapter expects the DynamoDB table and its GSIs to be provisioned externally.
 
-Detailed instructions for setting up the table using AWS CloudFormation or AWS CDK are available in [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md). Please ensure your table is configured according to those instructions before proceeding.
+Detailed instructions for setting up the table using AWS CloudFormation or AWS CDK are available in [TABLE_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md). Please ensure your table is configured according to those instructions before proceeding.
 
 ## Usage
 
@@ -122,7 +122,7 @@ For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/
 
 **config.credentials** (`object`): AWS credentials object with accessKeyId and secretAccessKey. If not provided, the AWS SDK will attempt to source credentials from environment variables, IAM roles (e.g., for EC2/Lambda), or the shared AWS credentials file.
 
-**config.ttl** (`object`): TTL (Time To Live) configuration for automatic data expiration. Configure per entity type: thread, message, trace, eval, workflow\_snapshot, resource, score. Each entity config includes: enabled (boolean), attributeName (string, default: 'ttl'), defaultTtlSeconds (number).
+**config.ttl** (`object`): TTL (Time To Live) configuration for automatic data expiration. Configure per entity type: thread, message, trace, eval, workflow_snapshot, resource, score. Each entity config includes: enabled (boolean), attributeName (string, default: 'ttl'), defaultTtlSeconds (number).
 
 ## TTL (time to live) configuration
 
@@ -254,7 +254,7 @@ The IAM role or user executing the code needs appropriate permissions to interac
 
 Before diving into the architectural details, keep these key points in mind when working with the DynamoDB storage adapter:
 
-- **External Table Provisioning:** This adapter _requires_ you to create and configure the DynamoDB table and its Global Secondary Indexes (GSIs) yourself, prior to using the adapter. Follow the guide in [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md).
+- **External Table Provisioning:** This adapter _requires_ you to create and configure the DynamoDB table and its Global Secondary Indexes (GSIs) yourself, prior to using the adapter. Follow the guide in [TABLE_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md).
 - **Single-Table Design:** All Mastra data (threads, messages, etc.) is stored in one DynamoDB table. This is a deliberate design choice optimized for DynamoDB, differing from relational database approaches.
 - **Understanding GSIs:** Familiarity with how the GSIs are structured (as per `TABLE_SETUP.md`) is important for understanding data retrieval and potential query patterns.
 - **ElectroDB:** The adapter uses ElectroDB to manage interactions with DynamoDB, providing a layer of abstraction and type safety over raw DynamoDB operations.
@@ -266,7 +266,7 @@ This storage adapter utilizes a **single-table design pattern** with [ElectroDB]
 Key aspects of this approach:
 
 - **DynamoDB Native:** The single-table design is optimized for DynamoDB's key-value and query capabilities, often leading to better performance and capacity compared to mimicking relational models.
-- **External Table Management:** Unlike some adapters that might offer helper functions to create tables via code, this adapter **expects the DynamoDB table and its associated Global Secondary Indexes (GSIs) to be provisioned externally** before use. Please refer to [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md) for detailed instructions using tools like AWS CloudFormation or CDK. The adapter focuses solely on interacting with the pre-existing table structure.
+- **External Table Management:** Unlike some adapters that might offer helper functions to create tables via code, this adapter **expects the DynamoDB table and its associated Global Secondary Indexes (GSIs) to be provisioned externally** before use. Please refer to [TABLE_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md) for detailed instructions using tools like AWS CloudFormation or CDK. The adapter focuses solely on interacting with the pre-existing table structure.
 - **Consistency via Interface:** While the underlying storage model differs, this adapter adheres to the same `MastraStorage` interface as other adapters, ensuring it can be used interchangeably within the Mastra `Memory` component.
 
 ### Mastra Data in the Single Table

package/dist/docs/references/reference-core-mastra-class.md

@@ -34,6 +34,8 @@ export const mastra = new Mastra({
 Enable scheduled notification dispatch when deferred notification records and notification summaries should be delivered automatically through the workflow scheduler:
 
 ```typescript
+import { Mastra } from '@mastra/core'
+
 export const mastra = new Mastra({
   agents: { supportAgent },
   storage,
@@ -63,7 +65,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **logger** (`Logger`): Logger instance created with new PinoLogger() (Default: `Console logger with INFO level`)
 
-**loggerOptions** (`{ correlation?: boolean; export?: boolean }`): Controls logger observability behavior. correlation injects trace\_id/span\_id into native log output during traced operations; export forwards log records to observability storage. (Default: `{ correlation: true, export: true }`)
+**loggerOptions** (`{ correlation?: boolean; export?: boolean }`): Controls logger observability behavior. correlation injects trace_id/span_id into native log output during traced operations; export forwards log records to observability storage. (Default: `{ correlation: true, export: true }`)
 
 **idGenerator** (`(context?: IdGeneratorContext) => string`): Custom ID generator function. Used by agents, workflows, memory, and other components to generate unique identifiers. Receives optional context such as idType, source, entityId, and threadId to support context-aware ID formats.
 
@@ -73,9 +75,9 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **observability** (`ObservabilityEntrypoint`): Observability configuration for tracing and monitoring
 
-**environment** (`string`): Deployment environment name (e.g. production, staging, development). When set, automatically attached to all observability signals so they can be filtered by environment without passing tracingOptions.metadata.environment on each call. When unset, resolves to development for mastra dev runs, then falls back to process.env.NODE\_ENV; left undefined if none are set. Per-call tracingOptions.metadata.environment always takes precedence.
+**environment** (`string`): Deployment environment name (e.g. production, staging, development). When set, automatically attached to all observability signals so they can be filtered by environment without passing tracingOptions.metadata.environment on each call. When unset, resolves to development for mastra dev runs, then falls back to process.env.NODE_ENV; left undefined if none are set. Per-call tracingOptions.metadata.environment always takes precedence.
 
-**deployer** (`MastraDeployer`): An instance of a MastraDeployer for managing deployments.
+**deployer** (`IDeployer`): A deployer for managing deployments, such as VercelDeployer from @mastra/deployer-vercel.
 
 **server** (`ServerConfig`): Server configuration including port, host, timeout, API routes, middleware, CORS settings, and build options for Swagger UI, API request logging, and OpenAPI docs.
 
@@ -121,6 +123,8 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **backgroundTasks.perAgentConcurrency** (`number`): Max concurrent tasks per agent.
 
+**backgroundTasks.perOwnerConcurrency** (`Record<string, number>`): Per-owner overrides of perAgentConcurrency, keyed by agentId. Overridden owners still count toward globalConcurrency.
+
 **backgroundTasks.backpressure** (`'queue' | 'reject' | 'fallback-sync'`): Behavior when concurrency limit is reached.
 
 **backgroundTasks.defaultTimeoutMs** (`number`): Default task timeout in milliseconds.

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

@@ -4,7 +4,7 @@
 
 # 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.
+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, unless that vector store embeds text itself, an embedder.
 
 ## Usage example
 
@@ -31,17 +31,17 @@ export const agent = new Agent({
 
 ## Constructor parameters
 
-**storage** (`MastraCompositeStore`): Storage implementation for persisting memory data. Defaults to new DefaultStorage({ config: { url: "file:memory.db" } }) if not provided.
+**storage** (`MastraCompositeStore`): Storage implementation for persisting memory data. Optional: when omitted, an agent uses the storage of the Mastra instance it belongs to. If neither is configured, accessing memory.storage throws Memory requires a storage provider to function.
 
 **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.
+**embedder** (`string | EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder for vector embeddings, as a model-router ID string (for example "openai/text-embedding-3-small"), an EmbeddingModel, or an EmbeddingModelV2. Required when semantic recall is enabled and the vector store doesn't generate embeddings itself (vector.isSelfEmbedding is false).
 
-**embeddingDimension** (`number`): Output dimension of the embedder, as a positive integer. When set, Memory uses it to name the semantic recall index instead of embedding a probe string on first use. It must match the vectors the embedder returns: a mismatch throws a MASTRA\_MEMORY\_EMBEDDING\_DIMENSION\_MISMATCH error before any index is created. See Setting the embedding dimension.
+**embeddingDimension** (`number`): Output dimension of the embedder, as a positive integer. When set, Memory uses it to name the semantic recall index instead of embedding a probe string on first use. It must match the vectors the embedder returns: a mismatch throws a MASTRA_MEMORY_EMBEDDING_DIMENSION_MISMATCH error before any index is created. See Setting the embedding dimension.
 
 **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. The window slides forward on every request, so once a thread exceeds the limit, each turn invalidates the provider prompt cache. For long-running conversations, use Observational Memory instead.
+**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. The window slides forward on every request, so once a thread exceeds the limit, each turn invalidates the provider prompt cache. For long-running conversations, use Observational Memory instead.
 
 **options.messageHistory** (`{ maxTokens: number; atMaxRemoveTokens?: number }`): Token budget for the complete prompt, including remembered history, system instructions, context, and the current turn. When the prompt exceeds maxTokens, the oldest remembered messages are dropped until the prompt is at most maxTokens - atMaxRemoveTokens (defaults to 25% of maxTokens). Protected content is never removed. Linked tool calls and results are removed together. During agent runs, trimmed history is excluded from later turns via a persisted per-thread boundary, but the messages themselves stay in storage. When set without an explicit lastMessages, the default 10-message cap is not applied. Set maxTokens to 0 to disable message history. Prefer this over lastMessages, since message count is a poor proxy for context size.
 
@@ -49,7 +49,7 @@ export const agent = new Agent({
 
 **options.retainFullInput** (`boolean`): When true, the request input is processed exactly as supplied instead of being filtered against stored history. Use this when you assemble the input yourself and need the message sequence preserved. Stored history is still loaded underneath, and every input message that isn't already stored is saved to the thread, including few-shot examples. Can be set per call on memory.options or agent-wide in the memory constructor options.
 
-**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.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 a vector store, and an embedder unless the vector store embeds text itself (isSelfEmbedding). 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.
 
@@ -61,6 +61,83 @@ export const agent = new Agent({
 
 **memory** (`Memory`): A new Memory instance with the specified configuration.
 
+## `saveMessages()`
+
+`agent.generate()` and `agent.stream()` persist messages for you. Call `memory.saveMessages()` when you need to write messages yourself, for example to seed a thread, to import a transcript, or to store messages that originated outside Mastra. Each message needs a `threadId` and a `resourceId`, so create the thread with [`createThread()`](https://mastra.ai/reference/memory/createThread) before saving into it.
+
+```typescript
+await memory.saveMessages({
+  messages: [
+    {
+      id: 'msg-1',
+      threadId: 'thread-123',
+      resourceId: 'user-456',
+      role: 'user',
+      createdAt: new Date(),
+      content: {
+        format: 2,
+        parts: [{ type: 'text', text: 'Where is my order?' }],
+      },
+    },
+  ],
+})
+```
+
+### Parameters
+
+**messages** (`MastraDBMessage[]`): The messages to save. Every message must include a threadId and a resourceId.
+
+**memoryConfig** (`MemoryConfig`): Per-call memory options. Merged over the options passed to the constructor.
+
+**observabilityContext** (`Partial<ObservabilityContext>`): Tracing context attached to the save operation.
+
+Returns `Promise<{ messages: MastraDBMessage[]; usage?: { tokens: number } }>`. `usage` is present when the embedder reports token usage while indexing messages for semantic recall.
+
+### `MastraDBMessage`
+
+Storage uses a single message shape, `MastraDBMessage`. The methods that hand messages back or take them in use this shape, including `saveMessages()` and [`recall()`](https://mastra.ai/reference/memory/recall).
+
+**id** (`string`): Message identifier.
+
+**role** (`'user' | 'assistant' | 'system' | 'signal'`): Who produced the message. System messages and transient signals are not persisted.
+
+**threadId** (`string`): Thread the message belongs to. Required when saving.
+
+**resourceId** (`string`): Resource (usually a user or tenant) the message belongs to. Required when saving.
+
+**createdAt** (`Date`): Message timestamp.
+
+**content** (`MastraMessageContentV2`): The message body. Its parts array holds the text, reasoning, tool calls, and attachments.
+
+`content.parts` is the part the agent actually reads. `content.format` is always `2` for stored messages, and `content.metadata` carries arbitrary custom data. `content.toolInvocations`, `content.reasoning`, and `content.experimental_attachments` are flat mirrors kept for AI SDK v4 compatibility; write to `parts` instead.
+
+```typescript
+const assistantMessage = {
+  id: 'msg-2',
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+  role: 'assistant',
+  createdAt: new Date(),
+  content: {
+    format: 2,
+    parts: [
+      { type: 'text', text: 'It ships tomorrow.' },
+      {
+        type: 'tool-invocation',
+        toolInvocation: {
+          state: 'result',
+          toolCallId: 'call-1',
+          toolName: 'lookupOrder',
+          args: { orderId: 'A-1' },
+          result: { eta: '2026-10-30' },
+        },
+      },
+    ],
+    metadata: { source: 'import' },
+  },
+}
+```
+
 ## Extended usage example
 
 ```typescript
@@ -128,8 +205,10 @@ export const agent = new Agent({
         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
+          hnsw: {
+            m: 16, // Number of bi-directional links
+            efConstruction: 64, // Construction-time candidate list size
+          },
         },
       },
       workingMemory: {

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

@@ -382,6 +382,7 @@ Vector store prompts define query patterns and filtering capabilities for each v
 
 ```ts
 import { MONGODB_PROMPT } from '@mastra/mongodb'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -416,6 +417,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { PINECONE_PROMPT } from '@mastra/pinecone'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -433,6 +435,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { QDRANT_PROMPT } from '@mastra/qdrant'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -450,6 +453,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { CHROMA_PROMPT } from '@mastra/chroma'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -467,6 +471,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { ASTRA_PROMPT } from '@mastra/astra'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -484,6 +489,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { LIBSQL_PROMPT } from '@mastra/libsql'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -501,6 +507,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { UPSTASH_PROMPT } from '@mastra/upstash'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -518,6 +525,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { VECTORIZE_PROMPT } from '@mastra/vectorize'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -535,6 +543,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { OPENSEARCH_PROMPT } from '@mastra/opensearch'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -552,6 +561,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { ORACLEDB_PROMPT } from '@mastra/oracledb'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -569,6 +579,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { S3VECTORS_PROMPT } from '@mastra/s3vectors'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',