@mastra/mcp-docs-server 1.2.7-alpha.3 → 1.2.7-alpha.6

package/.docs/reference/file-based-agents/storage.md

@@ -0,0 +1,30 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Storage
+
+Mastra sets the project's default [storage](https://mastra.ai/docs/storage/overview) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
+
+Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage/overview).
+
+## Quickstart
+
+Use [`LibSQLStore`](https://mastra.ai/reference/storage/libsql) for a local file-backed store:
+
+```typescript
+import { LibSQLStore } from '@mastra/libsql'
+
+export default new LibSQLStore({
+  id: 'mastra-storage',
+  url: 'file:./mastra.db',
+})
+```
+
+Mastra registers the store before file-based agents and workflows, so storage-dependent primitives bind to this store instead of the default in-memory store.
+
+## Production backends
+
+`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability storage](https://mastra.ai/docs/observability/storage), and the [storage reference](https://mastra.ai/reference/storage/overview).
+
+## Precedence with code
+
+Code-registered storage wins over `storage.ts`. Use `storage.ts` when one project-wide store is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

package/.docs/reference/file-based-agents/studio.md

@@ -0,0 +1,56 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Studio
+
+Mastra configures [Studio](https://mastra.ai/docs/studio/overview) from a `studio.ts` file directly under `src/mastra/`. The file default-exports a `StudioConfig` object for Studio authentication and authorization: who can access Studio, and what authenticated users can do.
+
+Use this page for the file-based convention. For auth providers, role-based access control (RBAC), and fine-grained authorization (FGA), see [Studio auth](https://mastra.ai/docs/studio/auth).
+
+## Quickstart
+
+For local development, you don't need `studio.ts`. Start the dev server and open Studio:
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+Studio opens without authentication in local development. Add `studio.ts` when you're ready to secure a shared or production deployment.
+
+## Add authentication
+
+Use an auth provider to require sign-in before users can access Studio. This example uses [WorkOS](https://mastra.ai/docs/server/auth/workos):
+
+```typescript
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+import type { StudioConfig } from '@mastra/core/server'
+
+export default {
+  auth: new MastraAuthWorkos(),
+} satisfies StudioConfig
+```
+
+The auth provider handles who the user is. For what the user can do after sign-in, add RBAC or FGA in the same config. See [Studio auth](https://mastra.ai/docs/studio/auth) for full examples.
+
+## Precedence with code
+
+Code-registered Studio config wins over `studio.ts`. Use `studio.ts` when one project-wide Studio config is enough; use code registration when auth depends on runtime wiring in `src/mastra/index.ts`.

package/.docs/reference/file-based-agents/subagents.md

@@ -0,0 +1,123 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Subagents
+
+A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory, calls that tool to hand off a task, and receives the subagent's result back in the parent conversation.
+
+Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents).
+
+## Quickstart
+
+Declare one directory per subagent under `subagents/`:
+
+```text
+src/mastra/agents/
+└── supervisor/
+    ├── config.ts
+    ├── instructions.md
+    └── subagents/
+        └── researcher/
+            ├── config.ts
+            ├── instructions.md
+            └── tools/
+                └── search.ts
+```
+
+Mastra assembles `researcher` as its own agent and wires it into the supervisor's `agents` map. The parent model can delegate to it by using the generated `researcher` delegation tool.
+
+A subagent's `config.ts` must set a non-empty `description`. The parent model reads this when deciding whether to delegate.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  description: 'Researches a topic and returns cited findings.',
+})
+```
+
+## How the model delegates
+
+A subagent's `description` is routing text for the parent model. Write it like a [tool description](https://mastra.ai/reference/file-based-agents/tools): explain what the subagent does and when to delegate to it.
+
+The build fails when a discovered subagent doesn't provide a non-empty description.
+
+## Isolation
+
+Subagents are isolated. A subagent doesn't inherit its parent's tools, skills, workspace, memory, processors, or subagents. Each child is a self-contained agent with its own directory.
+
+If multiple agents should share the same dependency, define it in code and assign it through each agent's config.
+
+## Nesting
+
+Subagents can declare their own `subagents/` directories, nesting up to three levels below the top-level agent. A `subagents/` directory nested deeper is ignored with a warning.
+
+```text
+src/mastra/agents/
+└── supervisor/            # depth 0
+    └── subagents/
+        └── researcher/    # depth 1
+            └── subagents/
+                └── summarizer/ # depth 2
+```
+
+## Naming rules
+
+- A subagent id that collides with one of the parent's tool keys is a build error.
+- A duplicate subagent id under the same parent is a build error.
+- If a subagent id also exists in the parent's `config.agents`, the `config.agents` entry wins and logs a warning.
+- If `config.agents` is a function, discovered subagents are ignored with a warning because they can't be statically merged.
+
+## Example
+
+This supervisor coordinates a research-and-writing flow. The `researcher` subagent owns search tools, while the `writer` subagent owns a workspace for drafting files.
+
+```text
+src/mastra/agents/
+└── research-supervisor/
+    ├── config.ts
+    ├── instructions.md
+    └── subagents/
+        ├── researcher/
+        │   ├── config.ts
+        │   ├── instructions.md
+        │   └── tools/
+        │       └── search_web.ts
+        └── writer/
+            ├── config.ts
+            ├── instructions.md
+            └── workspace/
+                └── draft-template.md
+```
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+})
+```
+
+```markdown
+You coordinate research and writing.
+
+Delegate fact gathering to `researcher`. Delegate final drafting to `writer`.
+```
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5-mini',
+  description: 'Use to gather facts, sources, and concise research notes for a topic.',
+})
+```
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  description: 'Use to turn research notes into a structured draft.',
+})
+```

package/.docs/reference/file-based-agents/tools.md

@@ -0,0 +1,63 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Tools
+
+A file-based agent discovers tools from `.ts` and `.js` files directly under its `tools/` directory. Each discovered file is imported at build time, the file must default-export a [`createTool()`](https://mastra.ai/reference/tools/create-tool) result, and the filename without its extension becomes the tool key the model can call.
+
+Use this page for the file-based convention. For tool schemas, execution options, output shaping, and approval options, see the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool).
+
+## Quickstart
+
+Place one tool per file under `tools/`. This file is exposed to the agent as `get_weather`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export default createTool({
+  id: 'get_weather',
+  description: 'Get the current weather for a city.',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  outputSchema: z.object({
+    city: z.string(),
+    tempC: z.number(),
+  }),
+  execute: async ({ context }) => {
+    return { city: context.city, tempC: 21 }
+  },
+})
+```
+
+## Organizing tools
+
+Use one file per tool. Name the file after the action the model should take:
+
+- Use `get_weather.ts`, `search_docs.ts`, or `create_ticket.ts`.
+- Avoid vague names like `helper.ts`, `api.ts`, or `utils.ts`.
+- Co-locate tests next to the tool as `*.test.ts` or `*.spec.ts`; discovery ignores those files.
+- Keep shared helper code outside `tools/` or in files that don't match the discovered extensions under `tools/`.
+
+Because nested directories aren't discovered as tools, group related tools with clear filename prefixes instead of subfolders, such as `calendar_create_event.ts` and `calendar_list_events.ts`.
+
+## Tool options
+
+The file-based convention only controls where the tool lives and how it's registered. The tool API still comes from `createTool()`:
+
+- Use `description` to tell the model when to call the tool.
+- Use `inputSchema` and `outputSchema` for structured inputs and outputs.
+- Use `toModelOutput` when the model should see a different shape than the raw value returned from `execute`.
+- Use `requireApproval` when a tool needs human confirmation before execution.
+
+See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for all options and [tool approval](https://mastra.ai/docs/agent-controller/tool-approvals) for the approval flow.
+
+## Runtime boundary
+
+Tool code runs in your app/server runtime when the agent calls the tool. If a tool needs filesystem or shell isolation, call [workspace](https://mastra.ai/reference/file-based-agents/workspace) or sandbox APIs explicitly.
+
+## Precedence with config
+
+Discovered tools merge with any `tools` in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). On a key collision, `config.tools` wins and a warning is logged.
+
+If `config.tools` is a function, discovered tools are ignored with a warning because function-valued tools can't be statically merged.

package/.docs/reference/file-based-agents/workflows.md

@@ -0,0 +1,52 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workflows
+
+Mastra discovers project-level workflows from `.ts` and `.js` files under `src/mastra/workflows/`. This convention isn't scoped to one agent: every file with a default export becomes a registered workflow, and the filename becomes the workflow key.
+
+Use this page for the file-based convention. For steps, schemas, control flow, streaming, state, and workflow execution, see [Workflows overview](https://mastra.ai/docs/workflows/overview).
+
+## Quickstart
+
+Create a file under `src/mastra/workflows/`, build the workflow with [`createWorkflow()`](https://mastra.ai/reference/workflows/workflow), and default-export it.
+
+```typescript
+import { createStep, createWorkflow } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const collectInputs = createStep({
+  id: 'collect-inputs',
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ topic: z.string(), audience: z.string() }),
+  execute: async ({ inputData }) => ({
+    topic: inputData.topic,
+    audience: 'engineering',
+  }),
+})
+
+const writeSummary = createStep({
+  id: 'write-summary',
+  inputSchema: z.object({ topic: z.string(), audience: z.string() }),
+  outputSchema: z.object({ report: z.string() }),
+  execute: async ({ inputData }) => ({
+    report: `Daily report about ${inputData.topic} for ${inputData.audience}.`,
+  }),
+})
+
+const dailyReport = createWorkflow({
+  id: 'daily-report',
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ report: z.string() }),
+})
+  .then(collectInputs)
+  .then(writeSummary)
+  .commit()
+
+export default dailyReport
+```
+
+Mastra registers this workflow under the `daily-report` key.
+
+## Precedence with code
+
+File-based workflows merge with workflows registered in [`new Mastra()`](https://mastra.ai/reference/core/mastra-class). On a key collision, the code-registered workflow wins.

package/.docs/reference/file-based-agents/workspace.md

@@ -0,0 +1,74 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workspace
+
+A [workspace](https://mastra.ai/docs/workspace/overview) gives an agent filesystem access and command execution. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`, so they can read and write files and run shell commands without extra configuration.
+
+Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Workspaces](https://mastra.ai/docs/workspace/overview).
+
+## Default workspace
+
+Without `workspace.ts`, a file-based agent gets a default [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) when the build provides a per-agent workspace path. The default workspace uses:
+
+- [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) rooted at the agent's bundled workspace directory.
+- [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) with the same working directory.
+
+This gives the agent file tools and shell tools automatically. The default workspace is per agent; subagents get nested workspace directories under their parent agent's workspace path.
+
+## Quickstart
+
+For the default workspace, don't add a file. Start with an agent directory like this:
+
+```text
+src/mastra/agents/weather/
+├── config.ts
+└── instructions.md
+```
+
+Add `workspace.ts` only when you need to customize the workspace:
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+export default new Workspace({
+  name: 'weather-workspace',
+  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
+  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
+})
+```
+
+Visit the [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class) for the full config.
+
+## When to customize the workspace
+
+Customize the workspace when the default local directory isn't enough. Common reasons include:
+
+- Point file tools at a different filesystem root.
+- Run shell commands in a different sandbox provider.
+- Add workspace search with BM25 or vector search.
+- Share one workspace across multiple agents.
+
+For provider patterns and runtime behavior, see the [workspace overview](https://mastra.ai/docs/workspace/overview), [sandbox guide](https://mastra.ai/docs/workspace/sandbox), and [workspace search](https://mastra.ai/docs/workspace/search).
+
+## Runtime boundary
+
+The workspace filesystem controls what file tools can read and write. The sandbox controls where shell commands run. Application runtime code, including code in [`tools/`](https://mastra.ai/reference/file-based-agents/tools), still runs in your app/server process unless it explicitly calls workspace or sandbox APIs.
+
+## Seed files
+
+Add a `workspace/` directory to ship starting files with the agent. Mastra mirrors files under `workspace/` into the agent's default runtime workspace at build time, so the agent starts with those files on disk.
+
+```text
+src/mastra/agents/weather/
+├── config.ts
+└── workspace/
+    ├── README.md
+    └── data/
+        └── cities.json
+```
+
+The files are copied into the bundled workspace path, where workspace file tools and sandbox commands can read them. Symlinked seed files are skipped during mirroring.
+
+## Precedence with config
+
+`config.workspace` wins over `workspace.ts`; otherwise the default file-based workspace is used. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.

package/.docs/reference/index.md

@@ -175,17 +175,32 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.startExperimentAsync()](https://mastra.ai/reference/datasets/startExperimentAsync)
 - [.update()](https://mastra.ai/reference/datasets/update)
 - [.updateItem()](https://mastra.ai/reference/datasets/updateItem)
+- [config.ts](https://mastra.ai/reference/file-based-agents/config)
+- [Instructions](https://mastra.ai/reference/file-based-agents/instructions)
+- [Memory](https://mastra.ai/reference/file-based-agents/memory)
+- [Observability](https://mastra.ai/reference/file-based-agents/observability)
+- [Processors](https://mastra.ai/reference/file-based-agents/processors)
+- [Server](https://mastra.ai/reference/file-based-agents/server)
+- [Skills](https://mastra.ai/reference/file-based-agents/skills)
+- [Storage](https://mastra.ai/reference/file-based-agents/storage)
+- [Studio](https://mastra.ai/reference/file-based-agents/studio)
+- [Subagents](https://mastra.ai/reference/file-based-agents/subagents)
+- [Tools](https://mastra.ai/reference/file-based-agents/tools)
+- [Workflows](https://mastra.ai/reference/file-based-agents/workflows)
+- [Workspace](https://mastra.ai/reference/file-based-agents/workspace)
 - [API Reference](https://mastra.ai/reference/mastra-platform/api)
 - [Cloned Thread Utilities](https://mastra.ai/reference/memory/clone-utilities)
 - [Memory Class](https://mastra.ai/reference/memory/memory-class)
 - [Observational Memory](https://mastra.ai/reference/memory/observational-memory)
 - [SerializedMemoryConfig](https://mastra.ai/reference/memory/serialized-memory-config)
+- [summarizeConversation()](https://mastra.ai/reference/memory/summarizeConversation)
 - [.cloneThread()](https://mastra.ai/reference/memory/cloneThread)
 - [.createThread()](https://mastra.ai/reference/memory/createThread)
 - [.deleteMessages()](https://mastra.ai/reference/memory/deleteMessages)
 - [.getThreadById()](https://mastra.ai/reference/memory/getThreadById)
 - [.listThreads()](https://mastra.ai/reference/memory/listThreads)
 - [.recall()](https://mastra.ai/reference/memory/recall)
+- [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
 - [Feedback](https://mastra.ai/reference/observability/feedback)
 - [PinoLogger](https://mastra.ai/reference/logging/pino-logger)
 - [Automatic Metrics](https://mastra.ai/reference/observability/metrics/automatic-metrics)

package/.docs/reference/memory/memory-class.md

@@ -37,7 +37,7 @@ export const agent = new Agent({
 
 **options** (`MemoryConfig`): Memory configuration options.
 
-**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable loading conversation history into context. Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To prevent saving new messages, use the readOnly option instead.
+**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option.
 
 **options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
 

package/.docs/reference/memory/serialized-memory-config.md

@@ -38,7 +38,7 @@ new MastraEditor({
 
 **options.readOnly** (`boolean`): Treat memory as read-only — no new messages are stored.
 
-**options.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable.
+**options.lastMessages** (`number | false`): Number of recent messages to include in context, or false to disable message history entirely (messages are not loaded or saved).
 
 **options.semanticRecall** (`boolean | SemanticRecall`): Semantic recall configuration. See the Memory class reference for the full shape.
 

package/.docs/reference/memory/summarizeConversation.md

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# summarizeConversation()
+
+The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — without Observational Memory attached to an agent, and without reading from or writing to storage.
+
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+
+Use this when you already have the messages in hand and want explicit control over what gets summarized. To summarize a stored thread by ID instead, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
+
+## Usage example
+
+```typescript
+import { summarizeConversation } from '@mastra/memory'
+
+const result = await summarizeConversation({
+  model: 'openai/gpt-5-mini',
+  messages,
+  instructions: 'Summarize this voicemail call for the business owner.',
+})
+```
+
+## Parameters
+
+**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
+
+**messages** (`MastraDBMessage[]`): The conversation to summarize. When empty, the function returns an empty result without calling the model.
+
+**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
+
+**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
+
+**threadId** (`string`): Thread the conversation belongs to. Defaults to the first threadId found on messages. Passed to extractor contexts.
+
+**resourceId** (`string`): Resource (user) the conversation belongs to. Defaults to the first resourceId found on messages. Passed to extractor contexts.
+
+**memory** (`Memory`): Memory instance forwarded to extractor contexts. Set automatically when called through Memory.summarizeThread().
+
+**mastra** (`Mastra`): Mastra instance used to resolve custom gateway models. Set automatically when called through Memory.summarizeThread().
+
+**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
+
+**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
+
+## Returns
+
+**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
+
+**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
+
+**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
+
+**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
+
+## Extended usage example
+
+The following example summarizes an in-flight voice session from messages the application already holds, and extracts a structured record:
+
+```typescript
+import { summarizeConversation, Extractor } from '@mastra/memory'
+import type { MastraDBMessage } from '@mastra/core/agent'
+import { z } from 'zod'
+import { sessionRecords } from './db'
+
+const sessionSummary = new Extractor({
+  name: 'session-summary',
+  instructions: 'Return a concise summary of the session.',
+  schema: z.object({
+    summary: z.string(),
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    followUps: z.array(z.string()),
+  }),
+  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
+  onExtracted: async ({ current, threadId }) => {
+    await sessionRecords.upsert({ sessionId: threadId, record: current })
+  },
+})
+
+export async function onSessionEnd(messages: MastraDBMessage[]) {
+  const { summary, extracted, extractionFailures } = await summarizeConversation({
+    model: 'openai/gpt-5-mini',
+    messages,
+    instructions: 'Summarize this support session for the account manager.',
+    extract: [sessionSummary],
+  })
+
+  if (extractionFailures?.length) {
+    console.warn('Some extractors failed', extractionFailures)
+  }
+
+  return { summary, extracted }
+}
+```
+
+### Related
+
+- [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)

package/.docs/reference/memory/summarizeThread.md

@@ -0,0 +1,93 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.summarizeThread()
+
+The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — as a standalone call, without Observational Memory attached to an agent.
+
+Messages load page-by-page starting from the newest, bounded by `lastMessages` and `maxInputTokens`, so summarizing a long thread doesn't read its entire history from storage.
+
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+
+Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. To summarize messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead — it takes the same options with `messages` in place of `threadId`.
+
+## Usage example
+
+```typescript
+const result = await memory.summarizeThread({
+  model: 'openai/gpt-5-mini',
+  threadId: 'thread-123',
+  instructions: 'Summarize this voicemail call for the business owner.',
+})
+```
+
+## Parameters
+
+**threadId** (`string`): The unique identifier of the thread to summarize.
+
+**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
+
+**resourceId** (`string`): ID of the resource that owns the thread. If provided, validates thread ownership. Also passed to extractor contexts.
+
+**lastMessages** (`number`): Only summarize the last N messages of the thread. By default the whole thread is loaded, bounded by maxInputTokens.
+
+**maxInputTokens** (`number`): Stop loading older messages once the collected messages exceed this estimated token count. The newest message is always included. (Default: `1000000`)
+
+**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
+
+**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
+
+**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
+
+**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
+
+## Returns
+
+**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
+
+**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
+
+**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
+
+**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
+
+## Extended usage example
+
+The following example summarizes a finished voice call and stores a structured record in the application's own database:
+
+```typescript
+import { Extractor } from '@mastra/memory'
+import { z } from 'zod'
+import { memory } from './mastra/memory'
+import { callRecords } from './db'
+
+const callSummary = new Extractor({
+  name: 'call-summary',
+  instructions: 'Return a concise summary of the call.',
+  schema: z.object({
+    summary: z.string(),
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    requestedServices: z.array(z.string()),
+  }),
+  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
+  onExtracted: async ({ current, threadId, resourceId }) => {
+    await callRecords.upsert({ callId: threadId, callerId: resourceId, record: current })
+  },
+})
+
+export async function onCallEnd(threadId: string, resourceId: string) {
+  await memory.summarizeThread({
+    model: 'openai/gpt-5-mini',
+    threadId,
+    resourceId,
+    instructions: 'Summarize this voicemail call for the business owner.',
+    extract: [callSummary],
+  })
+}
+```
+
+### Related
+
+- [summarizeConversation()](https://mastra.ai/reference/memory/summarizeConversation)
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)
+- [.recall()](https://mastra.ai/reference/memory/recall)

package/.docs/reference/project-structure.md

@@ -44,7 +44,7 @@ Mastra recommends organizing your code into the following folders:
 
 Mastra has two special folder conventions:
 
-- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [file-based agents](https://mastra.ai/docs/agents/file-based-agents) guide.
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/file-based-agents) docs.
 - `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files