@mastra/core 1.2.0 → 1.2.1-alpha.0

package/dist/docs/{logging/01-reference.md → references/reference-logging-pino-logger.md}

@@ -1,21 +1,12 @@
-# Logging API Reference
-
-> API reference for logging - 1 entries
-
-
----
-
-## Reference: PinoLogger
-
-> Documentation for PinoLogger, which provides methods to record events at various severity levels.
+# PinoLogger
 
 A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
 
-When deploying to Mastra Cloud, logs are displayed on the [Logs](https://mastra.ai/docs/mastra-cloud/observability#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+When deploying to Mastra Cloud, logs are displayed on the [Logs](https://mastra.ai/docs/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { PinoLogger } from "@mastra/loggers";
 
@@ -29,11 +20,21 @@ export const mastra = new Mastra({
 
 ## Parameters
 
+**name:** (`string`): A label used to group and identify logs from this logger.
+
+**level:** (`"debug" | "info" | "warn" | "error"`): Sets the minimum log level. Messages below this level are ignored.
+
+**transports:** (`Record<string, LoggerTransport>`): A map of transport instances used to persist logs.
+
+**overrideDefaultTransports?:** (`boolean`): If true, disables the default console transport.
+
+**formatters?:** (`pino.LoggerOptions['formatters']`): Custom Pino formatters for log serialization.
+
 ## File transport (structured logs)
 
 Writes structured logs to a file using the `FileTransport`. The logger accepts a plain message as the first argument and structured metadata as the second argument. These are internally converted to a `BaseLogMessage` and persisted to the configured file path.
 
-```typescript title="src/mastra/loggers/file-transport.ts"
+```typescript
 import { FileTransport } from "@mastra/loggers/file";
 import { PinoLogger } from "@mastra/loggers/pino";
 
@@ -57,7 +58,7 @@ fileLogger.warn("Low disk space", {
 
 Streams structured logs to a remote Redis list using the `UpstashTransport`. The logger accepts a string message and a structured metadata object. This enables centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.
 
-```typescript title="src/mastra/loggers/upstash-transport.ts"
+```typescript
 import { UpstashTransport } from "@mastra/loggers/upstash";
 import { PinoLogger } from "@mastra/loggers/pino";
 
@@ -92,7 +93,7 @@ You can create custom transports using the `createCustomTransport` utility to in
 
 Creates a custom transport using `createCustomTransport` and integrates it with a third-party logging stream such as `pino-sentry-transport`. This allows forwarding logs to an external system like Sentry for advanced monitoring and observability.
 
-```typescript title="src/mastra/loggers/sentry-transport.ts"
+```typescript
 import { createCustomTransport } from "@mastra/core/loggers";
 import { PinoLogger } from "@mastra/loggers/pino";
 import pinoSentry from "pino-sentry-transport";

package/dist/docs/references/reference-memory-deleteMessages.md

@@ -0,0 +1,40 @@
+# Memory.deleteMessages()
+
+The `.deleteMessages()` method deletes multiple messages by their IDs.
+
+## Usage Example
+
+```typescript
+await memory?.deleteMessages(["671ae63f-3a91-4082-a907-fe7de78e10ec"]);
+```
+
+## Parameters
+
+**messageIds:** (`string[]`): Array of message IDs to delete
+
+## Returns
+
+**void:** (`Promise<void>`): A promise that resolves when all messages are deleted
+
+## Extended usage example
+
+```typescript
+import { mastra } from "./mastra";
+import { MastraDBMessage } from "@mastra/core";
+
+const agent = mastra.getAgent("agent");
+const memory = await agent.getMemory();
+
+const { messages } = await memory!.recall({ threadId: "thread-123" });
+
+const messageIds = messages.map(
+  (message: MastraDBMessage) => message.id,
+);
+await memory?.deleteMessages([...messageIds]);
+```
+
+## Related
+
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [recall](https://mastra.ai/reference/memory/recall)
+- [Getting Started with Memory](https://mastra.ai/docs/memory/overview)

package/dist/docs/{memory/06-reference.md → references/reference-memory-memory-class.md}

@@ -1,60 +1,10 @@
-# Memory API Reference
-
-> API reference for memory - 2 entries
-
-
----
-
-## Reference: Memory.deleteMessages()
-
-> Documentation for the `Memory.deleteMessages()` method in Mastra, which deletes multiple messages by their IDs.
-
-The `.deleteMessages()` method deletes multiple messages by their IDs.
-
-## Usage Example
-
-```typescript
-await memory?.deleteMessages(["671ae63f-3a91-4082-a907-fe7de78e10ec"]);
-```
-
-## Parameters
-
-## Returns
-
-## Extended usage example
-
-```typescript title="src/test-memory.ts"
-import { mastra } from "./mastra";
-import { MastraDBMessage } from "@mastra/core";
-
-const agent = mastra.getAgent("agent");
-const memory = await agent.getMemory();
-
-const { messages } = await memory!.recall({ threadId: "thread-123" });
-
-const messageIds = messages.map(
-  (message: MastraDBMessage) => message.id,
-);
-await memory?.deleteMessages([...messageIds]);
-```
-
-## Related
-
-- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
-- [recall](https://mastra.ai/reference/memory/recall)
-- [Getting Started with Memory](https://mastra.ai/docs/memory/overview)
-
----
-
-## Reference: Memory Class
-
-> Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage.
+# Memory Class
 
 The `Memory` class provides a robust system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
 
 ## Usage example
 
-```typescript title="src/mastra/agents/test-agent.ts"
+```typescript
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 
@@ -72,17 +22,39 @@ export const agent = new Agent({
 });
 ```
 
-> To enable `workingMemory` on an agent, you’ll need a storage provider configured on your main Mastra instance. See [Mastra class](../core/mastra-class) for more information.
+> To enable `workingMemory` on an agent, you’ll need a storage provider configured on your main Mastra instance. See [Mastra class](https://mastra.ai/reference/core/mastra-class) for more information.
 
 ## Constructor parameters
 
+**storage?:** (`MastraCompositeStore`): Storage implementation for persisting memory data. Defaults to \`new DefaultStorage({ config: { url: "file:memory.db" } })\` if not provided.
+
+**vector?:** (`MastraVector | false`): Vector store for semantic search capabilities. Set to \`false\` to disable vector operations.
+
+**embedder?:** (`EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder instance for vector embeddings. Required when semantic recall is enabled.
+
+**options?:** (`MemoryConfig`): Memory configuration options.
+
 ### Options parameters
 
+**lastMessages?:** (`number | false`): Number of most recent messages to retrieve. Set to false to disable. (Default: `10`)
+
+**readOnly?:** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory. (Default: `false`)
+
+**semanticRecall?:** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured. Default topK is 4, default messageRange is {before: 1, after: 1}. (Default: `false`)
+
+**workingMemory?:** (`WorkingMemory`): Configuration for working memory feature. Can be \`{ enabled: boolean; template?: string; schema?: ZodObject\<any> | JSONSchema7; scope?: 'thread' | 'resource' }\` or \`{ enabled: boolean }\` to disable. (Default: `{ enabled: false, template: '# User Information\n- **First Name**:\n- **Last Name**:\n...' }`)
+
+**observationalMemory?:** (`boolean | ObservationalMemoryOptions`): Enable Observational Memory for long-context agentic memory. Set to \`true\` for defaults, or pass a config object to customize token budgets, models, and scope. See \[Observational Memory reference]\(/reference/memory/observational-memory) for configuration details. (Default: `false`)
+
+**generateTitle?:** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions. (Default: `false`)
+
 ## Returns
 
+**memory:** (`Memory`): A new Memory instance with the specified configuration.
+
 ## Extended usage example
 
-```typescript title="src/mastra/agents/test-agent.ts"
+```typescript
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
@@ -118,7 +90,7 @@ export const agent = new Agent({
 
 ## PostgreSQL with index configuration
 
-```typescript title="src/mastra/agents/pg-agent.ts"
+```typescript
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
@@ -164,6 +136,7 @@ export const agent = new Agent({
 - [Getting Started with Memory](https://mastra.ai/docs/memory/overview)
 - [Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)
 - [Working Memory](https://mastra.ai/docs/memory/working-memory)
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
 - [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
 - [createThread](https://mastra.ai/reference/memory/createThread)
 - [recall](https://mastra.ai/reference/memory/recall)

package/dist/docs/references/reference-memory-observational-memory.md

@@ -0,0 +1,217 @@
+# Observational Memory
+
+Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Two background agents — an **Observer** that watches conversations and creates observations, and a **Reflector** that restructures observations by combining related items, reflecting on overarching patterns, and condensing where possible — maintain an observation log that replaces raw message history as it grows.
+
+## Usage
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  memory: new Memory({
+    options: {
+      observationalMemory: true,
+    },
+  }),
+});
+```
+
+## Configuration
+
+The `observationalMemory` option accepts `true`, `false`, or a configuration object.
+
+Setting `observationalMemory: true` enables it with all defaults. Setting `observationalMemory: false` or omitting it disables it.
+
+**enabled?:** (`boolean`): Enable or disable Observational Memory. When omitted from a config object, defaults to \`true\`. Only \`enabled: false\` explicitly disables it. (Default: `true`)
+
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. (Default: `'google/gemini-2.5-flash'`)
+
+**scope?:** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
+
+**shareTokenBudget?:** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. (Default: `false`)
+
+**observation?:** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
+
+**reflection?:** (`ObservationalMemoryReflectionConfig`): Configuration for the reflection step. Controls when the Reflector agent runs and how it behaves.
+
+### Observation config
+
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. (Default: `'google/gemini-2.5-flash'`)
+
+**messageTokens?:** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. (Default: `30000`)
+
+**maxTokensPerBatch?:** (`number`): Maximum tokens per batch when observing multiple threads in resource scope. Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls. (Default: `10000`)
+
+**modelSettings?:** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. (Default: `{ temperature: 0.3, maxOutputTokens: 100_000 }`)
+
+### Reflection config
+
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. (Default: `'google/gemini-2.5-flash'`)
+
+**observationTokens?:** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them. (Default: `40000`)
+
+**modelSettings?:** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent. (Default: `{ temperature: 0, maxOutputTokens: 100_000 }`)
+
+### Model settings
+
+**temperature?:** (`number`): Temperature for generation. Lower values produce more consistent output. (Default: `0.3`)
+
+**maxOutputTokens?:** (`number`): Maximum output tokens. Set high to prevent truncation of observations. (Default: `100000`)
+
+## Examples
+
+### Resource scope with custom thresholds
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        scope: "resource",
+        observation: {
+          messageTokens: 20_000,
+        },
+        reflection: {
+          observationTokens: 60_000,
+        },
+      },
+    },
+  }),
+});
+```
+
+### Shared token budget
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        shareTokenBudget: true,
+        observation: {
+          messageTokens: 20_000,
+        },
+        reflection: {
+          observationTokens: 80_000,
+        },
+      },
+    },
+  }),
+});
+```
+
+When `shareTokenBudget` is enabled, the total budget is `observation.messageTokens + reflection.observationTokens` (100k in this example). If observations only use 30k tokens, messages can expand to use up to 70k. If messages are short, observations have more room before triggering reflection.
+
+### Custom model
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        model: "openai/gpt-4o-mini",
+      },
+    },
+  }),
+});
+```
+
+### Different models per agent
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        observation: {
+          model: "google/gemini-2.5-flash",
+        },
+        reflection: {
+          model: "openai/gpt-4o-mini",
+        },
+      },
+    },
+  }),
+});
+```
+
+## Standalone usage
+
+Most users should use the `Memory` class above. Using `ObservationalMemory` directly is mainly useful for benchmarking, experimentation, or when you need to control processor ordering with other processors (like [guardrails](https://mastra.ai/docs/agents/guardrails)).
+
+```typescript
+import { ObservationalMemory } from "@mastra/memory/processors";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore } from "@mastra/libsql";
+
+const storage = new LibSQLStore({
+  id: "my-storage",
+  url: "file:./memory.db",
+});
+
+const om = new ObservationalMemory({
+  storage: storage.stores.memory,
+  model: "google/gemini-2.5-flash",
+  scope: "resource",
+  observation: {
+    messageTokens: 20_000,
+  },
+  reflection: {
+    observationTokens: 60_000,
+  },
+});
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  inputProcessors: [om],
+  outputProcessors: [om],
+});
+```
+
+### Standalone config
+
+The standalone `ObservationalMemory` class accepts all the same options as the `observationalMemory` config object above, plus the following:
+
+**storage:** (`MemoryStorage`): Storage adapter for persisting observations. Must be a MemoryStorage instance (from \`MastraStorage.stores.memory\`).
+
+**onDebugEvent?:** (`(event: ObservationDebugEvent) => void`): Debug callback for observation events. Called whenever observation-related events occur. Useful for debugging and understanding the observation flow.
+
+**obscureThreadIds?:** (`boolean`): When enabled, thread IDs are hashed before being included in observation context. This prevents the LLM from recognizing patterns in thread identifiers. Automatically enabled when using resource scope through the Memory class. (Default: `false`)
+
+### Related
+
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
+- [Memory Overview](https://mastra.ai/docs/memory/overview)
+- [Memory Class](https://mastra.ai/reference/memory/memory-class)
+- [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
+- [Processors](https://mastra.ai/docs/agents/processors)

package/dist/docs/references/reference-observability-tracing-bridges-otel.md

@@ -0,0 +1,131 @@
+# OtelBridge
+
+> **Warning:** The OpenTelemetry Bridge is currently **experimental**. APIs and configuration options may change in future releases.
+
+Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans.
+
+## Constructor
+
+```typescript
+new OtelBridge()
+```
+
+## Methods
+
+### executeInContext
+
+```typescript
+executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>
+```
+
+Executes an async function within the OTEL context of a Mastra span. OTEL-instrumented code running inside the function will have correct parent relationships.
+
+**Returns:** `Promise<T>` - The result of the function execution.
+
+### executeInContextSync
+
+```typescript
+executeInContextSync<T>(spanId: string, fn: () => T): T
+```
+
+Executes a synchronous function within the OTEL context of a Mastra span.
+
+**Returns:** `T` - The result of the function execution.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Shuts down the bridge and cleans up resources. Ends any spans that were not properly closed.
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { OtelBridge } from "@mastra/otel-bridge";
+
+const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: "my-service",
+        bridge: new OtelBridge(),
+      },
+    },
+  }),
+  agents: { myAgent },
+});
+```
+
+### Combined with Exporters
+
+The bridge can be used alongside exporters. The bridge handles OTEL context, while exporters send data to additional destinations:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { Observability, DefaultExporter } from "@mastra/observability";
+import { OtelBridge } from "@mastra/otel-bridge";
+import { LangfuseExporter } from "@mastra/langfuse";
+
+const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: "my-service",
+        bridge: new OtelBridge(), // Handles OTEL context
+        exporters: [
+          new DefaultExporter(), // Studio access
+          new LangfuseExporter({
+            // Additional destination
+            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+            secretKey: process.env.LANGFUSE_SECRET_KEY,
+          }),
+        ],
+      },
+    },
+  }),
+});
+```
+
+## OpenTelemetry Setup Requirements
+
+The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.
+
+See the [OtelBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/otel) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
+
+## Tags Support
+
+The OtelBridge supports trace tagging for categorization and filtering. Tags are only applied to root spans and are included as the `mastra.tags` attribute on native OTEL spans.
+
+### Usage
+
+```typescript
+const result = await agent.generate("Hello", {
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+### How Tags Are Stored
+
+Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute:
+
+```json
+{
+  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
+}
+```
+
+This format ensures compatibility with all OTEL-compatible backends and collectors.
+
+## Related
+
+- [OtelBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/otel) - Setup guide with examples
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - General tracing concepts
+- [OtelExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel) - OTEL exporter for sending traces