@mastra/libsql 0.0.0-structured-output-issue-20260302184919 → 0.0.0-structured-output-errors-20260409185629

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

@@ -2,44 +2,239 @@
 
 Memory enables your agent to remember user messages, agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, and produce better answers over time.
 
-Mastra supports four complementary memory types:
+Mastra agents can be configured to store [message history](https://mastra.ai/docs/memory/message-history). Additionally, you can enable:
 
-- [**Message history**](https://mastra.ai/docs/memory/message-history) - keeps recent messages from the current conversation so they can be rendered in the UI and used to maintain short-term continuity within the exchange.
-- [**Working memory**](https://mastra.ai/docs/memory/working-memory) - stores persistent, structured user data such as names, preferences, and goals.
-- [**Semantic recall**](https://mastra.ai/docs/memory/semantic-recall) - retrieves relevant messages from older conversations based on semantic meaning rather than exact keywords, mirroring how humans recall information by association. Requires a [vector database](https://mastra.ai/docs/memory/semantic-recall) and an [embedding model](https://mastra.ai/docs/memory/semantic-recall).
-- [**Observational memory**](https://mastra.ai/docs/memory/observational-memory) - uses background Observer and Reflector agents to maintain a dense observation log that replaces raw message history as it grows, keeping the context window small while preserving long-term memory across conversations.
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory) (Recommended): Uses background agents to maintain a dense observation log that replaces raw message history as it grows. This keeps the context window small while preserving long-term memory.
+- [Working memory](https://mastra.ai/docs/memory/working-memory): Stores persistent, structured user data such as names, preferences, and goals.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): Retrieves relevant past messages based on semantic meaning rather than exact keywords.
 
 If the combined memory exceeds the model's context limit, [memory processors](https://mastra.ai/docs/memory/memory-processors) can filter, trim, or prioritize content so the most relevant information is preserved.
 
-## Getting started
+Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/memory/storage).
 
-Choose a memory option to get started:
+## When to use memory
 
-- [Message history](https://mastra.ai/docs/memory/message-history)
-- [Working memory](https://mastra.ai/docs/memory/working-memory)
-- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall)
-- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
+Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges, recall user preferences or facts from earlier in a session, or build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.
 
-## Storage
+## Quickstart
 
-Before enabling memory, you must first configure a storage adapter. Mastra supports several databases including PostgreSQL, MongoDB, libSQL, and [more](https://mastra.ai/docs/memory/storage).
+1. Install the `@mastra/memory` package.
 
-Storage can be configured at the [instance level](https://mastra.ai/docs/memory/storage) (shared across all agents) or at the [agent level](https://mastra.ai/docs/memory/storage) (dedicated per agent).
+   **npm**:
 
-For semantic recall, you can use a separate vector database like Pinecone alongside your primary storage.
+   ```bash
+   npm install @mastra/memory@latest
+   ```
 
-See the [Storage](https://mastra.ai/docs/memory/storage) documentation for configuration options, supported providers, and examples.
+   **pnpm**:
 
-## Debugging memory
+   ```bash
+   pnpm add @mastra/memory@latest
+   ```
 
-When [tracing](https://mastra.ai/docs/observability/tracing/overview) is enabled, you can inspect exactly which messages the agent uses for context in each request. The trace output shows all memory included in the agent's context window - both recent message history and messages recalled via semantic recall.
+   **Yarn**:
 
-![Trace output showing memory context included in an agent request](https://mastra.ai/_next/image?url=%2Ftracingafter.png\&w=1920\&q=75)
+   ```bash
+   yarn add @mastra/memory@latest
+   ```
 
-This visibility helps you understand why an agent made specific decisions and verify that memory retrieval is working as expected.
+   **Bun**:
 
-## Next steps
+   ```bash
+   bun add @mastra/memory@latest
+   ```
 
-- Learn more about [Storage](https://mastra.ai/docs/memory/storage) providers and configuration options
-- Add [Message history](https://mastra.ai/docs/memory/message-history), [Working memory](https://mastra.ai/docs/memory/working-memory), [Semantic recall](https://mastra.ai/docs/memory/semantic-recall), or [Observational memory](https://mastra.ai/docs/memory/observational-memory)
-- Visit [Memory configuration reference](https://mastra.ai/reference/memory/memory-class) for all available options
+2. Memory **requires** a storage provider to persist message history, including user messages and agent responses.
+
+   For the purposes of this quickstart, use `@mastra/libsql`.
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/libsql@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/libsql@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/libsql@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/libsql@latest
+   ```
+
+   > **Note:** For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/memory/storage) documentation.
+
+3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
+
+   ```typescript
+   import { Mastra } from '@mastra/core'
+   import { LibSQLStore } from '@mastra/libsql'
+
+   export const mastra = new Mastra({
+     storage: new LibSQLStore({
+       id: 'mastra-storage',
+       url: ':memory:',
+     }),
+   })
+   ```
+
+4. Create a `Memory` instance and pass it to the agent's `memory` option.
+
+   ```typescript
+   import { Agent } from '@mastra/core/agent'
+   import { Memory } from '@mastra/memory'
+
+   export const memoryAgent = new Agent({
+     id: 'memory-agent',
+     name: 'Memory Agent',
+     memory: new Memory({
+       options: {
+         lastMessages: 20,
+       },
+     }),
+   })
+   ```
+
+   > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
+
+5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
+
+## Message history
+
+Pass a `memory` object with `resource` and `thread` to track message history.
+
+- `resource`: A stable identifier for the user or entity.
+- `thread`: An ID that isolates a specific conversation or session.
+
+```typescript
+const response = await memoryAgent.generate('Remember my favorite color is blue.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'conversation-123',
+  },
+})
+```
+
+To recall information stored in memory, call the agent with the same `resource` and `thread` values used in the original conversation.
+
+```typescript
+const response = await memoryAgent.generate("What's my favorite color?", {
+  memory: {
+    resource: 'user-123',
+    thread: 'conversation-123',
+  },
+})
+
+// Response: "Your favorite color is blue."
+```
+
+> **Warning:** Each thread has an owner (`resourceId`) that can't be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
+
+To list all threads for a resource, or retrieve a specific thread, [use the memory API directly](https://mastra.ai/docs/memory/message-history).
+
+## Observational Memory
+
+For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: new Memory({
+    options: {
+      observationalMemory: true,
+    },
+  }),
+})
+```
+
+> **Note:** See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
+
+## Memory in multi-agent systems
+
+When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
+
+### How delegation scopes memory
+
+Each delegation creates a fresh `threadId` and a deterministic `resourceId` for the subagent:
+
+- **Thread ID**: Unique per delegation. The subagent starts with a clean message history every time it's called.
+- **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
+- **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance. If the subagent defines its own, that takes precedence.
+
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
+
+> **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Two different subagents under the same supervisor never share a resource ID through delegation.
+
+To go beyond this default isolation, you can share memory between agents by passing matching identifiers when you call them directly.
+
+### Share memory between agents
+
+When you call agents directly (outside the delegation flow), memory sharing is controlled by two identifiers: `resourceId` and `threadId`. Agents that use the same values read and write to the same data. This is useful when agents collaborate on a shared context — for example, a researcher that saves notes and a writer that reads them.
+
+**Resource-scoped sharing** is the most common pattern. [Working memory](https://mastra.ai/docs/memory/working-memory) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) default to `scope: 'resource'`. If two agents share a `resourceId`, they share observations, working memory, and embeddings — even across different threads:
+
+```typescript
+// Both agents share the same resource-scoped memory
+await researcher.generate('Find information about quantum computing.', {
+  memory: { resource: 'project-42', thread: 'research-session' },
+})
+
+await writer.generate('Write a summary from the research notes.', {
+  memory: { resource: 'project-42', thread: 'writing-session' },
+})
+```
+
+Because both calls use `resource: 'project-42'`, the writer can access the researcher's observations, working memory, and semantic embeddings. Each agent still has its own thread, so message histories stay separate.
+
+**Thread-scoped sharing** gives tighter coupling. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses `scope: 'thread'` by default. If two agents use the same `resource` _and_ `thread`, they share the full message history. Each agent sees every message the other has written. This is useful when agents need to build on each other's exact outputs.
+
+## Observability
+
+Enable [Tracing](https://mastra.ai/docs/observability/tracing/overview) to monitor and debug memory in action. Traces show you exactly which messages and observations the agent included in its context for each request, helping you understand agent behavior and verify that memory retrieval is working as expected.
+
+Open [Studio](https://mastra.ai/docs/studio/overview) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.
+
+## Switch memory per request
+
+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
+export type UserTier = {
+  'user-tier': 'enterprise' | 'pro'
+}
+
+const premiumMemory = new Memory()
+const standardMemory = new Memory()
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: ({ requestContext }) => {
+    const userTier = requestContext.get('user-tier') as UserTier['user-tier']
+
+    return userTier === 'enterprise' ? premiumMemory : standardMemory
+  },
+})
+```
+
+> **Note:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+
+## Related
+
+- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
+- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
+- [Request Context](https://mastra.ai/docs/server/request-context)

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

@@ -1,10 +1,10 @@
-# Semantic Recall
+# 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.
 
 > **Watch 📹:** What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
 
-## How Semantic Recall Works
+## How semantic recall works
 
 Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](https://mastra.ai/docs/memory/message-history).
 
@@ -16,26 +16,41 @@ When it's enabled, new messages are used to query a vector DB for semantically s
 
 After getting a response from the LLM, all new messages (user, assistant, and tool calls/results) are inserted into the vector DB to be recalled in later interactions.
 
-## Quick Start
+## Quickstart
 
-Semantic recall is enabled by default, so if you give your agent memory it will be included:
+Semantic recall is disabled by default. To enable it, set `semanticRecall: true` in `options` and provide a `vector` store and `embedder`:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
   id: 'support-agent',
   name: 'SupportAgent',
   instructions: 'You are a helpful support agent.',
-  model: 'openai/gpt-5.1',
-  memory: new Memory(),
+  model: 'openai/gpt-5.4',
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'agent-storage',
+      url: 'file:./local.db',
+    }),
+    vector: new LibSQLVector({
+      id: 'agent-vector',
+      url: 'file:./local.db',
+    }),
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
+  }),
 })
 ```
 
-## Using the recall() Method
+## Using the `recall()` method
 
-While `listMessages` retrieves messages by thread ID with basic pagination, [`recall()`](https://mastra.ai/reference/memory/recall) adds support for **semantic search**. When you need to find messages by meaning rather than just recency, use `recall()` with a `vectorSearchString`:
+While `listMessages` retrieves messages by thread ID with basic pagination, [`recall()`](https://mastra.ai/reference/memory/recall) adds support for **semantic search**. When you need to find messages by meaning rather than recency, use `recall()` with a `vectorSearchString`:
 
 ```typescript
 const memory = await agent.getMemory()
@@ -77,6 +92,9 @@ const agent = new Agent({
       id: 'agent-vector',
       url: 'file:./local.db',
     }),
+    options: {
+      semanticRecall: true,
+    },
   }),
 })
 ```
@@ -139,6 +157,9 @@ import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 const agent = new Agent({
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
   }),
 })
 ```
@@ -147,8 +168,24 @@ Supported embedding models:
 
 - **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
 - **Google**: `gemini-embedding-001`
+- **OpenRouter**: Access embedding models from various providers
 
-The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`).
+```ts
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+
+const agent = new Agent({
+  memory: new Memory({
+    embedder: new ModelRouterEmbeddingModel({
+      providerId: 'openrouter',
+      modelId: 'openai/text-embedding-3-small',
+    }),
+  }),
+})
+```
+
+The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `OPENROUTER_API_KEY`).
 
 ### Using AI SDK Packages
 
@@ -166,7 +203,7 @@ const agent = new Agent({
 })
 ```
 
-### Using FastEmbed (Local)
+### Using FastEmbed (local)
 
 To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
 
@@ -208,7 +245,7 @@ const agent = new Agent({
 })
 ```
 
-## PostgreSQL Index Optimization
+## PostgreSQL index optimization
 
 When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.
 
@@ -246,27 +283,15 @@ const agent = new Agent({
 
 For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg).
 
-## Disabling
+## Disable semantic recall
 
-There is a performance impact to using semantic recall. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
-
-Semantic recall is enabled by default but can be disabled when not needed:
-
-```typescript
-const agent = new Agent({
-  memory: new Memory({
-    options: {
-      semanticRecall: false,
-    },
-  }),
-})
-```
+Semantic recall is disabled by default (`semanticRecall: false`). Each call adds latency because new messages are converted into embeddings and used to query a vector database before the LLM receives them.
 
-You might want to disable semantic recall in scenarios like:
+Keep semantic recall disabled when:
 
-- When message history provides sufficient context for the current conversation.
-- In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.
+- Message history provides sufficient context for the current conversation.
+- You're building performance-sensitive applications, like realtime two-way audio, where embedding and vector query latency is noticeable.
 
-## Viewing Recalled Messages
+## Viewing recalled messages
 
 When tracing is enabled, any messages retrieved via semantic recall will appear in the agent's trace output, alongside recent message history (if configured).

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

@@ -1,6 +1,6 @@
 # Storage
 
-For agents to remember previous interactions, Mastra needs a database. Use a storage adapter for one of the [supported databases](#supported-providers) and pass it to your Mastra instance.
+For agents to remember previous interactions, Mastra needs a storage adapter. Use one of the [supported providers](#supported-providers) and pass it to your Mastra instance.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -14,7 +14,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Sharing the database with Mastra Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
+> **Sharing the database with Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
 >
 > ```typescript
 > url: 'file:/absolute/path/to/your/project/mastra.db'
@@ -24,7 +24,7 @@ export const mastra = new Mastra({
 
 This configures instance-level storage, which all agents share by default. You can also configure [agent-level storage](#agent-level-storage) for isolated data boundaries.
 
-Mastra automatically creates the necessary tables on first interaction. See the [core schema](https://mastra.ai/reference/storage/overview) for details on what gets created, including tables for messages, threads, resources, workflows, traces, and evaluation datasets.
+Mastra automatically initializes the necessary storage structures on first interaction. See [Storage Overview](https://mastra.ai/reference/storage/overview) for domain coverage and the schema used by the built-in database-backed domains.
 
 ## Supported providers
 
@@ -35,7 +35,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [MongoDB](https://mastra.ai/reference/storage/mongodb)
 - [Upstash](https://mastra.ai/reference/storage/upstash)
 - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
-- [Cloudflare Durable Objects](https://mastra.ai/reference/storage/cloudflare)
+- [Cloudflare KV & Durable Objects](https://mastra.ai/reference/storage/cloudflare)
 - [Convex](https://mastra.ai/reference/storage/convex)
 - [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
 - [LanceDB](https://mastra.ai/reference/storage/lance)
@@ -49,7 +49,7 @@ Storage can be configured at the instance level (shared by all agents) or at the
 
 ### Instance-level storage
 
-Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same memory provider:
+Add storage to your Mastra instance so all agents, workflows, observability traces, and scores share the same storage backend:
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -71,7 +71,7 @@ This is useful when all primitives share the same storage backend and have simil
 
 #### Composite storage
 
-[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to set the `memory` domain (and any other [domains](https://mastra.ai/reference/storage/composite) you need) to different storage providers.
+[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to route `memory` and any other [supported domains](https://mastra.ai/reference/storage/composite) to different storage providers.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -100,7 +100,7 @@ This is useful when different types of data have different performance or operat
 
 ### Agent-level storage
 
-Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need data boundaries or compliance requirements:
+Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need to keep data separate or use different providers per agent.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -118,18 +118,16 @@ export const agent = new Agent({
 })
 ```
 
-> **Warning:** [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment) doesn't support agent-level storage.
-
 ## Threads and resources
 
 Mastra organizes conversations using two identifiers:
 
-- **Thread** - a conversation session containing a sequence of messages.
-- **Resource** - the entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
+- **Thread**: A conversation session containing a sequence of messages.
+- **Resource**: The entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
 
 Both identifiers are required for agents to store information:
 
-**Generate**:
+**.generate()**:
 
 ```typescript
 const response = await agent.generate('hello', {
@@ -140,7 +138,7 @@ const response = await agent.generate('hello', {
 })
 ```
 
-**Stream**:
+**.stream()**:
 
 ```typescript
 const stream = await agent.stream('hello', {
@@ -151,7 +149,7 @@ const stream = await agent.stream('hello', {
 })
 ```
 
-> **Note:** [Studio](https://mastra.ai/docs/getting-started/studio) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
+> **Note:** [Studio](https://mastra.ai/docs/studio/overview) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
 
 ### Thread title generation
 
@@ -170,7 +168,7 @@ export const agent = new Agent({
 })
 ```
 
-Title generation runs asynchronously after the agent responds and does not affect response time.
+Title generation runs asynchronously after the agent responds and doesn't affect response time.
 
 To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
 
@@ -180,7 +178,7 @@ export const agent = new Agent({
   memory: new Memory({
     options: {
       generateTitle: {
-        model: 'openai/gpt-4o-mini',
+        model: 'openai/gpt-5-mini',
         instructions: 'Generate a 1 word title',
       },
     },