@mastra/memory 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

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

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# summarizeConversation()
+
+The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory): without Observational Memory attached to an agent, and without reading from or writing to storage.
+
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go: for example your own database.
+
+Use this when you already have the messages in hand and want explicit control over what gets summarized. For a stored thread identified by ID, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
+
+## Usage example
+
+```typescript
+import { summarizeConversation } from '@mastra/memory'
+
+const result = await summarizeConversation({
+  model: 'openai/gpt-5-mini',
+  messages,
+  instructions: 'Summarize this voicemail call for the business owner.',
+})
+```
+
+## Parameters
+
+**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
+
+**messages** (`MastraDBMessage[]`): The conversation to summarize. When empty, the function returns an empty result without calling the model.
+
+**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
+
+**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
+
+**threadId** (`string`): Thread the conversation belongs to. Defaults to the first threadId found on messages. Passed to extractor contexts.
+
+**resourceId** (`string`): Resource (user) the conversation belongs to. Defaults to the first resourceId found on messages. Passed to extractor contexts.
+
+**memory** (`Memory`): Memory instance forwarded to extractor contexts. Set automatically when called through Memory.summarizeThread().
+
+**mastra** (`Mastra`): Mastra instance used to resolve custom gateway models. Set automatically when called through Memory.summarizeThread().
+
+**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
+
+**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
+
+## Returns
+
+**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
+
+**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
+
+**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
+
+**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
+
+## Extended usage example
+
+The following example summarizes an in-flight voice session from messages the application already holds, and extracts a structured record:
+
+```typescript
+import { summarizeConversation, Extractor } from '@mastra/memory'
+import type { MastraDBMessage } from '@mastra/core/agent'
+import { z } from 'zod'
+import { sessionRecords } from './db'
+
+const sessionSummary = new Extractor({
+  name: 'session-summary',
+  instructions: 'Return a concise summary of the session.',
+  schema: z.object({
+    summary: z.string(),
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    followUps: z.array(z.string()),
+  }),
+  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
+  onExtracted: async ({ current, threadId }) => {
+    await sessionRecords.upsert({ sessionId: threadId, record: current })
+  },
+})
+
+export async function onSessionEnd(messages: MastraDBMessage[]) {
+  const { summary, extracted, extractionFailures } = await summarizeConversation({
+    model: 'openai/gpt-5-mini',
+    messages,
+    instructions: 'Summarize this support session for the account manager.',
+    extract: [sessionSummary],
+  })
+
+  if (extractionFailures?.length) {
+    console.warn('Some extractors failed', extractionFailures)
+  }
+
+  return { summary, extracted }
+}
+```
+
+### Related
+
+- [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)

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

@@ -0,0 +1,93 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.summarizeThread()
+
+The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory): as a standalone call, without Observational Memory attached to an agent.
+
+Messages load page-by-page starting from the newest, bounded by `lastMessages` and `maxInputTokens`, so summarizing a long thread doesn't read its entire history from storage.
+
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go: for example your own database.
+
+Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. For messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead. It takes the same options with `messages` in place of `threadId`.
+
+## Usage example
+
+```typescript
+const result = await memory.summarizeThread({
+  model: 'openai/gpt-5-mini',
+  threadId: 'thread-123',
+  instructions: 'Summarize this voicemail call for the business owner.',
+})
+```
+
+## Parameters
+
+**threadId** (`string`): The unique identifier of the thread to summarize.
+
+**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
+
+**resourceId** (`string`): ID of the resource that owns the thread. If provided, validates thread ownership. Also passed to extractor contexts.
+
+**lastMessages** (`number`): Only summarize the last N messages of the thread. By default the whole thread is loaded, bounded by maxInputTokens.
+
+**maxInputTokens** (`number`): Stop loading older messages once the collected messages exceed this estimated token count. The newest message is always included. (Default: `1000000`)
+
+**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
+
+**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
+
+**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
+
+**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
+
+## Returns
+
+**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
+
+**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
+
+**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
+
+**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
+
+## Extended usage example
+
+The following example summarizes a finished voice call and stores a structured record in the application's own database:
+
+```typescript
+import { Extractor } from '@mastra/memory'
+import { z } from 'zod'
+import { memory } from './mastra/memory'
+import { callRecords } from './db'
+
+const callSummary = new Extractor({
+  name: 'call-summary',
+  instructions: 'Return a concise summary of the call.',
+  schema: z.object({
+    summary: z.string(),
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    requestedServices: z.array(z.string()),
+  }),
+  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
+  onExtracted: async ({ current, threadId, resourceId }) => {
+    await callRecords.upsert({ callId: threadId, callerId: resourceId, record: current })
+  },
+})
+
+export async function onCallEnd(threadId: string, resourceId: string) {
+  await memory.summarizeThread({
+    model: 'openai/gpt-5-mini',
+    threadId,
+    resourceId,
+    instructions: 'Summarize this voicemail call for the business owner.',
+    extract: [callSummary],
+  })
+}
+```
+
+### Related
+
+- [summarizeConversation()](https://mastra.ai/reference/memory/summarizeConversation)
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)
+- [.recall()](https://mastra.ai/reference/memory/recall)

package/dist/docs/references/reference-processors-token-limiter-processor.md

@@ -0,0 +1,158 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# TokenLimiterProcessor
+
+The `TokenLimiterProcessor` limits the number of tokens in messages. It can be used as an input, per-step input, and output processor:
+
+- **Input processor** (`processInput`): Filters historical messages to fit within the context window before the agentic loop starts, prioritizing recent messages
+- **Per-step input processor** (`processInputStep`): Prunes messages at each step of a multi-step agent workflow, preventing unbounded token growth when tools trigger additional LLM calls
+- **Output processor**: Limits generated response tokens via streaming or non-streaming with configurable strategies for handling exceeded limits
+
+## Usage example
+
+```typescript
+import { TokenLimiterProcessor } from '@mastra/core/processors'
+
+const processor = new TokenLimiterProcessor({
+  limit: 1000,
+  strategy: 'truncate',
+  countMode: 'cumulative',
+})
+```
+
+## Constructor parameters
+
+**options** (`number | Options`): Either a simple number for token limit, or configuration options object
+
+**options.limit** (`number`): Maximum number of tokens to allow in the response
+
+**options.encoding** (`TiktokenBPE`): Optional encoding to use. Defaults to o200k\_base which is used by gpt-5.1
+
+**options.strategy** (`'truncate' | 'abort'`): Strategy when token limit is reached: 'truncate' stops emitting chunks, 'abort' calls abort() to stop the stream
+
+**options.countMode** (`'cumulative' | 'part'`): Whether to count tokens from the beginning of the stream or just the current part: 'cumulative' counts all tokens from start, 'part' only counts tokens in current part
+
+**options.trimMode** (`'best-fit' | 'contiguous'`): Controls how messages are trimmed when exceeding the token limit: 'best-fit' keeps as many messages as possible (may create gaps), 'contiguous' stops at the first message that does not fit, ensuring a continuous suffix of conversation history
+
+## Returns
+
+**id** (`string`): Processor identifier set to 'token-limiter'
+
+**name** (`string`): Optional processor display name
+
+**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Filters input messages to fit within token limit before the agentic loop starts, prioritizing recent messages while preserving system messages
+
+**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Prunes messages at each step of the agentic loop (including tool call continuations) to keep the conversation within the token limit. Mutates the messageList directly by removing oldest messages first while preserving system messages.
+
+**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null>`): Processes streaming output parts to limit token count during streaming. Only text and object parts count against the limit and can be withheld; lifecycle, reasoning and tool parts always pass through.
+
+**processOutputResult** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Processes final output results to limit token count in non-streaming scenarios
+
+**getMaxTokens** (`() => number`): Get the maximum token limit
+
+## Output stream behavior
+
+As an output processor, only parts that carry generated output count against the limit: `text-delta` and `object`. Lifecycle parts (such as `step-start`), reasoning deltas, response metadata, and tool parts (`tool-call`, `tool-result`) are neither counted nor withheld, so tool calls always reach the agentic loop and get executed.
+
+With the default `truncate` strategy, the first time output is withheld the processor emits a transient `data-token-limit-reached` part on the stream:
+
+```typescript
+for await (const part of stream.fullStream) {
+  if (part.type === 'data-token-limit-reached') {
+    console.log('output truncated at', part.data.limit, 'tokens')
+  }
+}
+```
+
+## Error behavior
+
+When used as an input processor (both `processInput` and `processInputStep`), `TokenLimiterProcessor` throws a `TripWire` error in the following cases:
+
+- **Empty messages**: If there are no messages to process, a TripWire is thrown because you can't send an LLM request with no messages.
+- **System messages exceed limit**: If system messages alone exceed the token limit, a TripWire is thrown because you can't send an LLM request with only system messages and no user/assistant messages.
+
+```typescript
+import { TripWire } from '@mastra/core/agent'
+
+try {
+  await agent.generate('Hello')
+} catch (error) {
+  if (error instanceof TripWire) {
+    console.log('Token limit error:', error.message)
+  }
+}
+```
+
+## Extended usage example
+
+### As an input processor (limit context window)
+
+Use `inputProcessors` to limit historical messages sent to the model, which helps stay within context window limits:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { TokenLimiterProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  id: 'context-limited-agent',
+  name: 'context-limited-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({/* ... */}),
+  inputProcessors: [
+    new TokenLimiterProcessor({ limit: 4000 }), // Limits historical messages to ~4000 tokens
+  ],
+})
+```
+
+### As a per-step input processor (limit multi-step token growth)
+
+When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps. Use `inputProcessors` to also limit tokens at each step of the agentic loop. The `TokenLimiterProcessor` automatically applies to both the initial input and every subsequent step:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { TokenLimiterProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  id: 'multi-step-agent',
+  name: 'multi-step-agent',
+  instructions: 'You are a helpful research assistant with access to tools',
+  model: 'openai/gpt-5.6-sol',
+  inputProcessors: [
+    new TokenLimiterProcessor({ limit: 8000 }), // Applied at every step
+  ],
+})
+
+// Each tool call step will be limited to ~8000 input tokens
+const result = await agent.generate('Research this topic using your tools', {
+  maxSteps: 10,
+})
+```
+
+### As an output processor (limit response length)
+
+Use `outputProcessors` to limit the length of generated responses:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { TokenLimiterProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  id: 'response-limited-agent',
+  name: 'response-limited-agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.6-sol',
+  outputProcessors: [
+    new TokenLimiterProcessor({
+      limit: 1000,
+      strategy: 'truncate',
+      countMode: 'cumulative',
+    }),
+  ],
+})
+```
+
+## Related
+
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)