@mastra/libsql 1.2.0-alpha.0 → 1.3.0-alpha.0

package/dist/docs/{agents/02-networks.md → references/docs-agents-networks.md}

@@ -1,8 +1,6 @@
-> Learn how to coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
-
 # Agent Networks
 
-Agent networks in Mastra coordinate multiple agents, workflows, and tools to handle tasks that aren't clearly defined upfront but can be inferred from the user's message or context. A top-level **routing agent** (a Mastra agent with other agents, workflows, and tools configured) uses an LLM to interpret the request and decide which primitives (sub-agents, workflows, or tools) to call, in what order, and with what data.
+Agent networks in Mastra coordinate multiple agents, workflows, and tools to handle tasks that aren't clearly defined upfront but can be inferred from the user's message or context. A top-level **routing agent** (a Mastra agent with other agents, workflows, and tools configured) uses an LLM to interpret the request and decide which primitives (subagents, workflows, or tools) to call, in what order, and with what data.
 
 ## When to use networks
 
@@ -18,9 +16,9 @@ Mastra agent networks operate using these principles:
 
 ## Creating an agent network
 
-An agent network is built around a top-level routing agent that delegates tasks to agents, workflows, and tools defined in its configuration. Memory is configured on the routing agent using the `memory` option, and `instructions` define the agent's routing behavior.
+An agent network is built around a top-level routing agent that delegates tasks to subagents, workflows, and tools defined in its configuration. Memory is configured on the routing agent using the `memory` option, and `instructions` define the agent's routing behavior.
 
-```typescript {22-23,26,29} title="src/mastra/agents/routing-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -66,9 +64,9 @@ When configuring a Mastra agent network, each primitive (agent, workflow, or too
 
 #### Agent descriptions
 
-Each agent in a network should include a clear `description` that explains what the agent does.
+Each subagent in a network should include a clear `description` that explains what the agent does.
 
-```typescript title="src/mastra/agents/research-agent.ts"
+```typescript
 export const researchAgent = new Agent({
   id: "research-agent",
   name: "Research Agent",
@@ -78,7 +76,7 @@ export const researchAgent = new Agent({
 });
 ```
 
-```typescript title="src/mastra/agents/writing-agent.ts"
+```typescript
 export const writingAgent = new Agent({
   id: "writing-agent",
   name: "Writing Agent",
@@ -92,7 +90,7 @@ export const writingAgent = new Agent({
 
 Workflows in a network should include a `description` to explain their purpose, along with `inputSchema` and `outputSchema` to describe the expected data.
 
-```typescript title="src/mastra/workflows/city-workflow.ts"
+```typescript
 export const cityWorkflow = createWorkflow({
   id: "city-workflow",
   description: `This workflow handles city-specific research tasks.
@@ -112,7 +110,7 @@ export const cityWorkflow = createWorkflow({
 
 Tools in a network should include a `description` to explain their purpose, along with `inputSchema` and `outputSchema` to describe the expected data.
 
-```typescript title="src/mastra/tools/weather-tool.ts"
+```typescript
 export const weatherTool = createTool({
   id: "weather-tool",
   description: ` Retrieves current weather information using the wttr.in API.
@@ -286,7 +284,7 @@ const final = await stream.object;
 
 ## Related
 
-- [Agent Memory](./agent-memory)
-- [Workflows Overview](../workflows/overview)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
+- [Workflows Overview](https://mastra.ai/docs/workflows/overview)
 - [Request Context](https://mastra.ai/docs/server/request-context)
 - [Supervisor example](https://github.com/mastra-ai/mastra/tree/main/examples/supervisor-agent)

package/dist/docs/{memory/06-memory-processors.md → references/docs-memory-memory-processors.md}

@@ -1,5 +1,3 @@
-> Learn how to use memory processors in Mastra to filter, trim, and transform messages before they
-
 # Memory Processors
 
 Memory processors transform and filter messages as they pass through an agent with memory enabled. They manage context window limits, remove unnecessary content, and optimize the information sent to the language model.
@@ -200,7 +198,7 @@ Understanding the execution order is important when combining guardrails with me
 
 ### Input Processors
 
-```
+```text
 [Memory Processors] → [Your inputProcessors]
 ```
 
@@ -211,7 +209,7 @@ This means memory loads message history before your processors can validate or f
 
 ### Output Processors
 
-```
+```text
 [Your outputProcessors] → [Memory Processors]
 ```
 
@@ -302,10 +300,10 @@ const agent = new Agent({
 
 ### Summary
 
-| Guardrail Type | When it runs | If it aborts |
-| -------------- | ------------ | ------------ |
-| Input | After memory loads history | LLM not called, nothing saved |
-| Output | Before memory saves | Nothing saved to storage |
+| Guardrail Type | When it runs               | If it aborts                  |
+| -------------- | -------------------------- | ----------------------------- |
+| Input          | After memory loads history | LLM not called, nothing saved |
+| Output         | Before memory saves        | Nothing saved to storage      |
 
 Both scenarios are safe - guardrails prevent inappropriate content from being persisted to memory
 

package/dist/docs/{memory/03-message-history.md → references/docs-memory-message-history.md}

@@ -1,25 +1,42 @@
-> Learn how to configure message history in Mastra to store recent messages from the current conversation.
-
 # Message History
 
-Message history is the most basic and important form of memory. It gives the LLM a view of recent messages in the context window, enabling your agent to reference earlier exchanges and respond coherently. 
+Message history is the most basic and important form of memory. It gives the LLM a view of recent messages in the context window, enabling your agent to reference earlier exchanges and respond coherently.
 
 You can also retrieve message history to display past conversations in your UI.
 
-> **Note:**
-Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage#threads-and-resources) for more detail.
+> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage) for more detail.
 
 ## Getting started
 
-Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage#supported-providers) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
+Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
+
+**npm**:
 
-```bash npm2yarn
+```bash
 npm install @mastra/memory@latest @mastra/libsql@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/memory@latest @mastra/libsql@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/memory@latest @mastra/libsql@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/memory@latest @mastra/libsql@latest
+```
+
 Message history requires a storage adapter to persist conversations. Configure storage on your Mastra instance if you haven't already:
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
@@ -33,7 +50,7 @@ export const mastra = new Mastra({
 
 Give your agent a `Memory`:
 
-```typescript title="src/mastra/agents/your-agent.ts"
+```typescript
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 
@@ -49,7 +66,7 @@ export const agent = new Agent({
 
 When you call the agent, messages are automatically saved to the database. You can specify a `threadId`, `resourceId`, and optional `metadata`:
 
-  **generate:**
+**Generate**:
 
 ```typescript
 await agent.generate("Hello", {
@@ -64,8 +81,7 @@ await agent.generate("Hello", {
 });
 ```
 
-  
-  **stream:**
+**Stream**:
 
 ```typescript
 await agent.stream("Hello", {
@@ -80,11 +96,7 @@ await agent.stream("Hello", {
 });
 ```
 
-  
-
-> **Note:**
-
-Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class). 
+> **Info:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
 
 There are two ways to use this history:
 
@@ -106,8 +118,7 @@ The `Memory` instance gives you access to functions for listing threads, recalli
 
 Use these methods to fetch threads and messages for displaying conversation history in your UI or for custom memory retrieval logic.
 
-> **Note:**
-The memory system does not enforce access control. Before running any query, verify in your application logic that the current user is authorized to access the `resourceId` being queried.
+> **Warning:** The memory system does not enforce access control. Before running any query, verify in your application logic that the current user is authorized to access the `resourceId` being queried.
 
 ### Threads
 
@@ -240,7 +251,7 @@ const { thread, clonedMessages } = await memory.cloneThread({
 });
 ```
 
-You can filter which messages get cloned (by count or date range), specify custom thread IDs, and use utility methods to inspect clone relationships. 
+You can filter which messages get cloned (by count or date range), specify custom thread IDs, and use utility methods to inspect clone relationships.
 
 See [`cloneThread()`](https://mastra.ai/reference/memory/cloneThread) and [clone utilities](https://mastra.ai/reference/memory/clone-utilities) for the full API.
 

package/dist/docs/{memory/01-overview.md → references/docs-memory-overview.md}

@@ -1,14 +1,13 @@
-> Learn how Mastra
-
 # Memory
 
 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 three complementary memory types:
+Mastra supports four complementary memory types:
 
 - [**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#storage-configuration) and an [embedding model](https://mastra.ai/docs/memory/semantic-recall#embedder-configuration).
+- [**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.
 
 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.
 
@@ -19,12 +18,13 @@ Choose a memory option to get started:
 - [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)
 
 ## Storage
 
-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#supported-providers).
+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).
 
-Storage can be configured at the [instance level](https://mastra.ai/docs/memory/storage#instance-level-storage) (shared across all agents) or at the [agent level](https://mastra.ai/docs/memory/storage#agent-level-storage) (dedicated per agent).
+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).
 
 For semantic recall, you can use a separate vector database like Pinecone alongside your primary storage.
 
@@ -34,12 +34,12 @@ See the [Storage](https://mastra.ai/docs/memory/storage) documentation for confi
 
 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.
 
-![Trace output showing memory context included in an agent request](https://mastra.ai/_next/image?url=%2Ftracingafter.png&w=1920&q=75)
+![Trace output showing memory context included in an agent request](https://mastra.ai/_next/image?url=%2Ftracingafter.png\&w=1920\&q=75)
 
 This visibility helps you understand why an agent made specific decisions and verify that memory retrieval is working as expected.
 
 ## Next steps
 
 - 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), or [Semantic recall](https://mastra.ai/docs/memory/semantic-recall)
+- 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

package/dist/docs/{memory/05-semantic-recall.md → references/docs-memory-semantic-recall.md}

@@ -1,20 +1,16 @@
-> Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
-
 # 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)
+> **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
 
-Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](./message-history).
+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).
 
 It uses vector embeddings of messages for similarity search, integrates with various vector stores, and has configurable context windows around retrieved messages.
 
-![Diagram showing Mastra Memory semantic recall](/img/semantic-recall.png)
+![Diagram showing Mastra Memory semantic recall](/assets/images/semantic-recall-fd7b9336a6d0d18019216cb6d3dbe710.png)
 
 When it's enabled, new messages are used to query a vector DB for semantically similar messages.
 
@@ -24,7 +20,7 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 Semantic recall is enabled by default, so if you give your agent memory it will be included:
 
-```typescript {9}
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 
@@ -64,7 +60,7 @@ const { messages: relevantMessages } = await memory!.recall({
 
 Semantic recall relies on a [storage and vector db](https://mastra.ai/reference/memory/memory-class) to store messages and their embeddings.
 
-```ts {8-16}
+```ts
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
@@ -113,7 +109,7 @@ The three main parameters that control semantic recall behavior are:
 2. **messageRange**: How much surrounding context to include with each match
 3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
 
-```typescript {5-7}
+```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {
@@ -135,7 +131,7 @@ Semantic recall relies on an [embedding model](https://mastra.ai/reference/memor
 
 The simplest way is to use a `provider/model` string with autocomplete support:
 
-```ts {7}
+```ts
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
@@ -158,7 +154,7 @@ The model router automatically handles API key detection from environment variab
 
 You can also use AI SDK embedding models directly:
 
-```ts {2,7}
+```ts
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
@@ -174,13 +170,33 @@ const agent = new Agent({
 
 To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
 
-```bash npm2yarn
+**npm**:
+
+```bash
 npm install @mastra/fastembed@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/fastembed@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/fastembed@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/fastembed@latest
+```
+
 Then configure it in your memory:
 
-```ts {3,7}
+```ts
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { fastembed } from "@mastra/fastembed";
@@ -198,7 +214,7 @@ When using PostgreSQL as your vector store, you can optimize semantic recall per
 
 PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
 
-```typescript {18-23}
+```typescript
 import { Memory } from "@mastra/memory";
 import { PgStore, PgVector } from "@mastra/pg";
 
@@ -228,7 +244,7 @@ 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#index-configuration-guide).
+For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg).
 
 ## Disabling
 
@@ -236,7 +252,7 @@ There is a performance impact to using semantic recall. New messages are convert
 
 Semantic recall is enabled by default but can be disabled when not needed:
 
-```typescript {4}
+```typescript
 const agent = new Agent({
   memory: new Memory({
     options: {

package/dist/docs/{memory/02-storage.md → references/docs-memory-storage.md}

@@ -1,10 +1,8 @@
-> Configure storage for Mastra
-
 # 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 database. Use a storage adapter for one of the [supported databases](#supported-providers) and pass it to your Mastra instance.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
@@ -16,18 +14,17 @@ 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:
-
-```typescript
-url: "file:/absolute/path/to/your/project/mastra.db"
-```
-
-Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
+> **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:
+>
+> ```typescript
+> url: "file:/absolute/path/to/your/project/mastra.db"
+> ```
+>
+> Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
 
 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#core-schema) for details on what gets created, including tables for messages, threads, resources, workflows, traces, and evaluation datasets.
+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.
 
 ## Supported providers
 
@@ -44,8 +41,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [LanceDB](https://mastra.ai/reference/storage/lance)
 - [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
 
-> **Note:**
-libSQL is the easiest way to get started because it doesn’t require running a separate database server.
+> **Tip:** libSQL is the easiest way to get started because it doesn’t require running a separate database server.
 
 ## Configuration scope
 
@@ -55,7 +51,7 @@ Storage can be configured at the instance level (shared by all agents) or at the
 
 Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same memory provider:
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { PostgresStore } from "@mastra/pg";
 
@@ -75,9 +71,9 @@ 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#storage-domains) 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 set the `memory` domain (and any other [domains](https://mastra.ai/reference/storage/composite) you need) to different storage providers.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryLibSQL } from "@mastra/libsql";
@@ -88,7 +84,6 @@ export const mastra = new Mastra({
   storage: new MastraCompositeStore({
     id: "composite",
     domains: {
-      // highlight-next-line
       memory: new MemoryLibSQL({ url: "file:./memory.db" }),
       workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
       observability: new ObservabilityStorageClickhouse({
@@ -107,7 +102,7 @@ This is useful when different types of data have different performance or operat
 
 Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need data boundaries or compliance requirements:
 
-```typescript title="src/mastra/agents/your-agent.ts"
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { PostgresStore } from "@mastra/pg";
@@ -123,19 +118,18 @@ export const agent = new Agent({
 });
 ```
 
-> **Note:**
-[Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment#using-mastra-cloud-store) doesn't support agent-level storage.
+> **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: 
+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.
 
 Both identifiers are required for agents to store information:
 
-  **generate:**
+**Generate**:
 
 ```typescript
 const response = await agent.generate("hello", {
@@ -146,8 +140,7 @@ const response = await agent.generate("hello", {
 });
 ```
 
-  
-  **stream:**
+**Stream**:
 
 ```typescript
 const stream = await agent.stream("hello", {
@@ -158,10 +151,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/getting-started/studio) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
 
 ### Thread title generation
 
@@ -169,7 +159,7 @@ Mastra can automatically generate descriptive thread titles based on the user's
 
 Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
 
-```typescript title="src/mastra/agents/my-agent.ts"
+```typescript
 export const agent = new Agent({
   id: "agent",
   memory: new Memory({
@@ -182,9 +172,9 @@ export const agent = new Agent({
 
 Title generation runs asynchronously after the agent responds and does not affect response time.
 
-To optimize cost or behavior, provide a smaller [`model`](/models) and custom `instructions`:
+To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
 
-```typescript title="src/mastra/agents/my-agent.ts"
+```typescript
 export const agent = new Agent({
   id: "agent",
   memory: new Memory({
@@ -206,17 +196,17 @@ Semantic recall has different storage requirements - it needs a vector database
 
 Some storage providers enforce record size limits that base64-encoded file attachments (such as images) can exceed:
 
-| Provider | Record size limit |
-| -------- | ----------------- |
-| [DynamoDB](https://mastra.ai/reference/storage/dynamodb) | 400 KB |
-| [Convex](https://mastra.ai/reference/storage/convex) | 1 MiB |
-| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB |
+| Provider                                                           | Record size limit |
+| ------------------------------------------------------------------ | ----------------- |
+| [DynamoDB](https://mastra.ai/reference/storage/dynamodb)           | 400 KB            |
+| [Convex](https://mastra.ai/reference/storage/convex)               | 1 MiB             |
+| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB             |
 
 PostgreSQL, MongoDB, and libSQL have higher limits and are generally unaffected.
 
 To avoid this, use an input processor to upload attachments to external storage (S3, R2, GCS, [Convex file storage](https://docs.convex.dev/file-storage), etc.) and replace them with URL references before persistence.
 
-```typescript title="src/mastra/processors/attachment-uploader.ts"
+```typescript
 import type { Processor } from "@mastra/core/processors";
 import type { MastraDBMessage } from "@mastra/core/memory";