@mastra/mcp-docs-server 0.13.34 → 0.13.35

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)

package/.docs/raw/observability/ai-tracing/exporters/arize.mdx

@@ -0,0 +1,201 @@
+---
+title: "Arize Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send AI traces to Arize Phoenix or Arize AX using OpenTelemetry and OpenInference"
+---
+
+import { Callout } from "nextra/components";
+
+# Arize Exporter
+
+[Arize](https://arize.com/) provides observability platforms for AI applications through [Phoenix](https://phoenix.arize.com/) (open-source) and [Arize AX](https://arize.com/generative-ai/) (enterprise). The Arize exporter sends AI traces using OpenTelemetry and [OpenInference](https://github.com/Arize-ai/openinference/tree/main/spec) semantic conventions, compatible with any OpenTelemetry platform that supports OpenInference.
+
+## When to Use Arize
+
+Arize is ideal when you need:
+- **OpenInference standards** - Industry-standard semantic conventions for AI traces
+- **Flexible deployment** - Self-hosted Phoenix or managed Arize AX
+- **OpenTelemetry compatibility** - Works with any OTLP-compatible platform
+- **Comprehensive AI observability** - LLM traces, embeddings, and retrieval analytics
+- **Open-source option** - Full-featured local deployment with Phoenix
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/arize
+```
+
+## Configuration
+
+### Phoenix Setup
+
+Phoenix is an open-source observability platform that can be self-hosted or used via Phoenix Cloud.
+
+#### Prerequisites
+
+1. **Phoenix Instance**: Deploy using Docker or sign up at [Phoenix Cloud](https://app.phoenix.arize.com/login)
+2. **Endpoint**: Your Phoenix endpoint URL (ends in `/v1/traces`)
+3. **API Key**: Optional for unauthenticated instances, required for Phoenix Cloud
+4. **Environment Variables**: Set your configuration
+
+```bash filename=".env"
+PHOENIX_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL
+PHOENIX_API_KEY=your-api-key  # Optional for local instances
+PHOENIX_PROJECT_NAME=mastra-service  # Optional, defaults to 'mastra-service'
+```
+
+#### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { ArizeExporter } from "@mastra/arize";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      arize: {
+        serviceName: process.env.PHOENIX_PROJECT_NAME || 'mastra-service',
+        exporters: [
+          new ArizeExporter({
+            endpoint: process.env.PHOENIX_ENDPOINT!,
+            apiKey: process.env.PHOENIX_API_KEY,
+            projectName: process.env.PHOENIX_PROJECT_NAME,
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+<Callout type="info">
+**Quick Start with Docker**
+
+Test locally with an in-memory Phoenix instance:
+
+```bash
+docker run --pull=always -d --name arize-phoenix -p 6006:6006 \
+  -e PHOENIX_SQL_DATABASE_URL="sqlite:///:memory:" \
+  arizephoenix/phoenix:latest
+```
+
+Set `PHOENIX_ENDPOINT=http://localhost:6006/v1/traces` and run your Mastra agent to see traces at [localhost:6006](http://localhost:6006).
+</Callout>
+
+### Arize AX Setup
+
+Arize AX is an enterprise observability platform with advanced features for production AI systems.
+
+#### Prerequisites
+
+1. **Arize AX Account**: Sign up at [app.arize.com](https://app.arize.com/)
+2. **Space ID**: Your organization's space identifier
+3. **API Key**: Generate in Arize AX settings
+4. **Environment Variables**: Set your credentials
+
+```bash filename=".env"
+ARIZE_SPACE_ID=your-space-id
+ARIZE_API_KEY=your-api-key
+ARIZE_PROJECT_NAME=mastra-service  # Optional
+```
+
+#### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { ArizeExporter } from "@mastra/arize";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      arize: {
+        serviceName: process.env.ARIZE_PROJECT_NAME || 'mastra-service',
+        exporters: [
+          new ArizeExporter({
+            apiKey: process.env.ARIZE_API_KEY!,
+            spaceId: process.env.ARIZE_SPACE_ID!,
+            projectName: process.env.ARIZE_PROJECT_NAME,
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+## Configuration Options
+
+The Arize exporter supports advanced configuration for fine-tuning OpenTelemetry behavior:
+
+### Complete Configuration
+
+```typescript
+new ArizeExporter({
+  // Phoenix Configuration
+  endpoint: 'https://your-collector.example.com/v1/traces',  // Required for Phoenix
+
+  // Arize AX Configuration
+  spaceId: 'your-space-id',  // Required for Arize AX
+
+  // Shared Configuration
+  apiKey: 'your-api-key',  // Required for authenticated endpoints
+  projectName: 'mastra-service',  // Optional project name
+
+  // Optional OTLP settings
+  headers: {
+    'x-custom-header': 'value',  // Additional headers for OTLP requests
+  },
+
+  // Debug and performance tuning
+  logLevel: 'debug',  // Logging: debug | info | warn | error
+  batchSize: 512,     // Batch size before exporting spans
+  timeout: 30000,     // Timeout in ms before exporting spans
+
+  // Custom resource attributes
+  resourceAttributes: {
+    'deployment.environment': process.env.NODE_ENV,
+    'service.version': process.env.APP_VERSION,
+  },
+})
+```
+
+### Batch Processing Options
+
+Control how traces are batched and exported:
+
+```typescript
+new ArizeExporter({
+  endpoint: process.env.PHOENIX_ENDPOINT!,
+  apiKey: process.env.PHOENIX_API_KEY,
+
+  // Batch processing configuration
+  batchSize: 512,    // Number of spans to batch (default: 512)
+  timeout: 30000,    // Max time in ms to wait before export (default: 30000)
+})
+```
+
+### Resource Attributes
+
+Add custom attributes to all exported spans:
+
+```typescript
+new ArizeExporter({
+  endpoint: process.env.PHOENIX_ENDPOINT!,
+  resourceAttributes: {
+    'deployment.environment': process.env.NODE_ENV,
+    'service.namespace': 'production',
+    'service.instance.id': process.env.HOSTNAME,
+    'custom.attribute': 'value',
+  },
+})
+```
+
+## OpenInference Semantic Conventions
+
+This exporter implements the [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [Phoenix Documentation](https://docs.arize.com/phoenix)
+- [Arize AX Documentation](https://docs.arize.com/)
+- [OpenInference Specification](https://github.com/Arize-ai/openinference/tree/main/spec)

package/.docs/raw/observability/ai-tracing/overview.mdx

@@ -89,14 +89,13 @@ Mastra provides two built-in exporters that work out of the box:
 
 In addition to the internal exporters, Mastra supports integration with popular observability platforms. These exporters allow you to leverage your existing monitoring infrastructure and take advantage of platform-specific features like alerting, dashboards, and correlation with other application metrics.
 
+- **[Arize](/docs/observability/ai-tracing/exporters/arize)** - Exports traces to Arize Phoenix or Arize AX using OpenInference semantic conventions
 - **[Braintrust](/docs/observability/ai-tracing/exporters/braintrust)** - Exports traces to Braintrust's eval and observability platform
 - **[Langfuse](/docs/observability/ai-tracing/exporters/langfuse)** - Sends traces to the Langfuse open-source LLM engineering platform
-- **[LangSmith](/docs/observability/ai-tracing/exporters/langsmith)** - Pushes traces into LangSmith’s observability and evaluation toolkit
+- **[LangSmith](/docs/observability/ai-tracing/exporters/langsmith)** - Pushes traces into LangSmith's observability and evaluation toolkit
 - **[OpenTelemetry](/docs/observability/ai-tracing/exporters/otel)** - Deliver traces to any OpenTelemetry-compatible observability system
   - Supports: Dash0, Laminar, New Relic, SigNoz, Traceloop, Zipkin, and others!
 
-- **Arize** - Coming soon!
-
 ## Sampling Strategies
 
 Sampling allows you to control which traces are collected, helping you balance between observability needs and resource costs. In production environments with high traffic, collecting every trace can be expensive and unnecessary. Sampling strategies let you capture a representative subset of traces while ensuring you don't miss critical information about errors or important operations.
@@ -311,7 +310,7 @@ When creating a custom config with external exporters, you might lose access to
 
 ```ts filename="src/mastra/index.ts" showLineNumbers copy
 import { DefaultExporter, CloudExporter } from '@mastra/core/ai-tracing';
-import { LangfuseExporter } from '@mastra/langfuse';
+import { ArizeExporter } from '@mastra/arize';
 
 export const mastra = new Mastra({
   observability: {
@@ -320,7 +319,10 @@ export const mastra = new Mastra({
       production: {
         serviceName: 'my-service',
         exporters: [
-          new LangfuseExporter(), // External exporter
+          new ArizeExporter({    // External exporter
+            endpoint: process.env.PHOENIX_ENDPOINT,
+            apiKey: process.env.PHOENIX_API_KEY,
+          }),
           new DefaultExporter(),  // Keep Playground access
           new CloudExporter(),    // Keep Cloud access
         ],
@@ -331,7 +333,7 @@ export const mastra = new Mastra({
 ```
 
 This configuration sends traces to all three destinations simultaneously:
-- **Langfuse** for external observability
+- **Arize Phoenix/AX** for external observability
 - **DefaultExporter** for local Playground access
 - **CloudExporter** for Mastra Cloud dashboard
 
@@ -759,8 +761,9 @@ Traces are available in multiple locations:
 
 - **Mastra Playground** - Local development environment
 - **Mastra Cloud** - Production monitoring dashboard
-- **Langfuse Dashboard** - When using Langfuse exporter
+- **Arize Phoenix / Arize AX** - When using Arize exporter
 - **Braintrust Console** - When using Braintrust exporter
+- **Langfuse Dashboard** - When using Langfuse exporter
 
 ## See Also
 
@@ -777,8 +780,9 @@ Traces are available in multiple locations:
 - [DefaultExporter](/reference/observability/ai-tracing/exporters/default-exporter) - Storage persistence
 - [CloudExporter](/reference/observability/ai-tracing/exporters/cloud-exporter) - Mastra Cloud integration
 - [ConsoleExporter](/reference/observability/ai-tracing/exporters/console-exporter) - Debug output
-- [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
+- [Arize](/reference/observability/ai-tracing/exporters/arize) - Arize Phoenix and Arize AX integration
 - [Braintrust](/reference/observability/ai-tracing/exporters/braintrust) - Braintrust integration
+- [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
 - [OpenTelemetry](/reference/observability/ai-tracing/exporters/otel) - OTEL-compatible platforms
 
 ### Processors