@mastra/pg 1.2.0 → 1.3.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # @mastra/pg
 
+## 1.3.0-alpha.1
+
+### Patch Changes
+
+- Fixed observational memory progress bars resetting to zero after agent responses finish. The messages and observations sidebar bars now retain their values on stream completion, cancellation, and page reload. Also added a buffer-status endpoint so buffering badges resolve with accurate token counts instead of spinning forever when buffering outlives the stream. ([#12934](https://github.com/mastra-ai/mastra/pull/12934))
+
+- Updated dependencies [[`b31c922`](https://github.com/mastra-ai/mastra/commit/b31c922215b513791d98feaea1b98784aa00803a)]:
+  - @mastra/core@1.3.0-alpha.2
+
+## 1.3.0-alpha.0
+
+### Minor Changes
+
+- **Updated storage adapters for generic storage domain API** ([#12846](https://github.com/mastra-ai/mastra/pull/12846))
+
+  All storage adapters now implement the unified `VersionedStorageDomain` method names. Entity-specific methods (`createAgent`, `getAgentById`, `deleteAgent`, etc.) have been replaced with generic equivalents (`create`, `getById`, `delete`, etc.) across agents, prompt blocks, and scorer definitions domains.
+
+  Added `scorer-definitions` domain support to all adapters.
+
+  **Before:**
+
+  ```ts
+  const store = storage.getStore('agents');
+  await store.createAgent({ agent: input });
+  await store.getAgentById({ id: 'abc' });
+  await store.deleteAgent({ id: 'abc' });
+  ```
+
+  **After:**
+
+  ```ts
+  const store = storage.getStore('agents');
+  await store.create({ agent: input });
+  await store.getById('abc');
+  await store.delete('abc');
+  ```
+
+### Patch Changes
+
+- Fixed issues with stored agents ([#12790](https://github.com/mastra-ai/mastra/pull/12790))
+
+- Fixed cross-schema constraint checks in multi-schema PostgreSQL setups so tables and indexes are created in the intended schema. Single-schema (default) setups are unaffected. ([#12868](https://github.com/mastra-ai/mastra/pull/12868))
+
+- **Async buffering for observational memory is now enabled by default.** Observations are pre-computed in the background as conversations grow — when the context window fills up, buffered observations activate instantly with no blocking LLM call. This keeps agents responsive during long conversations. ([#12891](https://github.com/mastra-ai/mastra/pull/12891))
+
+  **Default settings:**
+  - `observation.bufferTokens: 0.2` — buffer every 20% of `messageTokens` (~6k tokens with the default 30k threshold)
+  - `observation.bufferActivation: 0.8` — on activation, retain 20% of the message window
+  - `reflection.bufferActivation: 0.5` — start background reflection at 50% of the observation threshold
+
+  **Disabling async buffering:**
+
+  Set `observation.bufferTokens: false` to disable async buffering for both observations and reflections:
+
+  ```ts
+  const memory = new Memory({
+    options: {
+      observationalMemory: {
+        model: 'google/gemini-2.5-flash',
+        observation: {
+          bufferTokens: false,
+        },
+      },
+    },
+  });
+  ```
+
+  **Model is now required** when passing an observational memory config object. Use `observationalMemory: true` for the default (google/gemini-2.5-flash), or set a model explicitly:
+
+  ```ts
+  // Uses default model (google/gemini-2.5-flash)
+  observationalMemory: true
+
+  // Explicit model
+  observationalMemory: {
+    model: "google/gemini-2.5-flash",
+  }
+  ```
+
+  **`shareTokenBudget` requires `bufferTokens: false`** (temporary limitation). If you use `shareTokenBudget: true`, you must explicitly disable async buffering:
+
+  ```ts
+  observationalMemory: {
+    model: "google/gemini-2.5-flash",
+    shareTokenBudget: true,
+    observation: { bufferTokens: false },
+  }
+  ```
+
+  **New streaming event:** `data-om-status` replaces `data-om-progress` with a structured status object containing active window usage, buffered observation/reflection state, and projected activation impact.
+
+  **Buffering markers:** New `data-om-buffering-start`, `data-om-buffering-end`, and `data-om-buffering-failed` streaming events for UI feedback during background operations.
+
+- Fixed PostgreSQL constraint names exceeding 63-byte identifier limit. Schema-prefixed constraint names are now truncated to fit within PostgreSQL's identifier length limit, preventing "relation already exists" errors when restarting the dev server with schema names longer than 13 characters. Fixes #12679. ([#12687](https://github.com/mastra-ai/mastra/pull/12687))
+
+- Added prompt block storage implementations. Each store supports full CRUD for prompt blocks and their versions, including JSON serialization for rules and metadata. Also updated agent instructions serialization to support the new `AgentInstructionBlock` array format alongside plain strings. ([#12776](https://github.com/mastra-ai/mastra/pull/12776))
+
+- Updated dependencies [[`717ffab`](https://github.com/mastra-ai/mastra/commit/717ffab42cfd58ff723b5c19ada4939997773004), [`e4b6dab`](https://github.com/mastra-ai/mastra/commit/e4b6dab171c5960e340b3ea3ea6da8d64d2b8672), [`5719fa8`](https://github.com/mastra-ai/mastra/commit/5719fa8880e86e8affe698ec4b3807c7e0e0a06f), [`83cda45`](https://github.com/mastra-ai/mastra/commit/83cda4523e588558466892bff8f80f631a36945a), [`11804ad`](https://github.com/mastra-ai/mastra/commit/11804adf1d6be46ebe216be40a43b39bb8b397d7), [`aa95f95`](https://github.com/mastra-ai/mastra/commit/aa95f958b186ae5c9f4219c88e268f5565c277a2), [`f5501ae`](https://github.com/mastra-ai/mastra/commit/f5501aedb0a11106c7db7e480d6eaf3971b7bda8), [`44573af`](https://github.com/mastra-ai/mastra/commit/44573afad0a4bc86f627d6cbc0207961cdcb3bc3), [`00e3861`](https://github.com/mastra-ai/mastra/commit/00e3861863fbfee78faeb1ebbdc7c0223aae13ff), [`7bfbc52`](https://github.com/mastra-ai/mastra/commit/7bfbc52a8604feb0fff2c0a082c13c0c2a3df1a2), [`1445994`](https://github.com/mastra-ai/mastra/commit/1445994aee19c9334a6a101cf7bd80ca7ed4d186), [`61f44a2`](https://github.com/mastra-ai/mastra/commit/61f44a26861c89e364f367ff40825bdb7f19df55), [`37145d2`](https://github.com/mastra-ai/mastra/commit/37145d25f99dc31f1a9105576e5452609843ce32), [`fdad759`](https://github.com/mastra-ai/mastra/commit/fdad75939ff008b27625f5ec0ce9c6915d99d9ec), [`e4569c5`](https://github.com/mastra-ai/mastra/commit/e4569c589e00c4061a686c9eb85afe1b7050b0a8), [`7309a85`](https://github.com/mastra-ai/mastra/commit/7309a85427281a8be23f4fb80ca52e18eaffd596), [`99424f6`](https://github.com/mastra-ai/mastra/commit/99424f6862ffb679c4ec6765501486034754a4c2), [`44eb452`](https://github.com/mastra-ai/mastra/commit/44eb4529b10603c279688318bebf3048543a1d61), [`6c40593`](https://github.com/mastra-ai/mastra/commit/6c40593d6d2b1b68b0c45d1a3a4c6ac5ecac3937), [`8c1135d`](https://github.com/mastra-ai/mastra/commit/8c1135dfb91b057283eae7ee11f9ec28753cc64f), [`dd39e54`](https://github.com/mastra-ai/mastra/commit/dd39e54ea34532c995b33bee6e0e808bf41a7341), [`b6fad9a`](https://github.com/mastra-ai/mastra/commit/b6fad9a602182b1cc0df47cd8c55004fa829ad61), [`4129c07`](https://github.com/mastra-ai/mastra/commit/4129c073349b5a66643fd8136ebfe9d7097cf793), [`5b930ab`](https://github.com/mastra-ai/mastra/commit/5b930aba1834d9898e8460a49d15106f31ac7c8d), [`4be93d0`](https://github.com/mastra-ai/mastra/commit/4be93d09d68e20aaf0ea3f210749422719618b5f), [`047635c`](https://github.com/mastra-ai/mastra/commit/047635ccd7861d726c62d135560c0022a5490aec), [`8c90ff4`](https://github.com/mastra-ai/mastra/commit/8c90ff4d3414e7f2a2d216ea91274644f7b29133), [`ed232d1`](https://github.com/mastra-ai/mastra/commit/ed232d1583f403925dc5ae45f7bee948cf2a182b), [`3891795`](https://github.com/mastra-ai/mastra/commit/38917953518eb4154a984ee36e6ededdcfe80f72), [`4f955b2`](https://github.com/mastra-ai/mastra/commit/4f955b20c7f66ed282ee1fd8709696fa64c4f19d), [`55a4c90`](https://github.com/mastra-ai/mastra/commit/55a4c9044ac7454349b9f6aeba0bbab5ee65d10f)]:
+  - @mastra/core@1.3.0-alpha.1
+
 ## 1.2.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -1,37 +1,40 @@
 ---
-name: mastra-pg-docs
-description: Documentation for @mastra/pg. Includes links to type definitions and readable implementation code in dist/.
+name: mastra-pg
+description: Documentation for @mastra/pg. Use when working with @mastra/pg APIs, configuration, or implementation.
+metadata:
+  package: "@mastra/pg"
+  version: "1.3.0-alpha.1"
 ---
 
-# @mastra/pg Documentation
+## When to use
 
-> **Version**: 1.2.0
-> **Package**: @mastra/pg
+Use this skill whenever you are working with @mastra/pg to obtain the domain-specific knowledge.
 
-## Quick Navigation
+## How to use
 
-Use SOURCE_MAP.json to find any export:
+Read the individual reference documents for detailed explanations and code examples.
 
-```bash
-cat docs/SOURCE_MAP.json
-```
+### Docs
 
-Each export maps to:
-- **types**: `.d.ts` file with JSDoc and API signatures
-- **implementation**: `.js` chunk file with readable source
-- **docs**: Conceptual documentation in `docs/`
+- [Semantic Recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
+- [Storage](references/docs-memory-storage.md) - Configure storage for Mastra's memory system to persist conversations, workflows, and traces.
+- [Working Memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
+- [RAG (Retrieval-Augmented Generation) in Mastra](references/docs-rag-overview.md) - Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
+- [Retrieval, Semantic Search, Reranking](references/docs-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
+- [Storing Embeddings in A Vector Database](references/docs-rag-vector-databases.md) - Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
 
-## Top Exports
+### Reference
 
+- [Reference: Memory Class](references/reference-memory-memory-class.md) - Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage.
+- [Reference: Message History Processor](references/reference-processors-message-history-processor.md) - Documentation for the MessageHistory processor in Mastra, which handles retrieval and persistence of conversation history.
+- [Reference: Semantic Recall Processor](references/reference-processors-semantic-recall-processor.md) - Documentation for the SemanticRecall processor in Mastra, which enables semantic search over conversation history using vector embeddings.
+- [Reference: Working Memory Processor](references/reference-processors-working-memory-processor.md) - Documentation for the WorkingMemory processor in Mastra, which injects persistent user/context data as system instructions.
+- [Reference: Metadata Filters](references/reference-rag-metadata-filters.md) - Documentation for metadata filtering capabilities in Mastra, which allow for precise querying of vector search results across different vector stores.
+- [Reference: Composite Storage](references/reference-storage-composite.md) - Documentation for combining multiple storage backends in Mastra.
+- [Reference: DynamoDB Storage](references/reference-storage-dynamodb.md) - Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.
+- [Reference: PostgreSQL Storage](references/reference-storage-postgresql.md) - Documentation for the PostgreSQL storage implementation in Mastra.
+- [Reference: createVectorQueryTool()](references/reference-tools-vector-query-tool.md) - Documentation for the Vector Query Tool in Mastra, which facilitates semantic search over vector stores with filtering and reranking capabilities.
+- [Reference: PG Vector Store](references/reference-vectors-pg.md) - Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
 
 
-See SOURCE_MAP.json for the complete list.
-
-## Available Topics
-
-- [Memory](memory/) - 4 file(s)
-- [Processors](processors/) - 3 file(s)
-- [Rag](rag/) - 4 file(s)
-- [Storage](storage/) - 3 file(s)
-- [Tools](tools/) - 1 file(s)
-- [Vectors](vectors/) - 1 file(s)
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/{SOURCE_MAP.json → assets/SOURCE_MAP.json}

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.3.0-alpha.1",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/docs/{memory/03-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/01-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";
 

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

@@ -1,8 +1,6 @@
-> Learn how to configure working memory in Mastra to store persistent user data, preferences.
-
 # Working Memory
 
-While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](./semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
+While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
 
 Think of it as the agent's active thoughts or scratchpad – the key information they keep available about the user or task. It's similar to how a person would naturally remember someone's name, preferences, or important details during a conversation.
 
@@ -19,7 +17,7 @@ Working memory can persist at two different scopes:
 
 Here's a minimal example of setting up an agent with working memory:
 
-```typescript {11-15}
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 
@@ -43,7 +41,7 @@ const agent = new Agent({
 
 Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
 
-<YouTube id="UMy_JHLf1n8" />
+[YouTube video player](https://www.youtube-nocookie.com/embed/UMy_JHLf1n8)
 
 ## Memory Persistence Scopes
 
@@ -136,7 +134,7 @@ Templates guide the agent on what information to track and update in working mem
 
 Here's an example of a custom template. In this example the agent will store the users name, location, timezone, etc as soon as the user sends a message containing any of the info:
 
-```typescript {5-28}
+```typescript
 const memory = new Memory({
   options: {
     workingMemory: {
@@ -172,19 +170,13 @@ const memory = new Memory({
 
 ## Designing Effective Templates
 
-A well-structured template keeps the information easy for the agent to parse and update. Treat the
-template as a short form that you want the assistant to keep up to date.
+A well-structured template keeps the information easy for the agent to parse and update. Treat the template as a short form that you want the assistant to keep up to date.
 
-- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example
-  `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
-- **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy
-  updates. Stick to Title Case or lower case for headings and bullet labels.
-- **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM
-  fill in the correct spots.
-- **Abbreviate very long values.** If you only need a short form, include guidance like
-  `- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
-- **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of
-  the template directly in the agent's `instructions` field.
+- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
+- **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy updates. Stick to Title Case or lower case for headings and bullet labels.
+- **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM fill in the correct spots.
+- **Abbreviate very long values.** If you only need a short form, include guidance like `- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
+- **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of the template directly in the agent's `instructions` field.
 
 ### Alternative Template Styles
 
@@ -281,8 +273,7 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 
 ## Example: Multi-step Retention
 
-Below is a simplified view of how the `User Profile` template updates across a short user
-conversation:
+Below is a simplified view of how the `User Profile` template updates across a short user conversation:
 
 ```nohighlight
 # User Profile
@@ -308,11 +299,9 @@ conversation:
 - Timezone: CET
 ```
 
-The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information
-again because it has been stored in working memory.
+The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information again because it has been stored in working memory.
 
-If your agent is not properly updating working memory when you expect it to, you can add system
-instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
+If your agent is not properly updating working memory when you expect it to, you can add system instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
 
 ## Setting Initial Working Memory
 
@@ -322,7 +311,7 @@ While agents typically update working memory through the `updateWorkingMemory` t
 
 When creating a thread, you can provide initial working memory through the metadata's `workingMemory` key:
 
-```typescript title="src/app/medical-consultation.ts"
+```typescript
 // Create a thread with initial working memory
 const thread = await memory.createThread({
   threadId: "thread-123",
@@ -353,7 +342,7 @@ await agent.generate("What's my blood type?", {
 
 You can also update an existing thread's working memory:
 
-```typescript title="src/app/medical-consultation.ts"
+```typescript
 // Update thread metadata to add/modify working memory
 await memory.updateThread({
   id: "thread-123",
@@ -375,7 +364,7 @@ await memory.updateThread({
 
 Alternatively, use the `updateWorkingMemory` method directly:
 
-```typescript title="src/app/medical-consultation.ts"
+```typescript
 await memory.updateWorkingMemory({
   threadId: "thread-123",
   resourceId: "user-456", // Required for resource-scoped memory

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

@@ -1,5 +1,3 @@
-> Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
-
 # RAG (Retrieval-Augmented Generation) in Mastra
 
 RAG in Mastra helps you enhance LLM outputs by incorporating relevant context from your own data sources, improving accuracy and grounding responses in real information.
@@ -63,11 +61,11 @@ This example shows the essentials: initialize a document, create chunks, generat
 
 ## Document Processing
 
-The basic building block of RAG is document processing. Documents can be chunked using various strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](./chunking-and-embedding).
+The basic building block of RAG is document processing. Documents can be chunked using various strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/docs/rag/chunking-and-embedding).
 
 ## Vector Storage
 
-Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](./vector-databases).
+Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/docs/rag/vector-databases).
 
 ## More resources