@mastra/mcp-docs-server 0.13.34 → 0.13.35-alpha.0

package/.docs/organized/code-examples/memory-with-mongodb.md

@@ -0,0 +1,208 @@
+### package.json
+```json
+{
+  "name": "memory-with-mongodb",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "latest",
+    "@mastra/memory": "latest",
+    "@mastra/mongodb": "latest"
+  },
+  "devDependencies": {
+    "dotenv": "^17.0.0",
+    "tsx": "^4.19.3"
+  }
+}
+```
+
+### chat.ts
+```typescript
+import { randomUUID } from 'crypto';
+import Readline from 'readline';
+
+import 'dotenv/config';
+
+import { mastra } from './mastra';
+
+const agent = mastra.getAgent('memoryAgent');
+
+let thread = randomUUID();
+// use this to play with a long running conversation. comment it out to get a new thread id every time
+thread = `39873fbf-84d6-425e-8c1b-8afd798d72a4`;
+// thread = `12569b14-3e16-4e31-8130-8d9676f1932c`;
+console.log(thread);
+
+const resource = 'SOME_USER_ID';
+
+async function logRes(res: Awaited<ReturnType<typeof agent.stream>>) {
+  console.log(`\n🤖 Agent:`);
+  for await (const chunk of res.textStream) {
+    process.stdout.write(chunk);
+  }
+  console.log(`\n\n`);
+}
+
+async function main() {
+  await logRes(
+    await agent.stream(
+      [
+        {
+          role: 'system',
+          content: `Chat with user started now ${new Date().toISOString()}. Don't mention this message. This means some time may have passed between this message and the one before. The user left and came back again. Say something to start the conversation up again.`,
+        },
+      ],
+      { memory: { resource, thread } },
+    ),
+  );
+
+  const rl = Readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  while (true) {
+    const prompt: string = await new Promise(res => {
+      rl.question('Message: ', answer => {
+        res(answer);
+      });
+    });
+
+    await logRes(
+      await agent.stream(prompt, {
+        memory: { thread, resource },
+      }),
+    );
+  }
+}
+
+main();
+
+```
+
+### index.ts
+```typescript
+import { randomUUID } from 'crypto';
+
+import { mastra } from './mastra';
+
+function log(message: string) {
+  console.log(`\n>>Prompt: ${message}`);
+  return message;
+}
+
+const agent = mastra.getAgent('chefAgent');
+const threadId = randomUUID();
+const resourceId = 'SOME_USER_ID';
+
+async function logRes(res: Awaited<ReturnType<typeof agent.stream>>) {
+  console.log(`\n👨‍🍳 Chef:`);
+  for await (const chunk of res.textStream) {
+    process.stdout.write(chunk);
+  }
+  console.log(`\n\n`);
+}
+
+async function main() {
+  await logRes(
+    await agent.stream(
+      log(
+        'In my kitchen I have: pasta, canned tomatoes, garlic, olive oil, and some dried herbs (basil and oregano). What can I make? Please keep your answer brief, only give me the high level steps.',
+      ),
+      {
+        threadId,
+        resourceId,
+      },
+    ),
+  );
+
+  await logRes(
+    await agent.stream(
+      log(
+        "Now I'm over at my friend's house, and they have: chicken thighs, coconut milk, sweet potatoes, and some curry powder.",
+      ),
+      {
+        threadId,
+        resourceId,
+      },
+    ),
+  );
+
+  await logRes(
+    await agent.stream(log('What did we cook before I went to my friends house?'), {
+      threadId,
+      resourceId,
+      memoryOptions: {
+        lastMessages: 3,
+      },
+    }),
+  );
+
+  process.exit(0);
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+import { MongoDBStore, MongoDBVector } from '@mastra/mongodb';
+
+// This URI must be an Atlas MongoDB deployment in order to work with vector search
+// in the format mongodb+srv://<username>:<password>@<cluster>.mongodb.net
+const uri = process.env.MONGODB_URI;
+const dbName = process.env.MONGODB_DB_NAME || 'mastra_memory';
+
+export const memory = new Memory({
+  storage: new MongoDBStore({
+    url: uri,
+    dbName,
+  }),
+  vector: new MongoDBVector({
+    uri,
+    dbName,
+  }),
+  options: {
+    lastMessages: 10,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2,
+    },
+  },
+  embedder: openai.embedding('text-embedding-3-small'),
+});
+
+export const chefAgent = new Agent({
+  name: 'chefAgent',
+  instructions:
+    'You are Michel, a practical and experienced home chef who helps people cook great meals with whatever ingredients they have available. Your first priority is understanding what ingredients and equipment the user has access to, then suggesting achievable recipes. You explain cooking steps clearly and offer substitutions when needed, maintaining a friendly and encouraging tone throughout.',
+  model: openai('gpt-4o'),
+  memory,
+});
+
+export const memoryAgent = new Agent({
+  name: 'Memory Agent',
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions. You may have conversations that last hours, days, months, or years. If you don't know it already you should ask for the users name and some info about them.",
+  model: openai('gpt-4o'),
+  memory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import 'dotenv/config';
+
+import { chefAgent, memoryAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { chefAgent, memoryAgent },
+});
+
+```

package/.docs/raw/getting-started/project-structure.mdx

@@ -63,7 +63,7 @@ Top-level files define how your Mastra project is configured, built, and connect
 | File                  | Description |
 | --------------------- | ------------ |
 | `src/mastra/index.ts` | Central entry point where you configure and initialize Mastra. |
-| `.env.example`        | Template for environment variables — copy and rename to `.env` to add your secret [model provider](/models) keys. |
+| `.env.example`        | Template for environment variables - copy and rename to `.env` to add your secret [model provider](/models) keys. |
 | `package.json`        | Defines project metadata, dependencies, and available npm scripts. |
 | `tsconfig.json`       | Configures TypeScript options such as path aliases, compiler settings, and build output. |
 

package/.docs/raw/getting-started/studio.mdx

@@ -10,15 +10,15 @@ import { Callout } from "nextra/components";
 
 # Playground
 
-Playground helps you build agents quickly. It provides an interactive UI for testing your agents and workflows, along with a REST API that exposes your Mastra application as a local service. This lets you start building without having to integrate Mastra into your project right away.
+Playground provides an interactive UI for building and testing your agents, along with a REST API that exposes your Mastra application as a local service. This lets you start building without worrying about integration right away.
 
-As your project evolves, Playground enables you to iterate quickly. Features like Observability and Scorers give you visibility into performance at every stage of development.
+As your project evolves, Playground's development environment helps you iterate on your agent quickly. Meanwhile, Observability and Scorer features give you visibility into performance at every stage.
 
-To get started, run Playground locally using the instructions below, or [deploy to Mastra Cloud](/docs/mastra-cloud/setting-up) to access the Playground remotely and collaborate with your team.
+To get started, run Playground locally using the instructions below, or [deploy to Mastra Cloud](https://mastra.ai/docs/mastra-cloud/setting-up) to collaborate with your team.
 
 <YouTube id="spGlcTEjuXY" startTime={126}/>
 
-## Launch Playground
+## Start Playground
 
 If you created your application with `create mastra`, start the local development server using the `dev` script. You can also run it directly with `mastra dev`.
 

package/.docs/raw/memory/overview.mdx

@@ -69,7 +69,7 @@ All memory types are [thread-scoped](./working-memory.mdx#thread-scoped-memory-d
 
 To persist and recall information between conversations, memory requires a storage adapter.
 
-Supported options include [LibSQL](/examples/memory/memory-with-libsql), [Postgres](/examples/memory/memory-with-pg), and [Upstash](/examples/memory/memory-with-upstash)
+Supported options include [LibSQL](/docs/memory/storage/memory-with-libsql), [MongoDB](/docs/memory/storage/memory-with-mongodb), [Postgres](/docs/memory/storage/memory-with-pg), and [Upstash](/docs/memory/storage/memory-with-upstash)
 
 We use LibSQL out of the box because it is file-based or in-memory, so it is easy to install and works well with the playground.
 

package/.docs/raw/memory/semantic-recall.mdx

@@ -92,9 +92,10 @@ const agent = new Agent({
 
 **Storage/vector code Examples**:
 
-- [LibSQL](/examples/memory/memory-with-libsql)
-- [Postgres](/examples/memory/memory-with-pg)
-- [Upstash](/examples/memory/memory-with-upstash)
+- [LibSQL](/docs/memory/storage/memory-with-libsql)
+- [MongoDB](/docs/memory/storage/memory-with-mongodb)
+- [Postgres](/docs/memory/storage/memory-with-pg)
+- [Upstash](/docs/memory/storage/memory-with-upstash)
 
 ### Embedder configuration
 

package/.docs/raw/memory/storage/memory-with-libsql.mdx

@@ -0,0 +1,141 @@
+---
+title: "Example: Memory with LibSQL | Memory | Mastra Docs"
+description: Example for how to use Mastra's memory system with LibSQL storage and vector database backend.
+---
+
+# Memory with LibSQL
+
+This example demonstrates how to use Mastra's memory system with LibSQL as the storage backend.
+
+## Prerequisites
+
+This example uses the `openai` model. Make sure to add `OPENAI_API_KEY` to your `.env` file.
+
+```bash filename=".env" copy
+OPENAI_API_KEY=<your-api-key>
+```
+
+And install the following package:
+
+```bash copy
+npm install @mastra/libsql
+```
+
+## Adding memory to an agent
+
+To add LibSQL memory to an agent use the `Memory` class and create a new `storage` key using `LibSQLStore`. The `url` can either by a remote location, or a local file system resource.
+
+```typescript filename="src/mastra/agents/example-libsql-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const libsqlAgent = new Agent({
+  name: "libsql-agent",
+  instructions: "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    storage: new LibSQLStore({
+      url: "file:libsql-agent.db"
+    }),
+    options: {
+      threads: {
+        generateTitle: true
+      }
+    }
+  })
+});
+```
+
+## Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash copy
+npm install @mastra/fastembed
+```
+
+Add the following to your agent:
+
+```typescript filename="src/mastra/agents/example-libsql-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
+import { fastembed } from "@mastra/fastembed";
+
+export const libsqlAgent = new Agent({
+  name: "libsql-agent",
+  instructions: "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    storage: new LibSQLStore({
+      url: "file:libsql-agent.db"
+    }),
+    vector: new LibSQLVector({
+      connectionUrl: "file:libsql-agent.db"
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2
+      },
+      threads: {
+        generateTitle: true
+      }
+    }
+  })
+});
+```
+
+## Usage example
+
+Use `memoryOptions` to scope recall for this request. Set `lastMessages: 5` to limit recency-based recall, and use `semanticRecall` to fetch the `topK: 3` most relevant messages, including `messageRange: 2` neighboring messages for context around each match.
+
+```typescript filename="src/test-libsql-agent.ts" showLineNumbers copy
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("libsqlAgent");
+
+const message = await agent.stream("My name is Mastra", {
+  memory: {
+    thread: threadId,
+    resource: resourceId
+  }
+});
+
+await message.textStream.pipeTo(new WritableStream());
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId
+  },
+  memoryOptions: {
+    lastMessages: 5,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2
+    }
+  }
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+
+## Related
+
+- [Calling Agents](../agents/calling-agents.mdx)

package/.docs/raw/memory/storage/memory-with-pg.mdx

@@ -0,0 +1,138 @@
+---
+title: "Example: Memory with PostgreSQL | Memory | Mastra Docs"
+description: Example for how to use Mastra's memory system with PostgreSQL storage and vector capabilities.
+---
+
+# Memory with Postgres
+
+This example demonstrates how to use Mastra's memory system with PostgreSQL as the storage backend.
+
+## Prerequisites
+
+This example uses the `openai` model and requires a PostgreSQL database with the `pgvector` extension. Make sure to add the following to your `.env` file:
+
+```bash filename=".env" copy
+OPENAI_API_KEY=<your-api-key>
+DATABASE_URL=<your-connection-string>
+```
+
+And install the following package:
+
+```bash copy
+npm install @mastra/pg
+```
+
+## Adding memory to an agent
+
+To add PostgreSQL memory to an agent use the `Memory` class and create a new `storage` key using `PostgresStore`. The `connectionString` can either be a remote location, or a local database connection.
+
+```typescript filename="src/mastra/agents/example-pg-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { PostgresStore } from "@mastra/pg";
+
+export const pgAgent = new Agent({
+  name: "pg-agent",
+  instructions: "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    storage: new PostgresStore({
+      connectionString: process.env.DATABASE_URL!
+    }),
+    options: {
+      threads: {
+        generateTitle: true
+      }
+    }
+  })
+});
+```
+
+## Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash copy
+npm install @mastra/fastembed
+```
+
+Add the following to your agent:
+
+```typescript filename="src/mastra/agents/example-pg-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { PostgresStore, PgVector } from "@mastra/pg";
+import { fastembed } from "@mastra/fastembed";
+
+export const pgAgent = new Agent({
+  name: "pg-agent",
+  instructions: "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    storage: new PostgresStore({
+      connectionString: process.env.DATABASE_URL!
+    }),
+    vector: new PgVector({
+      connectionString: process.env.DATABASE_URL!
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2
+      }
+    }
+  })
+});
+```
+
+## Usage example
+
+Use `memoryOptions` to scope recall for this request. Set `lastMessages: 5` to limit recency-based recall, and use `semanticRecall` to fetch the `topK: 3` most relevant messages, including `messageRange: 2` neighboring messages for context around each match.
+
+```typescript filename="src/test-pg-agent.ts" showLineNumbers copy
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("pgAgent");
+
+const message = await agent.stream("My name is Mastra", {
+  memory: {
+    thread: threadId,
+    resource: resourceId
+  }
+});
+
+await message.textStream.pipeTo(new WritableStream());
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId
+  },
+  memoryOptions: {
+    lastMessages: 5,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2
+    }
+  }
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## Related
+
+- [Calling Agents](../agents/calling-agents.mdx)

package/.docs/raw/memory/storage/memory-with-upstash.mdx

@@ -0,0 +1,147 @@
+---
+title: "Example: Memory with Upstash | Memory | Mastra Docs"
+description: Example for how to use Mastra's memory system with Upstash Redis storage and vector capabilities.
+---
+
+# Memory with Upstash
+
+This example demonstrates how to use Mastra's memory system with Upstash as the storage backend.
+
+## Prerequisites
+
+This example uses the `openai` model and requires both Upstash Redis and Upstash Vector services. Make sure to add the following to your `.env` file:
+
+```bash filename=".env" copy
+OPENAI_API_KEY=<your-api-key>
+UPSTASH_REDIS_REST_URL=<your-redis-url>
+UPSTASH_REDIS_REST_TOKEN=<your-redis-token>
+UPSTASH_VECTOR_REST_URL=<your-vector-index-url>
+UPSTASH_VECTOR_REST_TOKEN=<your-vector-index-token>
+```
+
+You can get your Upstash credentials by signing up at [upstash.com](https://upstash.com) and creating both Redis and Vector databases.
+
+And install the following package:
+
+```bash copy
+npm install @mastra/upstash
+```
+
+## Adding memory to an agent
+
+To add Upstash memory to an agent use the `Memory` class and create a new `storage` key using `UpstashStore` and a new `vector` key using `UpstashVector`. The configuration can point to either a remote service or a local setup.
+
+```typescript filename="src/mastra/agents/example-upstash-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { UpstashStore } from "@mastra/upstash";
+
+export const upstashAgent = new Agent({
+  name: "upstash-agent",
+  instructions: "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    storage: new UpstashStore({
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!
+    }),
+    options: {
+      threads: {
+        generateTitle: true
+      }
+    }
+  })
+});
+```
+
+
+## Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash copy
+npm install @mastra/fastembed
+```
+
+Add the following to your agent:
+
+```typescript filename="src/mastra/agents/example-upstash-agent.ts" showLineNumbers copy
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { UpstashStore, UpstashVector } from "@mastra/upstash";
+import { fastembed } from "@mastra/fastembed";
+
+export const upstashAgent = new Agent({
+  name: "upstash-agent",
+  instructions: "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    storage: new UpstashStore({
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!
+    }),
+    vector: new UpstashVector({
+      url: process.env.UPSTASH_VECTOR_REST_URL!,
+      token: process.env.UPSTASH_VECTOR_REST_TOKEN!
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2
+      }
+    }
+  })
+});
+```
+
+## Usage example
+
+Use `memoryOptions` to scope recall for this request. Set `lastMessages: 5` to limit recency-based recall, and use `semanticRecall` to fetch the `topK: 3` most relevant messages, including `messageRange: 2` neighboring messages for context around each match.
+
+```typescript filename="src/test-upstash-agent.ts" showLineNumbers copy
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("upstashAgent");
+
+const message = await agent.stream("My name is Mastra", {
+  memory: {
+    thread: threadId,
+    resource: resourceId
+  }
+});
+
+await message.textStream.pipeTo(new WritableStream());
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId
+  },
+  memoryOptions: {
+    lastMessages: 5,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2
+    }
+  }
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## Related
+
+- [Calling Agents](../agents/calling-agents.mdx)