@mastra/core 1.3.0 → 1.4.0

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

@@ -24,11 +24,21 @@ export const agent = new Agent({
 });
 ```
 
-That's it. The agent now has humanlike long-term memory that persists across conversations.
+That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model or customize thresholds, pass a config object instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "deepseek/deepseek-reasoner",
+    },
+  },
+});
+```
 
 See [configuration options](https://mastra.ai/reference/memory/observational-memory) for full API details.
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It also uses background agents for managing memory. The default model (configurable) is `google/gemini-2.5-flash` as it's the one we've tested the most.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
 
 ## Benefits
 
@@ -77,7 +87,9 @@ The result is a three-tier system:
 
 The Observer and Reflector run in the background. Any model that works with Mastra's model routing (e.g. `openai/...`, `google/...`, `deepseek/...`) can be used.
 
-The default is `google/gemini-2.5-flash` — it works well for both observation and reflection, and its 1M token context window gives the Reflector headroom.
+When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
+
+We recommend `google/gemini-2.5-flash` — it works well for both observation and reflection, and its 1M token context window gives the Reflector headroom.
 
 We've also tested `deepseek`, `qwen3`, and `glm-4.7` for the Observer. For the Reflector, make sure the model's context window can fit all observations. Note that Claude 4.5 models currently don't work well as observer or reflector.
 
@@ -97,24 +109,40 @@ See [model configuration](https://mastra.ai/reference/memory/observational-memor
 
 ### Thread scope (default)
 
-Each thread has its own observations.
+Each thread has its own observations. This scope is well tested and works well as a general purpose memory system, especially for long horizon agentic use-cases.
 
 ```typescript
-observationalMemory: {
-  scope: "thread",
-}
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      scope: "thread",
+    },
+  },
+});
 ```
 
-### Resource scope
+### Resource scope (experimental)
 
 Observations are shared across all threads for a resource (typically a user). Enables cross-conversation memory.
 
 ```typescript
-observationalMemory: {
-  scope: "resource",
-}
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      scope: "resource",
+    },
+  },
+});
 ```
 
+Resource scope works, however it's marked as experimental for now until we prove task adherence/continuity across multiple ongoing simultaneous threads. As of today, you may need to tweak your system prompt to prevent one thread from continuing the work that another had already started (but hadn't finished).
+
+This is because in resource scope, each thread is a perspective on _all_ threads for the resource.
+
+For your use-case this may not be a problem, so your mileage may vary.
+
 > **Warning:** In resource scope, unobserved messages across _all_ threads are processed together. For users with many existing threads, this can be slow. Use thread scope for existing apps.
 
 ## Token Budgets
@@ -125,6 +153,7 @@ OM uses token thresholds to decide when to observe and reflect. See [token budge
 const memory = new Memory({
   options: {
     observationalMemory: {
+      model: "google/gemini-2.5-flash",
       observation: {
         // when to run the Observer (default: 30,000)
         messageTokens: 30_000,
@@ -134,12 +163,58 @@ const memory = new Memory({
         observationTokens: 40_000,
       },
       // let message history borrow from observation budget
+      // requires bufferTokens: false (temporary limitation)
       shareTokenBudget: false,
     },
   },
 });
 ```
 
+## Async Buffering
+
+Without async buffering, the Observer runs synchronously when the message threshold is reached — the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.
+
+### How it works
+
+As the agent converses, message tokens accumulate. At regular intervals (`bufferTokens`), a background Observer call runs without blocking the agent. Each call produces a "chunk" of observations that's stored in a buffer.
+
+When message tokens reach the `messageTokens` threshold, buffered chunks activate: their observations move into the active observation log, and the corresponding raw messages are removed from the context window. The agent never pauses.
+
+If the agent produces messages faster than the Observer can process them, a `blockAfter` safety threshold forces a synchronous observation as a last resort.
+
+Reflection works similarly — the Reflector runs in the background when observations reach a fraction of the reflection threshold.
+
+### Settings
+
+| Setting                        | Default | What it controls                                                                                                                                                                      |
+| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).    |
+| `observation.bufferActivation` | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history. |
+| `observation.blockAfter`       | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                  |
+| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                  |
+| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                           |
+
+### Disabling
+
+To disable async buffering and use synchronous observation/reflection instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      observation: {
+        bufferTokens: false,
+      },
+    },
+  },
+});
+```
+
+Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
+
+> **Note:** Async buffering is not supported with `scope: 'resource'`. It is automatically disabled in resource scope.
+
 ## Migrating existing threads
 
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.

package/dist/docs/references/docs-streaming-events.md

@@ -126,6 +126,29 @@ Below is an example of events that may be emitted. Each event always includes a
 }
 ```
 
+### Foreach progress events
+
+When a workflow uses `.foreach()`, each iteration emits a `workflow-step-progress` event. You can use these to track real-time progress:
+
+```typescript
+for await (const chunk of stream) {
+  if (chunk.type === 'workflow-step-progress') {
+    console.log(
+      `${chunk.payload.id}: ${chunk.payload.completedCount}/${chunk.payload.totalCount} — ${chunk.payload.iterationStatus}`
+    );
+  }
+}
+```
+
+Each progress event includes:
+
+- **`id`**: The step ID of the foreach step
+- **`completedCount`**: Number of iterations completed so far
+- **`totalCount`**: Total number of iterations
+- **`currentIndex`**: Index of the iteration that just completed
+- **`iterationStatus`**: Status of the iteration (`success`, `failed`, or `suspended`)
+- **`iterationOutput`**: Output of the iteration (when successful)
+
 ## Inspecting agent networks
 
 When using multi-agent collaboration with `agent.network()`, iterate over the stream to track how tasks are delegated and executed across agents, workflows, and tools.

package/dist/docs/references/docs-workspace-filesystem.md

@@ -17,8 +17,10 @@ A filesystem provider handles all file operations for a workspace:
 Available providers:
 
 - [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) - Stores files in a directory on disk
+- [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) - Stores files in Amazon S3 or S3-compatible storage (R2, MinIO)
+- [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem) - Stores files in Google Cloud Storage
 
-> **Tip:** `LocalFilesystem` is the simplest way to get started as it requires no external services.
+> **Tip:** `LocalFilesystem` is the simplest way to get started as it requires no external services. For cloud storage, use `S3Filesystem` or `GCSFilesystem`.
 
 ## Basic usage
 
@@ -45,6 +47,25 @@ const agent = new Agent({
 const response = await agent.generate('List all files in the workspace');
 ```
 
+## Containment
+
+By default, `LocalFilesystem` runs in **contained mode** — all file operations are restricted to stay within `basePath`. This prevents path traversal attacks and symlink escapes.
+
+In contained mode, absolute paths that fall within `basePath` are used as-is, while other absolute paths are treated as virtual paths relative to `basePath` (e.g. `/file.txt` resolves to `basePath/file.txt`). Any resolved path that escapes `basePath` throws a `PermissionError`.
+
+If your agent needs to access paths outside `basePath` (for example, global skills directories or user home folders), disable containment:
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+    contained: false,
+  }),
+});
+```
+
+When `contained` is `false`, absolute paths are treated as real filesystem paths with no restriction.
+
 ## Read-only mode
 
 To prevent agents from modifying files, enable read-only mode:
@@ -60,6 +81,54 @@ const workspace = new Workspace({
 
 When read-only, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are not added to the agent's toolset. The agent can still read and list files.
 
+## Mounts and CompositeFilesystem
+
+When you use the `mounts` option on a workspace, Mastra creates a `CompositeFilesystem` that routes file operations to the correct provider based on path prefix.
+
+```typescript
+import { Workspace } from '@mastra/core/workspace';
+import { S3Filesystem } from '@mastra/s3';
+import { GCSFilesystem } from '@mastra/gcs';
+import { E2BSandbox } from '@mastra/e2b';
+
+const workspace = new Workspace({
+  mounts: {
+    '/data': new S3Filesystem({
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+    '/skills': new GCSFilesystem({
+      bucket: 'agent-skills',
+    }),
+  },
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+});
+```
+
+With this configuration:
+
+- `read_file('/data/input.csv')` reads from the S3 bucket
+- `write_file('/skills/guide.md', content)` writes to the GCS bucket
+- `list_directory('/')` returns virtual entries for `/data` and `/skills`
+- Commands in the sandbox can access files at `/data` and `/skills` via FUSE mounts
+
+### Path routing
+
+All file paths must start with a mount prefix. Operations on paths that don't match any mount will fail. Listing the root directory (`/`) returns virtual directory entries for each mount point.
+
+Mount paths cannot be nested — for example, you cannot mount at both `/data` and `/data/sub`.
+
+### `filesystem` vs `mounts`
+
+`filesystem` and `mounts` are mutually exclusive options on a workspace:
+
+- Use **`filesystem`** when you have a single storage provider and don't need to mount it into a sandbox. The agent gets file tools that operate directly against the provider.
+- Use **`mounts`** when you need cloud storage accessible inside a sandbox, or when you want to combine multiple providers. The workspace creates a CompositeFilesystem for file tools and FUSE-mounts the storage into the sandbox.
+
+For local development, you typically don't need `mounts` — a `LocalFilesystem` and `LocalSandbox` pointed at the same directory gives you both file tools and command execution on the same files. See [configuration patterns](https://mastra.ai/docs/workspace/overview) for more detail.
+
 ## Agent tools
 
 When you configure a filesystem on a workspace, agents receive tools for reading, writing, listing, and deleting files. See [workspace class reference](https://mastra.ai/reference/workspace/workspace-class) for details.
@@ -67,5 +136,7 @@ When you configure a filesystem on a workspace, agents receive tools for reading
 ## Related
 
 - [LocalFilesystem reference](https://mastra.ai/reference/workspace/local-filesystem)
+- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [GCSFilesystem reference](https://mastra.ai/reference/workspace/gcs-filesystem)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
 - [Sandbox](https://mastra.ai/docs/workspace/sandbox)

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

@@ -75,31 +75,88 @@ export const myAgent = new Agent({
 });
 ```
 
-## Initialization
+## Configuration patterns
 
-Calling `init()` is optional in most cases—some providers initialize on first operation. Call `init()` manually when using a workspace outside of Mastra (standalone scripts, tests) or when you need to pre-provision resources before the first agent interaction.
+Workspaces support several configuration patterns depending on what capabilities your agent needs. The two main building blocks are `filesystem` (file tools) and `sandbox` (command execution), with `mounts` as the way to bridge cloud storage into sandboxes.
 
-```typescript
-import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
+### Filesystem + sandbox (local)
+
+For local development, pair a `LocalFilesystem` and `LocalSandbox` pointed at the same directory. Since both operate on the local machine, files written through the filesystem are immediately available to commands in the sandbox:
 
+```typescript
 const workspace = new Workspace({
   filesystem: new LocalFilesystem({ basePath: './workspace' }),
   sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
 });
+```
 
-// Optional: pre-create directories and sandbox before first use
-await workspace.init();
+The agent receives both file tools and `execute_command`. This is the simplest full-featured setup.
+
+### Mounts + sandbox (cloud storage)
+
+When you need cloud storage accessible inside a sandbox, use `mounts`. This FUSE-mounts the cloud filesystem into the sandbox so commands can read and write files at the mount path:
+
+```typescript
+const workspace = new Workspace({
+  mounts: {
+    '/data': new S3Filesystem({
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+    '/skills': new GCSFilesystem({
+      bucket: 'agent-skills',
+    }),
+  },
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+});
 ```
 
-### What init() does
+Under the hood, `mounts` creates a [CompositeFilesystem](https://mastra.ai/docs/workspace/filesystem) that routes file tool operations to the correct provider based on path prefix. Commands in the sandbox access the mounted paths directly (e.g., `ls /data`).
 
-Initialization runs setup logic for each configured provider:
+You can mount multiple providers at different paths. Each mount path must be unique and non-overlapping.
 
-- `LocalFilesystem`: Creates the base directory if it doesn't exist
-- `LocalSandbox`: Creates the working directory
-- `Search` (if configured): Indexes files from `autoIndexPaths`, see [Search and Indexing](https://mastra.ai/docs/workspace/search)
+> **Note:** `filesystem` and `mounts` are mutually exclusive — you cannot use both in the same workspace. Use `filesystem` for a single provider without a sandbox, or `mounts` when you need to combine cloud storage with a sandbox.
 
-External providers may perform additional setup like establishing connections or authenticating.
+### Filesystem only
+
+Use a single `filesystem` when agents only need to read and write files. No command execution is available.
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new S3Filesystem({
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  }),
+});
+```
+
+The agent receives file tools (`read_file`, `write_file`, `list_directory`, etc.) that operate directly against the storage provider.
+
+### Sandbox only
+
+Use a single `sandbox` when agents only need to execute commands. No file tools are added.
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+});
+```
+
+The agent receives the `execute_command` tool.
+
+### Which pattern should I use?
+
+| Scenario                                              | Pattern                                               |
+| ----------------------------------------------------- | ----------------------------------------------------- |
+| Local development with files and commands             | `filesystem` + `sandbox` (both local, same directory) |
+| Cloud storage accessible inside a cloud sandbox       | `mounts` + `sandbox`                                  |
+| Multiple cloud providers in one sandbox               | `mounts` + `sandbox` (one mount per provider)         |
+| Agent reads/writes files, no command execution needed | `filesystem` only                                     |
+| Agent runs commands, no file tools needed             | `sandbox` only                                        |
 
 ## Tool configuration
 
@@ -147,6 +204,32 @@ When `requireReadBeforeWrite` is enabled on write tools, agents must read a file
 - **Existing files**: Must be read first
 - **Externally modified files**: If a file changed since the agent read it, the write fails
 
+## Initialization
+
+Calling `init()` is optional in most cases—some providers initialize on first operation. Call `init()` manually when using a workspace outside of Mastra (standalone scripts, tests) or when you need to pre-provision resources before the first agent interaction.
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+});
+
+// Optional: pre-create directories and sandbox before first use
+await workspace.init();
+```
+
+### What init() does
+
+Initialization runs setup logic for each configured provider:
+
+- `LocalFilesystem`: Creates the base directory if it doesn't exist
+- `LocalSandbox`: Creates the working directory
+- `Search` (if configured): Indexes files from `autoIndexPaths`, see [Search and Indexing](https://mastra.ai/docs/workspace/search)
+
+External providers may perform additional setup like establishing connections or authenticating.
+
 ## Related
 
 - [Filesystem](https://mastra.ai/docs/workspace/filesystem)

package/dist/docs/references/docs-workspace-sandbox.md

@@ -19,6 +19,7 @@ When you assign a workspace with a sandbox to an agent, Mastra automatically inc
 Available providers:
 
 - [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) - Executes commands on the local machine
+- [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox) - Executes commands in isolated E2B cloud sandboxes
 
 ## Basic usage
 
@@ -57,5 +58,6 @@ When you configure a sandbox on a workspace, agents receive the `execute_command
 ## Related
 
 - [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [`E2BSandbox` reference](https://mastra.ai/reference/workspace/e2b-sandbox)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
 - [Filesystem](https://mastra.ai/docs/workspace/filesystem)

package/dist/docs/references/guides-agent-frameworks-ai-sdk.md

@@ -83,9 +83,11 @@ const storage = new LibSQLStore({
 });
 await storage.init();
 
+const memoryStorage = await storage.getStore('memory');
+
 const model = withMastra(openai('gpt-4o'), {
   memory: {
-    storage,
+    storage: memoryStorage!,
     threadId: 'user-thread-123',
     resourceId: 'user-123',
     lastMessages: 10,
@@ -111,11 +113,13 @@ import { LibSQLStore } from '@mastra/libsql';
 const storage = new LibSQLStore({ id: 'my-app', url: 'file:./data.db' });
 await storage.init();
 
+const memoryStorage = await storage.getStore('memory');
+
 const model = withMastra(openai('gpt-4o'), {
   inputProcessors: [myGuardProcessor],
   outputProcessors: [myLoggingProcessor],
   memory: {
-    storage,
+    storage: memoryStorage!,
     threadId: 'thread-123',
     resourceId: 'user-123',
     lastMessages: 10,

package/dist/docs/references/reference-ai-sdk-with-mastra.md

@@ -40,7 +40,7 @@ const { text } = await generateText({
 
 **options.memory?:** (`WithMastraMemoryOptions`): Memory configuration - enables automatic message history persistence.
 
-**options.memory.storage:** (`MemoryStorage`): Storage adapter for message persistence (e.g., LibSQLStore, PostgresStore).
+**options.memory.storage:** (`MemoryStorage`): Memory storage domain for message persistence. Get it from a composite store using \`await storage.getStore('memory')\`.
 
 **options.memory.threadId:** (`string`): Thread ID for conversation persistence.