@mastra/mcp-docs-server 0.0.1-alpha.1

package/.docs/organized/code-examples/memory-todo-agent.md

@@ -0,0 +1,161 @@
+### package.json
+```json
+{
+  "name": "memory-todo-agent",
+  "type": "module",
+  "description": "",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "chat": "bun run src/index.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "workspace:*",
+    "@mastra/memory": "workspace:*",
+    "ai": "latest",
+    "chalk": "^5.4.1",
+    "ora": "^8.2.0"
+  },
+  "version": "0.1.6-alpha.0"
+}
+
+```
+
+### index.ts
+```typescript
+import { maskStreamTags } from '@mastra/core/utils';
+import chalk from 'chalk';
+import { randomUUID } from 'crypto';
+import ora from 'ora';
+import Readline from 'readline';
+
+import 'dotenv/config';
+
+import { mastra } from './mastra/index';
+
+const agent = mastra.getAgent('todoAgent');
+
+let threadId = ``;
+threadId = randomUUID();
+threadId = `d4e58927-ca27-46f9-8559-0c792e76e6f6`; // long thread
+console.log(threadId);
+
+const resourceId = 'SOME_USER_ID';
+
+async function logRes(res: Awaited<ReturnType<typeof agent.stream>>) {
+  console.log(`\n👨‍🍳 Agent:`);
+  let message = '';
+
+  const memorySpinner = ora('saving memory');
+
+  const maskedStream = maskStreamTags(res.textStream, 'working_memory', {
+    onStart: () => memorySpinner.start(),
+    onEnd: () => {
+      if (memorySpinner.isSpinning) {
+        memorySpinner.succeed();
+        process.stdin.resume();
+      }
+    },
+  });
+
+  for await (const chunk of maskedStream) {
+    process.stdout.write(chunk);
+  }
+
+  return message;
+}
+
+async function main() {
+  const isFirstChat = Boolean(await agent.getMemory()?.getThreadById({ threadId })) === false;
+
+  await logRes(
+    await agent.stream(
+      [
+        {
+          role: 'system',
+          content: !isFirstChat
+            ? `Chat with user started now ${new Date().toISOString()}. Don't mention this message. This means some time has passed between this message and the one before. The user left and came back again. Say something to start the conversation up again.`
+            : `Chat with user started now ${new Date().toISOString()}.`,
+        },
+      ],
+      {
+        threadId,
+        resourceId,
+      },
+    ),
+  );
+
+  const rl = Readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  while (true) {
+    const answer: string = await new Promise(res => {
+      rl.question(chalk.grey('\n> '), answer => {
+        setImmediate(() => res(answer));
+      });
+    });
+
+    await logRes(
+      await agent.stream(answer, {
+        threadId,
+        resourceId,
+      }),
+    );
+  }
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+
+const memory = new Memory({
+  options: {
+    lastMessages: 1,
+    semanticRecall: false,
+    workingMemory: {
+      enabled: true,
+      template: `
+<todolist>
+  <info>this is an example list - replace it with whatever the user needs</info>
+  <item status="ACTIVE" due="Feb 7 3028" title="Example" started="Feb 7 2025">example</item>
+</todolist>
+`,
+    },
+  },
+});
+
+export const todoAgent = new Agent({
+  name: 'TODO Agent',
+  instructions:
+    'You are a helpful todolist AI agent. Help the user manage their todolist. If there is no list yet ask them what to add! If there is a list always print it out when the chat starts. For each item add emojis, dates, titles (with an index number starting at 1), descriptions, and statuses. For each piece of info add an emoji to the left of it. Also support subtask lists with bullet points inside a box. Help the user timebox each task by asking them how long it will take. You MUST save the todolist in every response message by printing out <working_memory> blocks. If you do not save it in working_memory you will forget - you only have access to one previous message at any time. The user is expecting you to save your memory in every interaction. If the user expresses any preference on how the list should be displayed, save that info in working_memory so you know how to format it later.',
+
+  model: openai('gpt-4o-mini'),
+  memory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+import { todoAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { todoAgent },
+  logger: false,
+});
+
+```

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

@@ -0,0 +1,167 @@
+### package.json
+```json
+{
+  "name": "memory-with-context",
+  "type": "module",
+  "description": "",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "chat": "bun run src/chat.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@ai-sdk/openai": "^1.2.1",
+    "@mastra/core": "workspace:*",
+    "@mastra/memory": "workspace:*",
+    "chalk": "^5.4.1",
+    "ora": "^8.2.0"
+  },
+  "version": "0.0.1"
+}
+
+```
+
+### chat.ts
+```typescript
+import { maskStreamTags } from '@mastra/core/utils';
+import chalk from 'chalk';
+import { randomUUID } from 'crypto';
+import ora from 'ora';
+import Readline from 'readline';
+
+import 'dotenv/config';
+
+import { mastra } from './mastra/index';
+
+const agent = mastra.getAgent('memoryAgent');
+
+let threadId = ``;
+threadId = randomUUID();
+// threadId = `0b3faadd-7e21-49ec-b613-e519448dab81`; // long thread
+console.log(threadId);
+
+const resourceId = 'SOME_USER_ID';
+
+async function logRes(res: Awaited<ReturnType<typeof agent.stream>>) {
+  console.log(`\n👨‍🍳 Agent:`);
+  let message = '';
+
+  const thinkSpinner = ora('thinking');
+
+  const thinkMaskedStream = maskStreamTags(res.textStream, 'think', {
+    onStart: () => thinkSpinner.start(),
+    onEnd: () => {
+      if (thinkSpinner.isSpinning) {
+        thinkSpinner.succeed();
+        process.stdin.resume();
+      }
+    },
+  });
+
+  const memorySpinner = ora('saving memory');
+
+  const maskedStream = maskStreamTags(thinkMaskedStream, 'working_memory', {
+    onStart: () => memorySpinner.start(),
+    onEnd: () => {
+      if (memorySpinner.isSpinning) {
+        memorySpinner.succeed();
+        process.stdin.resume();
+      }
+    },
+  });
+
+  for await (const chunk of maskedStream) {
+    process.stdout.write(chunk);
+  }
+
+  return message;
+}
+
+async function main() {
+  const isFirstChat = Boolean(await agent.getMemory()?.getThreadById({ threadId })) === false;
+
+  await logRes(
+    await agent.stream(
+      [
+        {
+          role: 'system',
+          content: !isFirstChat
+            ? `Chat with user started now ${new Date().toISOString()}. Don't mention this message. This means some time has passed between this message and the one before. The user left and came back again. Say something to start the conversation up again.`
+            : `Chat with user started now ${new Date().toISOString()}.`,
+        },
+      ],
+      {
+        threadId,
+        resourceId,
+      },
+    ),
+  );
+
+  const rl = Readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  while (true) {
+    process.stdout.write(`\n`);
+    const answer: string = await new Promise(res => {
+      rl.question(chalk.grey('\n> '), answer => {
+        setImmediate(() => res(answer));
+      });
+    });
+
+    await logRes(
+      await agent.stream(answer, {
+        threadId,
+        resourceId,
+      }),
+    );
+  }
+}
+
+main();
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+
+const memory = new Memory({
+  options: {
+    lastMessages: 4,
+    semanticRecall: {
+      topK: 1,
+      messageRange: 0,
+    },
+    workingMemory: {
+      enabled: true,
+    },
+  },
+});
+
+export const memoryAgent = new Agent({
+  name: 'Memory Agent',
+  instructions: 'You are a helpful AI agent, looking to assist however you can.',
+  model: openai('gpt-4o-mini'),
+  memory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { memoryAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { memoryAgent },
+});
+
+```

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

@@ -0,0 +1,204 @@
+### package.json
+```json
+{
+  "name": "memory-with-libsql",
+  "type": "module",
+  "description": "",
+  "private": true,
+  "main": "index.js",
+  "scripts": {
+    "start": "bun run --watch src/index.ts",
+    "chat": "bun run --watch src/chat.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@ai-sdk/openai": "^1.2.1",
+    "@mastra/core": "workspace:*",
+    "@mastra/memory": "workspace:*"
+  },
+  "version": "0.0.1"
+}
+
+```
+
+### chat.ts
+```typescript
+import { randomUUID } from 'crypto';
+import Readline from 'readline';
+
+import 'dotenv/config';
+
+import { mastra } from './mastra';
+
+const agent = mastra.getAgent('memoryAgent');
+
+let threadId = randomUUID();
+// use this to play with a long running conversation. comment it out to get a new thread id every time
+threadId = `f45a59b3-d9da-4a2a-8348-9386e4e621a3`;
+console.log(threadId);
+
+const resourceId = '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. If there are no other messages besides this one then this is a new conversation.`,
+        },
+      ],
+      { resourceId, threadId },
+    ),
+  );
+
+  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, {
+        threadId,
+        resourceId,
+      }),
+    );
+  }
+}
+
+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: false,
+        semanticRecall: {
+          topK: 3,
+          messageRange: 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';
+
+const memory = new Memory({
+  options: {
+    lastMessages: 100,
+    semanticRecall: {
+      topK: 2,
+      messageRange: 2,
+    },
+  },
+});
+
+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 { chefAgent, memoryAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { chefAgent, memoryAgent },
+});
+
+```