@mastra/libsql 1.15.1 → 1.16.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @mastra/libsql
 
+## 1.16.0-alpha.1
+
+### Minor Changes
+
+- Added atomic caller-defined dataset IDs for idempotent dataset creation across built-in storage adapters. Supplying `id` to `mastra.datasets.create()` now creates the dataset once and resolves compatible retries to the persisted record; incompatible immutable identity fields throw `DATASET_ID_CONFLICT`. ([#19370](https://github.com/mastra-ai/mastra/pull/19370))
+
+- Added caller-defined dataset item identities for safe retries across all dataset storage adapters. ([#19384](https://github.com/mastra-ai/mastra/pull/19384))
+
+  Dataset items can now include an `externalId` when calling `addItem` or `addItems`:
+
+  ```ts
+  await dataset.addItem({
+    externalId: 'source-item-123',
+    input: { prompt: 'Hello' },
+  });
+  ```
+
+  Retrying with the same identity and payload returns the existing item. Reusing an identity with different content returns a typed conflict, including during concurrent writes. Updates and deletes preserve the identity, Spanner retries transactions without changing the outcome, and MySQL batch writes now preserve every supported dataset item field.
+
+### Patch Changes
+
+- Raised the `@mastra/core` peer dependency floor to `>=1.51.0-0` so the dataset item identity helpers used by the storage adapters are available at runtime. ([#19384](https://github.com/mastra-ai/mastra/pull/19384))
+
+- Updated dependencies [[`a99eae8`](https://github.com/mastra-ai/mastra/commit/a99eae8908e500c1b2d12f9d277be616b98617a5), [`fd13f8e`](https://github.com/mastra-ai/mastra/commit/fd13f8e21990f9904c3eedba3a626bb4a929cdb8), [`f703f87`](https://github.com/mastra-ai/mastra/commit/f703f878de072d51fda557f9c50867d8252bef05), [`0ad646f`](https://github.com/mastra-ai/mastra/commit/0ad646f71a530f2454664299e5e01bfd13fa12e5)]:
+  - @mastra/core@1.51.0-alpha.13
+
+## 1.16.0-alpha.0
+
+### Minor Changes
+
+- Added `LibSQLVector.close()` to release the underlying libsql client. For local file databases it checkpoints the WAL and switches back to `journal_mode=DELETE` before closing (mirroring `LibSQLStore.close()`), so the `-wal`/`-shm` sidecar files and OS handles are released promptly. Safe to call more than once. ([#19059](https://github.com/mastra-ai/mastra/pull/19059))
+
+### Patch Changes
+
+- Updated dependencies [[`e955965`](https://github.com/mastra-ai/mastra/commit/e955965dce575a903e37cf054d28ea99aa48785e), [`860ef7e`](https://github.com/mastra-ai/mastra/commit/860ef7e77d92b63469cbe5857aa1e626197e43e9), [`17e818c`](https://github.com/mastra-ai/mastra/commit/17e818c51a958ba90641b1a959dc38faf8c034e9), [`4451dfe`](https://github.com/mastra-ai/mastra/commit/4451dfe857428e7abcc0261a507a2e186dae6d47), [`1d39058`](https://github.com/mastra-ai/mastra/commit/1d39058e548efd691799985d5c8af2737f1c3bd2)]:
+  - @mastra/core@1.51.0-alpha.2
+
 ## 1.15.1
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-libsql
 description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
 metadata:
   package: "@mastra/libsql"
-  version: "1.15.1"
+  version: "1.16.0-alpha.1"
 ---
 
 ## When to use
@@ -25,9 +25,9 @@ Read the individual reference documents for detailed explanations and code examp
 - [Multi-user threads](references/docs-memory-multi-user-threads.md) - Share one Mastra thread between multiple users by carrying speaker identity in the message body.
 - [Memory overview](references/docs-memory-overview.md) - Learn how Mastra's memory system works with working memory, message history, semantic recall, and observational memory.
 - [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 to persist conversations and other runtime state.
 - [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
 - [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.
+- [Storage overview](references/docs-storage-overview.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
 - [Snapshots](references/docs-workflows-snapshots.md) - Learn how to save and resume workflow execution state with snapshots in Mastra
 
 ### Guides
@@ -39,6 +39,8 @@ Read the individual reference documents for detailed explanations and code examp
 - [Reference: Mastra.getMemory()](references/reference-core-getMemory.md) - Documentation for the `Mastra.getMemory()` method in Mastra, which retrieves a registered memory instance by its registry key.
 - [Reference: Mastra.listMemory()](references/reference-core-listMemory.md) - Documentation for the `Mastra.listMemory()` method in Mastra, which returns all registered memory instances.
 - [Reference: Mastra class](references/reference-core-mastra-class.md) - Documentation for the `Mastra` class in Mastra, the core entry point for managing agents, workflows, MCP servers, and server endpoints.
+- [Memory](references/reference-file-based-agents-memory.md) - Give a file-based agent persistent memory with a memory.ts module.
+- [Storage](references/reference-file-based-agents-storage.md) - Set the default Mastra store by file convention with storage.ts.
 - [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: 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.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.15.1",
+  "version": "1.16.0-alpha.1",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-agent-builder-overview.md

@@ -4,10 +4,10 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
-[YouTube video player](https://www.youtube-nocookie.com/embed/AbdgIu4Z07I)
-
 The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
 
+> **📹 Watch:** Watch [Mastra Agent Builder overview](https://www.youtube.com/watch?v=AbdgIu4Z07I) to see how teams create and configure agents from the UI.
+
 - [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.
 - [**Model policy**](https://mastra.ai/docs/agent-builder/model-policy): Restrict which providers and models the Builder exposes, and pin a default.
 - [**Memory**](https://mastra.ai/docs/agent-builder/memory): Configure the default memory shape for every Builder-created agent.
@@ -108,4 +108,5 @@ Omitting the `builder` field has the same effect.
 
 - [Configuration](https://mastra.ai/docs/agent-builder/configuration): Toggle Builder surfaces and pin defaults for new agents.
 - [Access control](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder with authentication and role-based access control.
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Replace local development primitives with production-ready storage, filesystems, and sandboxes.
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Replace local development primitives with production-ready storage, filesystems, and sandboxes.
+- 📹 [Mastra Agent Builder workshop](https://www.youtube.com/watch?v=p2p_wb-rUPg\&t=666s)

package/dist/docs/references/docs-agents-agent-approval.md

@@ -48,7 +48,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-> **Note:** Agent approval uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/memory/storage) on your Mastra instance or you'll see a "snapshot not found" error.
+> **Note:** Agent approval uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage/overview) on your Mastra instance or you'll see a "snapshot not found" error.
 >
 > Snapshots for agent runs are minimal resume artifacts: they hold only what's needed to resume the suspended run and are deleted once the run finishes. Use [tracing](https://mastra.ai/docs/observability/overview) for the execution record and [memory](https://mastra.ai/docs/memory/overview) for the conversation history.
 
@@ -110,6 +110,29 @@ A tool can also pause _during_ its `execute` function by calling `suspend()`. Th
 
 The stream emits a `tool-call-suspended` chunk with a custom payload defined by the tool's `suspendSchema`. You resume by calling `resumeStream()` with data matching the tool's `resumeSchema`.
 
+```typescript
+const weatherTool = createTool({
+  id: 'get-weather',
+  inputSchema: z.object({
+    location: z.string().optional(),
+  }),
+  suspendSchema: z.object({
+    question: z.string(),
+  }),
+  resumeSchema: z.object({
+    location: z.string(),
+  }),
+  execute: async ({ location }, context) => {
+    if (!location) {
+      return await context?.agent?.suspend({
+        question: 'Which city would you like the weather for?',
+      })
+    }
+    return await fetchWeather(location)
+  },
+})
+```
+
 > **Note:** `suspend()` doesn't throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
 
 ## Tool approval with `generate()`
@@ -397,7 +420,7 @@ Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `
 
 The same discovery is available over HTTP as `GET /agents/:agentId/suspended-runs` and in the client SDK as [`agent.listSuspendedRuns()`](https://mastra.ai/reference/client-js/agents), so browser-based approval UIs can rediscover pending runs directly.
 
-> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/memory/storage). The default in-memory store loses snapshots when the process exits.
+> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/storage/overview). The default in-memory store loses snapshots when the process exits.
 
 ## Tool approval: Supervisor agents
 

package/dist/docs/references/docs-agents-networks.md

@@ -95,7 +95,7 @@ console.log(final?.summary)
 
 When a primitive requires approval, the stream emits an `agent-execution-approval` or `tool-execution-approval` chunk. Use `approveNetworkToolCall()` or `declineNetworkToolCall()` to respond.
 
-Network approval uses snapshots to capture execution state. Ensure a [storage provider](https://mastra.ai/docs/memory/storage) is enabled in your Mastra instance.
+Network approval uses snapshots to capture execution state. Ensure a [storage provider](https://mastra.ai/docs/storage/overview) is enabled in your Mastra instance.
 
 ```typescript
 const stream = await routingAgent.network('Perform some sensitive action', {

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

@@ -309,6 +309,73 @@ const agent = new Agent({
 
 Both scenarios are safe - guardrails prevent inappropriate content from being persisted to memory
 
+## Handling large attachments
+
+Some storage providers enforce record size limits that base64-encoded file attachments 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             |
+
+PostgreSQL, MongoDB, and libSQL have higher limits and are usually unaffected.
+
+Use an input processor to upload attachments to external storage, then replace them with URL references before messages are persisted.
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+import type { MastraDBMessage } from '@mastra/core/memory'
+
+export class AttachmentUploader implements Processor {
+  id = 'attachment-uploader'
+
+  async processInput({ messages }: { messages: MastraDBMessage[] }) {
+    return Promise.all(messages.map(message => this.processMessage(message)))
+  }
+
+  async processMessage(message: MastraDBMessage) {
+    const attachments = message.content.experimental_attachments
+    if (!attachments?.length) return message
+
+    const uploaded = await Promise.all(
+      attachments.map(async attachment => {
+        if (!attachment.url?.startsWith('data:')) return attachment
+
+        const url = await this.upload(attachment.url, attachment.contentType)
+        return { ...attachment, url }
+      }),
+    )
+
+    return { ...message, content: { ...message.content, experimental_attachments: uploaded } }
+  }
+
+  async upload(dataUri: string, contentType?: string): Promise<string> {
+    const base64 = dataUri.split(',')[1]
+    const buffer = Buffer.from(base64, 'base64')
+
+    throw new Error('Implement upload() with your storage provider')
+  }
+}
+```
+
+Use the processor with your agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { AttachmentUploader } from '../processors/attachment-uploader'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({ lastMessages: 10 }),
+  inputProcessors: [new AttachmentUploader()],
+})
+```
+
 ## Related documentation
 
 - [Processors](https://mastra.ai/docs/agents/processors): General processor concepts and custom processor creation

package/dist/docs/references/docs-memory-message-history.md

@@ -6,7 +6,7 @@ Message history is the most basic and important form of memory. It gives the LLM
 
 You can also retrieve message history to display past conversations in your UI.
 
-> **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.
+> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
 
 > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
 >
@@ -14,9 +14,18 @@ You can also retrieve message history to display past conversations in your UI.
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
+## 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 another domain entity in your application.
+
+Studio automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, provide these identifiers explicitly.
+
 ## Getting started
 
-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.
+Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/storage/overview) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
 
 **npm**:
 
@@ -113,6 +122,51 @@ You can use this history in two ways:
 
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
+## Thread title generation
+
+Mastra can automatically generate descriptive thread titles based on the user's first message when `generateTitle` is enabled. Use this option when you build a chat interface that renders conversation titles in a thread list or sidebar.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    options: {
+      generateTitle: true,
+    },
+  }),
+})
+```
+
+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`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    options: {
+      generateTitle: {
+        model: 'openai/gpt-5-mini',
+        instructions: 'Generate a one-word title.',
+      },
+    },
+  }),
+})
+```
+
 ## Accessing memory
 
 To access memory functions for querying, cloning, or deleting threads and messages, call `getMemory()` on an agent:

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

@@ -13,7 +13,9 @@ Mastra agents can be configured to store [message history](https://mastra.ai/doc
 
 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.
 
-Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/memory/storage).
+Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/storage/overview).
+
+> **📹 Watch:** Watch [Mastra memory concepts](https://www.youtube.com/watch?v=18iIHQtIPmc) for a conceptual overview of the memory layers agents can use.
 
 ## When to use memory
 
@@ -75,7 +77,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
    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.
+   For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/storage/overview) documentation.
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
@@ -108,7 +110,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
    })
    ```
 
-   > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
+   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.
 
@@ -164,7 +166,7 @@ export const memoryAgent = new Agent({
 })
 ```
 
-> **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.
+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
 
@@ -178,7 +180,7 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 - **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, including all of its options. If the subagent defines its own, that takes precedence.
 
-> **Note:** Title generation (`generateTitle`) is a top-level thread concern and is **not** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
+> **Note:** Title generation (`generateTitle`) is a top-level thread concern and **isn't** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
 
 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.
 
@@ -236,7 +238,7 @@ export const memoryAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
 
 ## Related
 

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

@@ -4,7 +4,7 @@
 
 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:** Watch [Mastra semantic recall](https://www.youtube.com/watch?v=UVZtK8cK8xQ\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents retrieve relevant messages from past conversations.
 
 ## How semantic recall works
 
@@ -22,6 +22,8 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 Semantic recall is disabled by default. To enable it, set `semanticRecall: true` in `options` and provide a `vector` store and `embedder`:
 
+**LibSQL**:
+
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'
@@ -50,6 +52,38 @@ const agent = new Agent({
 })
 ```
 
+**MongoDB**:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
+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.5',
+  memory: new Memory({
+    storage: new MongoDBStore({
+      id: 'agent-storage',
+      uri: process.env.MONGODB_URI,
+      dbName: process.env.MONGODB_DB_NAME,
+    }),
+    vector: new MongoDBVector({
+      id: 'agent-vector',
+      uri: process.env.MONGODB_URI,
+      dbName: process.env.MONGODB_DB_NAME,
+    }),
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
+  }),
+})
+```
+
 ## 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 recency, use `recall()` with a `vectorSearchString`:
@@ -146,7 +180,7 @@ const agent = new Agent({
 })
 ```
 
-> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, and Upstash storage adapters.
+> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, MongoDB, and Upstash storage adapters.
 
 ### Metadata filtering
 

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

@@ -10,6 +10,8 @@ This is useful for maintaining ongoing state that's always relevant and should a
 
 If you use [Observational Memory](https://mastra.ai/docs/memory/observational-memory), `observationalMemory.observation.manageWorkingMemory` lets OM update working memory for the agent.
 
+> **📹 Watch:** Watch [Mastra working memory](https://www.youtube.com/watch?v=UMy_JHLf1n8\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents keep persistent user context available across interactions.
+
 Working memory can persist at two different scopes:
 
 - **Resource-scoped** (default): Memory persists across all conversation threads for the same user
@@ -43,9 +45,7 @@ const agent = new Agent({
 
 ## How it works
 
-Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
-
-[YouTube video player](https://www.youtube-nocookie.com/embed/UMy_JHLf1n8)
+Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information.
 
 ## Memory persistence scopes