@mastra/mcp-docs-server 0.0.13 → 0.0.14-alpha.1

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

@@ -0,0 +1,609 @@
+### package.json
+```json
+{
+  "name": "memory-with-processors",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "support": "tsx src/support-agent.ts",
+    "interview": "tsx src/forgetful-interviewer.ts",
+    "tokens": "tsx src/processor-example.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@mastra/core": "latest",
+    "@mastra/memory": "latest",
+    "ai": "^4.3.15",
+    "chalk": "^5.4.1",
+    "dotenv": "^16.3.1",
+    "js-tiktoken": "^1.0.13",
+    "tiktoken": "^1.0.13",
+    "tsx": "^4.6.2",
+    "zod": "^3.24.3"
+  },
+  "pnpm": {
+    "overrides": {
+      "@mastra/core": "link:../../packages/core",
+      "@mastra/memory": "link:../../packages/memory"
+    }
+  },
+  "packageManager": "pnpm@10.10.0+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39"
+}
+
+```
+
+### forgetful-interviewer.ts
+```typescript
+import 'dotenv/config';
+
+import Readline from 'readline';
+
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import type { CoreMessage } from '@mastra/core';
+import { MemoryProcessor, MemoryProcessorOpts } from '@mastra/core/memory';
+import { Memory } from '@mastra/memory';
+
+import { makeSend } from './utils';
+
+// Custom processor that makes the llm forget any messages that contain keywords
+class ForgetfulProcessor extends MemoryProcessor {
+  constructor(private keywords: string[]) {
+    super({ name: 'ForgetfulProcessor' });
+  }
+
+  process(messages: CoreMessage[], _opts: MemoryProcessorOpts = {}): CoreMessage[] {
+    return messages.map(message => {
+      if (message.role === `assistant` || message.role === `user`) {
+        const content =
+          typeof message.content === `string`
+            ? message.content
+            : message.content.reduce((msg = ``, current) => {
+                if (current.type === `text`) {
+                  return msg + `\n${current.text}`;
+                }
+              }, '') || '';
+
+        const shouldForgetThis = this.keywords.some(keyword => content.toLowerCase().includes(keyword.toLowerCase()));
+        console.log(`\n`, { shouldForgetThis, content });
+        if (shouldForgetThis && (message.role === `user` || message.role === `assistant`)) {
+          return {
+            role: 'assistant',
+            content: `<forgotten>I'm getting forgetful in my old age. this used to be a ${message.role} message but I forgot it</forgotten>`,
+          };
+        }
+      }
+      return message;
+    });
+  }
+}
+
+// Interviewer agent that accidentally forgets your name all the time
+const agent = new Agent({
+  name: 'Forgetful Job Interviewer',
+  instructions:
+    "You are a professional job interviewer for a technology company. Conduct insightful interviews by asking relevant questions about skills, experience, and problem-solving abilities. Respond to candidate answers and ask follow-up questions. Keep the interview professional and engaging. Remember details the candidate shares earlier in the conversation. Sometimes you forget things by accident. The system will show you if you forgot. Don't be embarassed, you can admit when you forget something, you'll know when you do because there will be a message wrapped in <forgetten> tags. Don't refer to the user by their name, it comes across as too eager",
+  model: openai('gpt-4o'),
+  memory: new Memory({
+    processors: [
+      // Custom filter to remove messages with certain keywords
+      new ForgetfulProcessor(['name']),
+    ],
+    options: {
+      lastMessages: 30,
+      semanticRecall: false,
+    },
+  }),
+});
+
+console.log(`
+╔══════════════════════════════════════════════════════════╗
+║                                                          ║
+║  MASTRA MEMORY PROCESSORS DEMO - CONTENT FILTERING       ║
+║                                                          ║
+║  This example demonstrates:                              ║
+║  1. ToolCallFilter - All tool calls are filtered out     ║
+║  2. KeywordFilter - Messages with words like:            ║
+║     "confidential", "private", or "sensitive" are        ║
+║     filtered out of the conversation history.            ║
+║                                                          ║
+║  Try including those words in your responses to see      ║
+║  how the agent "forgets" that information in later       ║
+║  conversation turns.                                     ║
+║                                                          ║
+╚══════════════════════════════════════════════════════════╝
+`);
+
+const send = makeSend({
+  agentName: `\n👔 Forgetful interviewer (can never remember your name)`,
+  agent,
+});
+
+await send([
+  {
+    role: 'system',
+    content: `Interview starting now. Ask the candidate to introduce themselves and their background.`,
+  },
+]);
+
+const rl = Readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+// Interactive chat loop
+while (true) {
+  const prompt: string = await new Promise(res => {
+    rl.question('You: ', answer => {
+      res(answer);
+    });
+  });
+
+  if (prompt.toLowerCase() === 'exit' || prompt.toLowerCase() === 'quit') {
+    console.log('Ending interview. Thank you!');
+    process.exit(0);
+  }
+
+  await send(prompt);
+}
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { createTool } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
+import type { CoreMessage } from '@mastra/core';
+import { MemoryProcessor, MemoryProcessorOpts } from '@mastra/core/memory';
+import { Memory } from '@mastra/memory';
+import { TokenLimiter, ToolCallFilter } from '@mastra/memory/processors';
+import { z } from 'zod';
+
+// Custom processor that makes the llm forget any messages that contain keywords
+class ForgetfulProcessor extends MemoryProcessor {
+  constructor(private keywords: string[]) {
+    super({ name: 'ForgetfulProcessor' });
+  }
+
+  process(messages: CoreMessage[], _opts: MemoryProcessorOpts = {}): CoreMessage[] {
+    return messages.map(message => {
+      if (message.role === `assistant` || message.role === `user`) {
+        const content =
+          typeof message.content === `string`
+            ? message.content
+            : message.content.reduce((msg = ``, current) => {
+                if (current.type === `text`) {
+                  return msg + `\n${current.text}`;
+                }
+              }, '') || '';
+
+        const shouldForgetThis = this.keywords.some(keyword => content.toLowerCase().includes(keyword.toLowerCase()));
+        console.log(`\n`, { shouldForgetThis, content });
+        if (shouldForgetThis && (message.role === `user` || message.role === `assistant`)) {
+          return {
+            role: 'assistant',
+            content: `<forgotten>I'm getting forgetful in my old age. this used to be a ${message.role} message but I forgot it</forgotten>`,
+          };
+        }
+      }
+      return message;
+    });
+  }
+}
+
+// Create a technical support agent with token limiting
+const supportMemory = new Memory({
+  processors: [
+    // Limit history to approximately 2000 tokens to demonstrate truncation
+    new TokenLimiter(2000),
+  ],
+  options: {
+    lastMessages: 50,
+    semanticRecall: false,
+  },
+});
+
+// Create the web search tool
+const searchTool = createTool({
+  id: 'web-search',
+  description: 'Search the web for information',
+  inputSchema: z.object({
+    query: z.string().describe('The search query'),
+  }),
+  execute: async ({ context: { query } }) => {
+    // Simulate web search results
+    return `Search results for "${query}": 
+    1. Top result with important information
+    2. Secondary information related to the query
+    3. Additional context that might be helpful`;
+  },
+});
+
+// Technical support agent with token limiting
+export const supportAgent = new Agent({
+  name: 'Technical Support',
+  instructions:
+    'You are a technical support agent who helps users solve software problems. You provide clear, step-by-step instructions and ask clarifying questions when needed. You remember details from earlier in the conversation. Your goal is to efficiently resolve user issues.',
+  model: openai('gpt-4o-mini'),
+  memory: supportMemory,
+  tools: { searchTool },
+});
+
+// Create an interviewer agent that filters out tool calls and sensitive content
+const interviewMemory = new Memory({
+  processors: [
+    // Filter out all tool calls to keep conversation focused
+    new ToolCallFilter(),
+    // Custom filter to remove messages with certain keywords
+    new ForgetfulProcessor(['name']),
+  ],
+  options: {
+    lastMessages: 30,
+    semanticRecall: false,
+  },
+});
+
+// Interviewer agent that filters out tool calls and sensitive content
+export const interviewerAgent = new Agent({
+  name: 'Forgetful Job Interviewer',
+  instructions:
+    "You are a professional job interviewer for a technology company. Conduct insightful interviews by asking relevant questions about skills, experience, and problem-solving abilities. Respond to candidate answers and ask follow-up questions. Keep the interview professional and engaging. Remember details the candidate shares earlier in the conversation. Sometimes you forget things by accident. The system will show you if you forgot. Don't be embarassed, you can admit when you forget something, you'll know when you do because there will be a message wrapped in <forgetten> tags. Don't refer to the user by their name, it comes across as too eager",
+  model: openai('gpt-4o'),
+  memory: interviewMemory,
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from '@mastra/core';
+
+import { supportAgent, interviewerAgent } from './agents';
+
+export const mastra = new Mastra({
+  agents: { supportAgent, interviewerAgent },
+});
+
+```
+
+### processor-example.ts
+```typescript
+import 'dotenv/config';
+import { openai } from '@ai-sdk/openai';
+import { Mastra } from '@mastra/core';
+import { createLogger } from '@mastra/core/logger';
+import { createTool } from '@mastra/core/tools';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+import { TokenLimiter } from '@mastra/memory/processors';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import chalk from 'chalk';
+
+// Create a tool that reads the massive pnpm-lock.yaml file
+const testTool = createTool({
+  id: 'read-file',
+  description: 'Read a large file to test token limits',
+  execute: async () => {
+    try {
+      // Try multiple possible locations for the pnpm-lock.yaml file
+      const possiblePaths = [
+        // Root of the project
+        resolve(import.meta.dirname, '../../../', 'pnpm-lock.yaml'),
+      ];
+
+      let filePath: string | null = null;
+      let fileContent = '';
+
+      // Find the first file that exists
+      for (const path of possiblePaths) {
+        if (existsSync(path)) {
+          filePath = path;
+          fileContent = readFileSync(path, 'utf-8');
+          break;
+        }
+      }
+
+      // If no file was found, generate a large mock file
+      if (!filePath) {
+        console.log(chalk.yellow('No suitable large file found. Generating mock content...'));
+
+        // Create a large mock yaml-like content (about 20K characters)
+        fileContent = Array(100)
+          .fill(0)
+          .map(
+            (_, i) =>
+              `package-${i}:
+  version: "1.0.${i}"
+  resolved: "https://registry.npmjs.org/package-${i}/-/package-${i}-1.0.${i}.tgz"
+  integrity: "sha512-${Math.random().toString(36).substring(2, 40)}"
+  dependencies:
+    dep-a: "^2.0.0"
+    dep-b: "^3.1.2"
+    dep-c: "^0.8.9"
+  devDependencies:
+    test-lib: "^4.5.2"
+`,
+          )
+          .join('\n');
+      }
+
+      // Return the first 20K characters (still very token-heavy)
+      return `File content (truncated to 20K chars):\n${fileContent.slice(0, 20000)}`;
+    } catch (error) {
+      console.error('Error reading file:', error);
+
+      // Return a mock large response as fallback
+      return `Error reading file: ${error.message}\n\nGenerating mock content instead: \n${Array(50)
+        .fill('This is a large mock file content to test token limiting. ')
+        .join('\n')}`;
+    }
+  },
+});
+
+// Create memory with a low token limit to clearly demonstrate limiting
+const memory = new Memory({
+  processors: [
+    // Set a very low token limit (1000) to clearly demonstrate token limiting
+    new TokenLimiter(1000),
+  ],
+  options: {
+    lastMessages: 50,
+  },
+});
+
+// Create an agent with the test tool
+const tokenTestAgent = new Agent({
+  name: 'Token Test Agent',
+  instructions: 'You help test token limiting by calling tools that return large amounts of data.',
+  model: openai('gpt-4o-mini'),
+  memory,
+  tools: { testTool },
+});
+
+// Create Mastra instance
+const mastra = new Mastra({
+  agents: { tokenTestAgent },
+  logger: createLogger({ level: 'info' }),
+});
+
+// Track token usage
+const tokenHistory: number[] = [];
+
+async function sendMessage(message: string) {
+  console.log(`\n${chalk.green('You:')} ${message}`);
+
+  // Get the agent response
+  const response = await mastra.getAgent('tokenTestAgent').generate(message, {
+    threadId: 'token-test-thread',
+    resourceId: 'demo-user',
+  });
+
+  // Display the response
+  console.log(`\n${chalk.blue('Agent:')} ${response.text}`);
+
+  // Track and display token usage
+  const tokensUsed = response.usage.totalTokens;
+  tokenHistory.push(tokensUsed);
+
+  // Display token usage information
+  console.log(`\n${chalk.yellow('📊 Token Usage:')}`);
+  console.log(`${chalk.yellow('├')} Current: ${tokensUsed} tokens`);
+  console.log(`${chalk.yellow('├')} Total: ${tokenHistory.reduce((sum, t) => sum + t, 0)} tokens`);
+  console.log(`${chalk.yellow('└')} Memory Token Limit: 1000 tokens`);
+
+  return response;
+}
+
+async function main() {
+  console.log(
+    chalk.cyan(`
+╔══════════════════════════════════════════════════════════╗
+║                                                          ║
+║  TOKEN LIMITER PROCESSOR DEMO                            ║
+║                                                          ║
+║  This example demonstrates how TokenLimiter works with   ║
+║  extremely large tool responses.                         ║
+║                                                          ║
+║  The tool reads a massive pnpm-lock.yaml file and        ║
+║  returns a large chunk of text. If the file can't be     ║
+║  found, it generates mock content.                       ║
+║                                                          ║
+║  Memory token limit: 1000 tokens                         ║
+║                                                          ║
+╚══════════════════════════════════════════════════════════╝
+`),
+  );
+
+  // First message - introduction
+  await sendMessage("Hello! I'd like to test the token limiting functionality.");
+
+  // Second message - ask to call the tool
+  await sendMessage(
+    "Please use the read-file tool to read the large file. After you do, I'll ask you to summarize what you found.",
+  );
+
+  // Third message - ask about content that might be forgotten due to token limiting
+  await sendMessage(
+    'Now, can you tell me what was in the file you just read? And do you remember what I asked in my first message?',
+  );
+
+  // Fourth message - ask about content that should definitely be forgotten
+  await sendMessage(
+    "Let's see how the token limiter is working. Do you remember the exact contents at the beginning of the file?",
+  );
+
+  console.log(
+    chalk.cyan(`
+═════════════════════════════════════════════════════════════
+  DEMO COMPLETE
+  
+  The TokenLimiter processor has prevented the conversation from
+  exceeding the 1000 token limit by pruning older messages,
+  particularly the large tool response.
+  
+  This ensures that the context window is never exceeded while
+  still preserving the most recent and relevant messages.
+═════════════════════════════════════════════════════════════
+`),
+  );
+}
+
+main().catch(console.error);
+
+```
+
+### support-agent.ts
+```typescript
+import 'dotenv/config';
+import { makeSend, searchTool } from './utils';
+import { openai } from '@ai-sdk/openai';
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+import { TokenLimiter } from '@mastra/memory/processors';
+import { createLogger, Mastra } from '@mastra/core';
+
+const memory = new Memory({
+  processors: [new TokenLimiter(500)],
+  options: {
+    lastMessages: 50,
+    semanticRecall: true,
+  },
+});
+
+const techSupport = new Agent({
+  name: 'Technical Support',
+  instructions:
+    'You are a technical support agent who helps users solve software problems. You provide concise, short, instructions and ask clarifying questions when needed. You remember details from earlier in the conversation. Your goal is to efficiently resolve user issues. Make sure you provide concise responses without tons of text',
+  model: openai('gpt-4o-mini'),
+  memory,
+  tools: { searchTool },
+});
+
+const mastra = new Mastra({
+  agents: { techSupport },
+  logger: createLogger({ level: 'info' }),
+});
+
+console.log(`
+╔══════════════════════════════════════════════════════════╗
+║                                                          ║
+║  MASTRA MEMORY PROCESSORS DEMO - TOKEN LIMITING          ║
+║                                                          ║
+║  This example demonstrates the TokenLimiter processor    ║
+║  which limits memory to a specified token count (500).   ║
+║  As the conversation grows, older messages will be       ║
+║  automatically pruned to stay within the token limit.    ║
+║                                                          ║
+╚══════════════════════════════════════════════════════════╝
+`);
+
+const send = makeSend({
+  agentName: `\n 💻 Support Agent`,
+  agent: mastra.getAgent(`techSupport`),
+});
+
+await send(
+  "I'm having trouble with my laptop. It keeps shutting down randomly after about 30 minutes of use. I've had it for about 2 years and this just started happening last week.",
+);
+await send('Can you search for common causes of laptop overheating?');
+await send('Can you search again?');
+await send(
+  "The laptop feels quite hot before it shuts down. I'm using a Dell XPS 15 with Windows 11. I usually have multiple browser tabs open and sometimes I'm running Visual Studio Code. The battery seems to drain quickly too.",
+);
+await send(
+  "I've tried restarting in safe mode and the problem doesn't happen there. Also, I checked for Windows updates and everything is current. What should I do to fix this issue?",
+);
+await send(
+  "I tried cleaning the fans as you suggested, but it's still happening. I also downloaded a temperature monitoring app and it shows the CPU reaching 90°C before shutting down. My friend suggested it might be a failing thermal paste. Do you think I should try replacing the thermal paste myself or take it to a repair shop? I've never opened a laptop before but I'm somewhat technically inclined. Also, is there a way to limit how much CPU power certain applications use?",
+);
+await send(
+  'Can you remind me what was the first thing you suggested I should check? Also, do you think a cooling pad would help with my issue?',
+);
+
+```
+
+### utils.ts
+```typescript
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+import { Agent } from '@mastra/core/agent';
+import type { CoreMessage, StreamTextResult } from 'ai';
+import chalk from 'chalk';
+import { randomUUID } from 'node:crypto';
+
+export function makeLogger(botName: string) {
+  return async function logRes(res: Promise<StreamTextResult<any, any>>) {
+    console.log(chalk.bold.blue(botName + `:`));
+    for await (const chunk of (await res).fullStream) {
+      switch (chunk.type) {
+        case 'error':
+          console.error(chalk.red(chunk.error));
+          break;
+        case 'text-delta':
+          process.stdout.write(chalk.blue(chunk.textDelta));
+          break;
+
+        case 'tool-call':
+          console.log(chalk.cyan(`\n\ntool-call: ${chunk.toolName}`));
+          break;
+        case 'tool-result':
+          console.log(chalk.cyan(`\ntool-result: ${JSON.stringify(chunk.result)}\n\n`));
+      }
+    }
+    console.log(`\n\n`);
+    return {
+      usage: (await res).usage,
+      messages: (await (await res).response).messages,
+    };
+  };
+}
+
+export function makeSend({ agentName, agent }: { agentName: string; agent: Agent }) {
+  const threadId = randomUUID();
+  const resourceId = 'DEMO_USER_1';
+
+  const log = makeLogger(agentName);
+  function logQ(message: string | CoreMessage[]) {
+    if (typeof message !== 'string') return message;
+    console.log(
+      chalk.red(`\n${chalk.bold(`🐵 You:`)}\n${message}
+`),
+    );
+    return message;
+  }
+  let totalTokens = 0;
+  async function logStats(res: { usage: any; messages: any }) {
+    // console.log(chalk.green(`Completion had ${res.messages.length} messages`));
+    // console.log(chalk.green(`Usage: ${JSON.stringify(await res.usage, null, 2)}`));
+    totalTokens += (await res.usage).totalTokens;
+  }
+  process.on(`exit`, () => {
+    console.log(chalk.green.bold(`Total token usage: ${totalTokens}`));
+  });
+  return async function send(prompt: string | CoreMessage[]) {
+    await logStats(
+      await log(
+        agent.stream(logQ(prompt), {
+          threadId,
+          resourceId,
+        }),
+      ),
+    );
+  };
+}
+
+export const searchTool = createTool({
+  id: 'web-search',
+  description: 'Search the web for information',
+  inputSchema: z.object({
+    query: z.string().describe('The search query'),
+  }),
+  execute: async () => {
+    return `Not much found unfortunately. You'll probably have to turn it off an on again.`;
+  },
+});
+
+```