@mastra/mcp-docs-server 1.1.1-alpha.1 → 1.1.1

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

@@ -24,21 +24,11 @@ export const agent = new Agent({
 });
 ```
 
-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",
-    },
-  },
-});
-```
+That's it. The agent now has humanlike long-term memory that persists across conversations.
 
 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 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.
+> **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.
 
 ## Benefits
 
@@ -87,9 +77,7 @@ 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.
 
-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.
+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.
 
 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.
 
@@ -112,14 +100,9 @@ See [model configuration](https://mastra.ai/reference/memory/observational-memor
 Each thread has its own observations.
 
 ```typescript
-const memory = new Memory({
-  options: {
-    observationalMemory: {
-      model: "google/gemini-2.5-flash",
-      scope: "thread",
-    },
-  },
-});
+observationalMemory: {
+  scope: "thread",
+}
 ```
 
 ### Resource scope
@@ -127,14 +110,9 @@ const memory = new Memory({
 Observations are shared across all threads for a resource (typically a user). Enables cross-conversation memory.
 
 ```typescript
-const memory = new Memory({
-  options: {
-    observationalMemory: {
-      model: "google/gemini-2.5-flash",
-      scope: "resource",
-    },
-  },
-});
+observationalMemory: {
+  scope: "resource",
+}
 ```
 
 > **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.
@@ -147,7 +125,6 @@ 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,
@@ -157,58 +134,12 @@ 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/.docs/guides/guide/code-review-bot.md

@@ -0,0 +1,221 @@
+# Building a Code Review Bot
+
+In this guide, you'll build a code review bot that automatically reviews pull requests using workspace skills. The bot loads coding standards from skill files and provides structured feedback. You'll learn how to create a workspace with a skills directory, define an [Agent Skill](https://agentskills.io) with review instructions and reference files, and connect it to an agent that performs automated reviews.
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](https://mastra.ai/models)
+- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
+
+## Create the workspace
+
+In your `src/mastra/index.ts` file, import the [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) and [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) classes. On the `Workspace` instance, configure the `skills` option to point to a skills directory. The `skills` directory will live inside the filesystem's `basePath`.
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { resolve } from 'node:path';
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: resolve(import.meta.dirname, '../../workspace'),
+  }),
+  skills: ['/skills'],
+});
+
+export const mastra = new Mastra({
+  workspace,
+});
+```
+
+At the root of your project, create a new folder called `workspace`. Inside that, create a `skills` folder. This is where you'll define the code standards skill in the next step.
+
+## Create the code standards skill
+
+Skills are structured directories containing a `SKILL.md` file with instructions for the agent. The code standards skill defines the review process and references a style guide.
+
+Inside `workspace/skills`, create a new folder called `code-standards`. Create a file called `SKILL.md` and add the review instructions.
+
+```markdown
+---
+name: code-standards
+description: Automated code review standards and checks
+---
+
+# Code Review Standards
+
+Review code systematically using these steps:
+
+1. **Critical Issues**: Security vulnerabilities, memory leaks, logic bugs, missing error handling
+2. **Code Quality**: Functions over 50 lines, code duplication, confusing names, missing types
+3. **Style Guide**: Check references/style-guide.md for naming and organization
+4. **Linting**: Flag common issues like use of `var`, leftover `console.log` statements, and `debugger` statements
+
+Provide feedback in this format:
+
+**Summary**: One sentence overview
+
+**Critical Issues**: List with line numbers
+
+**Suggestions**: Improvements that would help
+
+**Positive Notes**: What the code does well
+```
+
+Inside `workspace/skills/code-standards`, create a `references` folder to hold reference materials for the skill. Author a style guide file that outlines the project's coding conventions with the file name `style-guide.md`.
+
+````markdown
+# Style Guide
+
+## Naming
+
+- Variables/Functions: `camelCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Files: `kebab-case.ts`
+- Booleans: Start with `is`, `has`, `should`
+
+## Code Organization
+
+```typescript
+// 1. Imports
+import { foo } from 'bar';
+
+// 2. Constants
+const MAX_SIZE = 100;
+
+// 3. Types
+interface User { id: string; }
+
+// 4. Functions
+function doSomething() {}
+
+// 5. Exports
+export { doSomething };
+```
+
+## Error Handling
+
+Always handle errors explicitly - never silently catch.
+
+## Comments
+
+Write "why" not "what".
+````
+
+## Create the review agent
+
+Now it's time to create the code review bot agent that uses the code-standards skill. Create a new file at `src/mastra/agents/code-reviewer.ts` and define the agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+
+export const codeReviewer = new Agent({
+  id: 'code-reviewer',
+  name: 'Code Review Bot',
+  instructions: `You are an automated code reviewer.
+
+When asked to review code:
+1. Activate the 'code-standards' skill
+2. Follow the review process from the skill
+3. Check against the style guide in skill references
+4. Be constructive and specific with line numbers`,
+  model: 'openai/gpt-4o',
+});
+```
+
+Define the agent by importing it inside `src/mastra/index.ts` and registering it with the `Mastra` instance:
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { resolve } from 'node:path';
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
+import { codeReviewer } from './agents/code-reviewer';
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: resolve(import.meta.dirname, '../../workspace'),
+  }),
+  skills: ['/skills'],
+});
+
+export const mastra = new Mastra({
+  workspace,
+  agents: { codeReviewer },
+});
+```
+
+## Test the bot
+
+Start Mastra Studio and interact with the code review bot to see it in action.
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+Open [localhost:4111](http://localhost:4111) and navigate to the code reviewer agent.
+
+Inside the chat input, provide a code snippet for review, such as:
+
+```text
+Review this code:
+
+function getData(id) {
+  var result = fetch('/api/data/' + id);
+  console.log(result);
+  return result;
+}
+```
+
+The bot should activate the `code-standards` skill and provide structured feedback. Since agent responses are non-deterministic, your output may vary, but you should see something similar to:
+
+```md
+**Summary**: Function has several issues with variable declaration,
+debugging statements, and missing error handling.
+
+**Critical Issues**:
+- Missing error handling for fetch (line 2)
+- No async/await for asynchronous operation (line 2)
+
+**Suggestions**:
+- Use const instead of var (line 2)
+- Remove console.log before committing (line 3)
+- Add TypeScript type for id parameter
+- Use template literals instead of concatenation
+
+**Positive Notes**:
+- Function name is clear and descriptive
+```
+
+## Next steps
+
+You can extend this bot to:
+
+- Add skills for different languages or frameworks
+- Create skills for security checks and performance reviews
+- Integrate with GitHub Actions for automatic PR reviews
+- Build a PR comment bot that leaves inline feedback
+
+Learn more:
+
+- [Agent Skills spec](https://agentskills.io)

package/.docs/guides/guide/dev-assistant.md

@@ -0,0 +1,304 @@
+# Building a Dev Assistant
+
+In this guide, you'll build a complete development assistant that combines all workspace features:
+
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem) for file management
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox) for code execution
+- [Skills](https://mastra.ai/docs/workspace/skills) for coding standards
+- [Search](https://mastra.ai/docs/workspace/search) for finding examples
+
+You'll set up a workspace with a sample project, add coding standards as a skill, and create an agent that writes code following TDD practices. By the end, you'll have an agent that can read existing code, write new implementations, run tests in a sandbox, and iterate based on results.
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](https://mastra.ai/models)
+- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
+
+### Install vitest
+
+The dev assistant will use [Vitest](https://vitest.dev/) to run tests inside the workspace sandbox. Install it as a dev dependency in your project:
+
+**npm**:
+
+```bash
+npm install -D vitest
+```
+
+**pnpm**:
+
+```bash
+pnpm add -D vitest
+```
+
+**Yarn**:
+
+```bash
+yarn add --dev vitest
+```
+
+**Bun**:
+
+```bash
+bun add --dev vitest
+```
+
+## Set up the workspace
+
+The workspace uses a local filesystem to manage documentation files. The agent reads and writes files within the workspace directory. In your `src/mastra/index.ts` file, import the [`Workspace`](https://mastra.ai/reference/workspace/workspace-class), [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem), and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) classes.
+
+Additionally, enable BM25 search indexing and load skills from the `skills` directory.
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { resolve } from 'node:path';
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
+  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
+  skills: ['/skills'],
+  bm25: true,
+  autoIndexPaths: ['/docs', '/src'],
+});
+
+export const mastra = new Mastra({
+  workspace,
+});
+```
+
+At the root of your project, create a new folder called `workspace`. This is where all files will be stored and managed by the agent.
+
+## Add sample project files
+
+The workspace uses the following folder structure:
+
+- `workspace/src/`: Source code for the sample project
+- `workspace/tests/`: Test files
+- `workspace/docs/`: Project documentation
+- `workspace/skills/`: Coding standards and guidelines as [Agent Skills](https://agentskills.io)
+
+Get started by creating a `workspace/src/utils/string-helpers.ts` file with some utility functions, and a corresponding test file in `workspace/tests/string-helpers.test.ts`.
+
+```typescript
+export function capitalize(str: string): string {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export function slugify(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-');
+}
+```
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { capitalize, slugify } from '../src/utils/string-helpers';
+
+describe('String Helpers', () => {
+  describe('capitalize', () => {
+    it('capitalizes first letter', () => {
+      expect(capitalize('hello')).toBe('Hello');
+    });
+  });
+
+  describe('slugify', () => {
+    it('converts to lowercase and replaces spaces', () => {
+      expect(slugify('Hello World')).toBe('hello-world');
+    });
+  });
+});
+```
+
+Create a skill definition at `workspace/skills/coding-standards/SKILL.md`. This tells the agent how to write and test code:
+
+```markdown
+---
+name: coding-standards
+description: Project coding standards and testing guidelines
+---
+
+# Coding Standards
+
+## Code Quality
+- Functions under 50 lines
+- Use descriptive variable names
+- Always add TypeScript types
+
+## Testing
+- Test all exported functions
+- Use AAA pattern: Arrange, Act, Assert
+- Cover happy paths and edge cases
+
+## Before Committing
+1. Write implementation
+2. Write comprehensive tests
+3. Run tests: `npm test`
+4. All tests must pass
+```
+
+Create a reference file at `workspace/skills/coding-standards/references/testing-guide.md` with detailed testing patterns:
+
+````markdown
+# Testing Guide
+
+## AAA Pattern
+
+```typescript
+it('descriptive test name', () => {
+  // Arrange: Set up test data
+  const input = 'test';
+
+  // Act: Execute the function
+  const result = doSomething(input);
+
+  // Assert: Verify the result
+  expect(result).toBe('expected');
+});
+```
+
+## What to Test
+
+- Happy paths (normal inputs)
+- Edge cases (empty, null, boundary values)
+- Error cases (invalid inputs, exceptions)
+````
+
+## Create the dev assistant
+
+With the workspace set up, it's time to create the development assistant agent. This agent will have instructions for adding new features using test-driven development (TDD).
+
+Create a new file `src/mastra/agents/dev-assistant.ts` and define the agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+
+export const devAssistant = new Agent({
+  id: 'dev-assistant',
+  name: 'Dev Assistant',
+  instructions: `You are a development assistant.
+
+When adding features:
+1. Activate 'coding-standards' skill
+2. Search workspace for similar code examples
+3. Write the implementation following standards
+4. Write comprehensive tests. Leave existing tests in place, only add your new tests
+5. Execute the command \`npx vitest run\` to validate that all tests pass
+6. Update documentation if needed
+
+For every new feature: Write code → Write tests → Run tests → Update docs
+
+Always explain your reasoning and steps.`,
+  model: 'openai/gpt-4o',
+});
+```
+
+Define the agent by importing it inside `src/mastra/index.ts` and registering it with the `Mastra` instance:
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { resolve } from 'node:path';
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
+import { devAssistant } from './agents/dev-assistant';
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
+  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
+  skills: ['/skills'],
+  bm25: true,
+  autoIndexPaths: ['/docs', '/src'],
+});
+
+export const mastra = new Mastra({
+  workspace,
+  agents: { devAssistant },
+});
+```
+
+## Test the assistant
+
+Start Mastra Studio and interact with the agent to see it in action.
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+Open [localhost:4111](http://localhost:4111) and navigate to the dev assistant.
+
+Try asking the agent to add a new function using TDD:
+
+```text
+Add a 'truncate' function to string-helpers.ts that shortens strings to a max length. Add '...' if truncated.
+
+Follow TDD: write tests first, then implementation.
+```
+
+Since agent responses are non-deterministic, the exact output will vary. However, you should see the agent follow a process similar to this:
+
+1. Activate the coding-standards skill
+
+2. Search the workspace for similar code patterns
+
+3. Write tests first, for example:
+
+   ```typescript
+   describe('truncate', () => {
+     it('truncates long strings', () => {
+       expect(truncate('Hello World', 5)).toBe('He...');
+     });
+
+     it('keeps short strings unchanged', () => {
+       expect(truncate('Hi', 10)).toBe('Hi');
+     });
+
+     it('handles edge cases', () => {
+       expect(truncate('', 5)).toBe('');
+     });
+   });
+   ```
+
+4. Write the implementation, for example:
+
+   ```typescript
+   export function truncate(str: string, maxLength: number): string {
+     if (!str || maxLength < 0) return str;
+     if (str.length <= maxLength) return str;
+     if (maxLength === 0) return '...';
+     return str.slice(0, maxLength - 3) + '...';
+   }
+   ```
+
+5. Run tests and verify they pass
+
+## Next steps
+
+You can extend this assistant to:
+
+- Add more skills for different languages or frameworks
+- Create specialized agents for backend, frontend, or DevOps
+- Integrate with GitHub for automated PR reviews
+- Build CI/CD automation
+- Add multi-agent workflows