@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-logging-pino-logger.md

@@ -0,0 +1,117 @@
+# 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) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+
+export const mastra = new Mastra({
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
+})
+```
+
+## 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
+import { FileTransport } from '@mastra/loggers/file'
+import { PinoLogger } from '@mastra/loggers/pino'
+
+export const fileLogger = new PinoLogger({
+  name: 'Mastra',
+  transports: { file: new FileTransport({ path: 'test-dir/test.log' }) },
+  level: 'warn',
+})
+```
+
+### File transport usage
+
+```typescript
+fileLogger.warn('Low disk space', {
+  destinationPath: 'system',
+  type: 'WORKFLOW',
+})
+```
+
+## Upstash transport (remote log drain)
+
+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
+import { UpstashTransport } from '@mastra/loggers/upstash'
+import { PinoLogger } from '@mastra/loggers/pino'
+
+export const upstashLogger = new PinoLogger({
+  name: 'Mastra',
+  transports: {
+    upstash: new UpstashTransport({
+      listName: 'production-logs',
+      upstashUrl: process.env.UPSTASH_URL!,
+      upstashToken: process.env.UPSTASH_TOKEN!,
+    }),
+  },
+  level: 'info',
+})
+```
+
+### Upstash transport usage
+
+```typescript
+upstashLogger.info('User signed in', {
+  destinationPath: 'auth',
+  type: 'AGENT',
+  runId: 'run_123',
+})
+```
+
+## Custom transport
+
+You can create custom transports using the `createCustomTransport` utility to integrate with any logging service or stream.
+
+### Sentry transport example
+
+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
+import { createCustomTransport } from '@mastra/core/loggers'
+import { PinoLogger } from '@mastra/loggers/pino'
+import pinoSentry from 'pino-sentry-transport'
+
+const sentryStream = await pinoSentry({
+  sentry: {
+    dsn: 'YOUR_SENTRY_DSN',
+    _experiments: {
+      enableLogs: true,
+    },
+  },
+})
+
+const customTransport = createCustomTransport(sentryStream)
+
+export const sentryLogger = new PinoLogger({
+  name: 'Mastra',
+  level: 'info',
+  transports: { sentry: customTransport },
+})
+```

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

@@ -0,0 +1,38 @@
+# 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/references/reference-memory-memory-class.md

@@ -0,0 +1,147 @@
+# 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
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+
+export const agent = new Agent({
+  name: 'test-agent',
+  instructions: 'You are an agent with memory.',
+  model: 'openai/gpt-5.1',
+  memory: new Memory({
+    options: {
+      workingMemory: {
+        enabled: true,
+      },
+    },
+  }),
+})
+```
+
+> 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 include in context. Set to \`false\` to disable loading conversation history into context. Use \`Number.MAX\_SAFE\_INTEGER\` to retrieve all messages with no limit. To prevent saving new messages, use the \`readOnly\` option instead. (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
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+export const agent = new Agent({
+  name: 'test-agent',
+  instructions: 'You are an agent with memory.',
+  model: 'openai/gpt-5.1',
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'test-agent-storage',
+      url: 'file:./working-memory.db',
+    }),
+    vector: new LibSQLVector({
+      id: 'test-agent-vector',
+      url: 'file:./vector-memory.db',
+    }),
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+        scope: 'resource',
+      },
+      workingMemory: {
+        enabled: true,
+      },
+      generateTitle: true,
+    },
+  }),
+})
+```
+
+## PostgreSQL with index configuration
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+import { PgStore, PgVector } from '@mastra/pg'
+
+export const agent = new Agent({
+  name: 'pg-agent',
+  instructions: 'You are an agent with optimized PostgreSQL memory.',
+  model: 'openai/gpt-5.1',
+  memory: new Memory({
+    storage: new PgStore({
+      id: 'pg-agent-storage',
+      connectionString: process.env.DATABASE_URL,
+    }),
+    vector: new PgVector({
+      id: 'pg-agent-vector',
+      connectionString: process.env.DATABASE_URL,
+    }),
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      lastMessages: 20,
+      semanticRecall: {
+        topK: 5,
+        messageRange: 3,
+        scope: 'resource',
+        indexConfig: {
+          type: 'hnsw', // Use HNSW for better performance
+          metric: 'dotproduct', // Optimal for OpenAI embeddings
+          m: 16, // Number of bi-directional links
+          efConstruction: 64, // Construction-time candidate list size
+        },
+      },
+      workingMemory: {
+        enabled: true,
+      },
+    },
+  }),
+})
+```
+
+### Related
+
+- [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)
+- [getThreadById](https://mastra.ai/reference/memory/getThreadById)
+- [listThreads](https://mastra.ai/reference/memory/listThreads)
+- [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)
+- [cloneThread](https://mastra.ai/reference/memory/cloneThread)
+- [Clone Utility Methods](https://mastra.ai/reference/memory/clone-utilities)