@mastra/mcp-docs-server 1.2.3-alpha.13 → 1.2.3-alpha.15

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

@@ -103,6 +103,7 @@ The following table shows the supported file-based agent surface:
 | `agents/<name>/skills/*.ts`             | Each default-exported [`createSkill()`](https://mastra.ai/reference/agents/createSkill), added to the agent `skills`.                     |
 | `agents/<name>/skills/<skill>/SKILL.md` | A packaged skill. Frontmatter supplies `name` and `description`, the body is the instructions, and files under `references/` are inlined. |
 | `agents/<name>/skills/<skill>.md`       | A flat skill. The filename is the skill name and the body is the instructions.                                                            |
+| `agents/<name>/memory.ts`               | Default export: a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance used as the agent `memory`.                        |
 | `agents/<name>/workspace.ts`            | Default export: a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) for the agent.                                     |
 | `agents/<name>/workspace/`              | Seed files mirrored into the agent's default workspace at build time.                                                                     |
 | `agents/<name>/subagents/<childId>/`    | A declared subagent with the same layout as an agent directory. Wired into the parent as a delegation tool named `<childId>`.             |
@@ -146,6 +147,18 @@ Add skills to a file-based agent by placing them under `agents/<name>/skills/`.
 
 Discovered skills merge with any `skills` in `config.ts`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning because they can't be statically merged.
 
+## Add memory
+
+Give a file-based agent [memory](https://mastra.ai/docs/memory/overview) by adding a `memory.ts` that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance:
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory()
+```
+
+The exported instance becomes the agent's `memory`. You can also set `memory` directly in `config.ts`. `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is present, the agent has no memory, which is the default.
+
 ## Add a workspace
 
 When a file-based agent is discovered through `mastra dev` or `mastra build`, it gets a default workspace unless `config.workspace` or `workspace.ts` supplies one. The default workspace uses a contained filesystem and shell sandbox rooted at a per-agent `workspace/` directory in the bundle.
@@ -180,7 +193,7 @@ Seed files are copied into the bundle next to the running server. Commit the sta
 
 ## Add subagents
 
-A file-based agent can declare **subagents**, specialist child agents it can delegate to. Add a `subagents/` directory under the agent, with one directory per subagent. Each subagent directory has the same layout as a top-level agent: `config.ts`, `instructions.md`, `tools/`, `skills/`, `workspace.ts`, and `workspace/`.
+A file-based agent can declare **subagents**, specialist child agents it can delegate to. Add a `subagents/` directory under the agent, with one directory per subagent. Each subagent directory has the same layout as a top-level agent: `config.ts`, `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `workspace/`.
 
 ```text
 src/mastra/agents/
@@ -224,11 +237,12 @@ Naming rules:
 File-based and code-based agents coexist with deterministic rules:
 
 - **Code wins on name collisions:** If an agent name exists in both code and the filesystem, the code-registered agent is kept and a warning is logged.
-- **A folder can hold a code agent:** If `config.ts` exports `new Agent({...})`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
+- **A folder can hold a code agent:** If `config.ts` exports `new Agent({...})`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
 - **Instructions:** Dynamic function instructions in `config.ts` win over `instructions.md`. Otherwise, `instructions.md` wins over a static `instructions` string. If neither is present, the build fails for that agent.
 - **Model:** A missing `model` fails the build and names the agent directory.
 - **Tools:** Tools from `tools/*.ts` merge with `config.tools`. 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.
 - **Skills:** Skills from `skills/` merge with `config.skills`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning.
+- **Memory:** `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is set, the agent has no memory.
 - **Workspace:** `config.workspace` wins over `workspace.ts`, which wins over the default workspace.
 - **Subagents:** Subagents from `subagents/` merge with `config.agents`. On an id collision, `config.agents` wins and a warning is logged. A subagent id that collides with a tool key, or a duplicate subagent id, is a build error.
 
@@ -261,10 +275,12 @@ export const mastra = new Mastra({
 - [Agents overview](https://mastra.ai/docs/agents/overview)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
 - [Skills](https://mastra.ai/docs/agents/skills)
+- [Memory](https://mastra.ai/docs/memory/overview)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
 - [Workspace](https://mastra.ai/docs/workspace/overview)
 - [Studio overview](https://mastra.ai/docs/studio/overview)
 - [`Agent` reference](https://mastra.ai/reference/agents/agent)
 - [`createTool()` reference](https://mastra.ai/reference/tools/create-tool)
 - [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
+- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
 - [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/reference/coding-agent/build-base-prompt.md

@@ -0,0 +1,75 @@
+# buildBasePrompt()
+
+`buildBasePrompt()` builds the shared base system prompt for a coding agent — the behavioral instructions that make the agent a good coding assistant. It takes a `PromptContext` describing the current environment (project, platform, git branch, mode, model) and returns the prompt as a string.
+
+Product-specific strings are parameterized through `productName`, `coAuthorName`, and `coAuthorEmail`, so you can rebrand the prompt and commit trailer without forking it. They default to `"Mastra Code"` / `"noreply@mastra.ai"`, so existing callers keep identical output.
+
+Use this with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) when you build dynamic instructions for the agent.
+
+## Usage example
+
+Build the base prompt from a `PromptContext`:
+
+```typescript
+import { buildBasePrompt } from '@mastra/core/coding-agent'
+
+const prompt = buildBasePrompt({
+  projectPath: process.cwd(),
+  projectName: 'my-app',
+  gitBranch: 'main',
+  platform: process.platform,
+  date: new Date().toDateString(),
+  mode: 'build',
+  modelId: 'openai/gpt-5',
+  toolGuidance: '',
+})
+```
+
+To rebrand the prompt, pass the product and co-author fields:
+
+```typescript
+const prompt = buildBasePrompt({
+  // ...environment fields
+  productName: 'Acme Coder',
+  coAuthorName: 'Acme Bot',
+  coAuthorEmail: 'bot@acme.dev',
+})
+```
+
+## Parameters
+
+`buildBasePrompt()` takes a single `PromptContext` object.
+
+**projectPath** (`string`): Absolute path to the project root.
+
+**projectName** (`string`): Display name of the project.
+
+**gitBranch** (`string`): Current git branch, if the project is a git repository.
+
+**platform** (`string`): Operating system platform (for example, the value of process.platform).
+
+**commonBinaries** (`{ name: string; path: string | null }[]`): Common binaries detected on the system, each with a name and resolved path (or null when not found).
+
+**date** (`string`): Current date string injected into the prompt.
+
+**mode** (`string`): Active agent mode (for example, "build" or "plan").
+
+**modelId** (`string`): Identifier of the active model, included in the commit Co-Authored-By line when provided.
+
+**activePlan** (`{ title: string; plan: string; approvedAt: string } | null`): The currently approved plan, if any.
+
+**toolGuidance** (`string`): Tool-usage guidance section appended to the prompt.
+
+**productName** (`string`): Display name used in the prompt header. (Default: `Mastra Code`)
+
+**coAuthorName** (`string`): Name used in the commit Co-Authored-By line. (Default: `Mastra Code`)
+
+**coAuthorEmail** (`string`): Email used in the commit Co-Authored-By line. (Default: `noreply@mastra.ai`)
+
+## Returns
+
+**prompt** (`string`): The base system prompt for the coding agent.
+
+## Related
+
+- [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent)

package/.docs/reference/coding-agent/create-coding-agent.md

@@ -0,0 +1,97 @@
+# createCodingAgent()
+
+`createCodingAgent()` builds a coding [`Agent`](https://mastra.ai/reference/agents/agent) with portable defaults for the pieces a coding agent always needs: a local workspace, the task-list signal provider, network-retry error processors, and the goal judge prompt. Supply only `model`, `instructions`, and `tools` to get a working agent, or override any default.
+
+The returned value is a standard `Agent`, so it works anywhere an `Agent` does — including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+
+## Usage example
+
+Pass a model, instructions, and tools. The factory fills in the workspace, task signal, error processors, and goal prompt:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  tools: {},
+})
+```
+
+## Parameters
+
+`createCodingAgent()` accepts every field of [`AgentConfig`](https://mastra.ai/reference/agents/agent) plus the fields below. Fields you provide always take precedence over the factory defaults.
+
+**model** (`MastraLanguageModel | DynamicArgument<MastraLanguageModel>`): The language model the agent uses. Passed straight through to Agent.
+
+**instructions** (`string | DynamicArgument<string>`): System instructions for the agent. Passed straight through to Agent.
+
+**tools** (`ToolsInput | DynamicArgument<ToolsInput>`): Tools available to the agent. Passed straight through to Agent.
+
+**workspace** (`AnyWorkspace | undefined`): The workspace backing the agent. When the key is omitted, a default local workspace is built. When set explicitly to undefined, the factory builds no default — opt out when the workspace is wired elsewhere (for example at the AgentController level).
+
+**basePath** (`string`): Base path for the default workspace built when workspace is omitted. (Default: `process.cwd()`)
+
+**signals** (`SignalProvider[]`): Signal providers for the agent. When omitted, defaults to a single TaskSignalProvider.
+
+**errorProcessors** (`Processor[]`): Error processors for the agent. When omitted, defaults to the ECONNRESET/bad-request retry stack plus PrefillErrorHandler and ProviderHistoryCompat.
+
+**goal** (`AgentGoalConfig`): Goal configuration. When provided without a prompt, the prompt defaults to DEFAULT\_GOAL\_JUDGE\_PROMPT.
+
+## Returns
+
+**agent** (`Agent`): A coding agent with the resolved workspace, signals, error processors, and goal applied.
+
+## Defaults
+
+The factory only fills a default when you do not provide the corresponding field. Caller-provided values always win.
+
+| Field             | Default when omitted                                                                                                                           |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `workspace`       | A [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) backed by `LocalFilesystem` and `LocalSandbox` rooted at the base path. |
+| `signals`         | A single [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider).                                                     |
+| `errorProcessors` | ECONNRESET and bad-request retry processors plus `PrefillErrorHandler` and `ProviderHistoryCompat`.                                            |
+| `goal.prompt`     | `DEFAULT_GOAL_JUDGE_PROMPT` (only when a `goal` is configured).                                                                                |
+
+### Workspace
+
+When the `workspace` key is omitted, the factory builds a local workspace rooted at `basePath` (default `process.cwd()`):
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+new Workspace({
+  filesystem: new LocalFilesystem({ basePath }),
+  sandbox: new LocalSandbox({ workingDirectory: basePath }),
+})
+```
+
+To opt out — for example when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level — pass `workspace: undefined` explicitly:
+
+```typescript
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  tools: {},
+  workspace: undefined, // opt out of the default workspace
+})
+```
+
+### Error processors
+
+The default error processors apply a retry policy for transient failures:
+
+- Network resets (`ECONNRESET` / `socket hang up`) retry up to twice with exponential backoff (`1000ms * 2^retryCount`, capped at `30000ms`).
+- Bad-request errors retry once after `2000ms`.
+
+`PrefillErrorHandler` and `ProviderHistoryCompat` are also included for provider compatibility.
+
+## Related
+
+- [`buildBasePrompt()`](https://mastra.ai/reference/coding-agent/build-base-prompt)
+- [`Agent`](https://mastra.ai/reference/agents/agent)
+- [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/reference/index.md

@@ -74,6 +74,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Tools API](https://mastra.ai/reference/client-js/tools)
 - [Vectors API](https://mastra.ai/reference/client-js/vectors)
 - [Workflows API](https://mastra.ai/reference/client-js/workflows)
+- [buildBasePrompt()](https://mastra.ai/reference/coding-agent/build-base-prompt)
+- [createCodingAgent()](https://mastra.ai/reference/coding-agent/create-coding-agent)
 - [Mastra Class](https://mastra.ai/reference/core/mastra-class)
 - [MastraModelGateway](https://mastra.ai/reference/core/mastra-model-gateway)
 - [.addGateway()](https://mastra.ai/reference/core/addGateway)

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.3-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`0ac14ce`](https://github.com/mastra-ai/mastra/commit/0ac14cea48e1b0a7857782153c78f7242fdf7e1a), [`c2f0b7f`](https://github.com/mastra-ai/mastra/commit/c2f0b7f1370f4428d165f51f0d1d9a48331cc257)]:
+  - @mastra/core@1.48.0-alpha.8
+
 ## 1.2.3-alpha.13
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.3-alpha.13",
+  "version": "1.2.3-alpha.15",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.48.0-alpha.7",
+    "@mastra/core": "1.48.0-alpha.8",
     "@mastra/mcp": "^1.12.1-alpha.0"
   },
   "devDependencies": {
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
-    "@internal/types-builder": "0.0.84",
     "@internal/lint": "0.0.109",
-    "@mastra/core": "1.48.0-alpha.7"
+    "@internal/types-builder": "0.0.84",
+    "@mastra/core": "1.48.0-alpha.8"
   },
   "homepage": "https://mastra.ai",
   "repository": {