@mastra/mcp-docs-server 1.2.4-alpha.5 → 1.2.4-alpha.6

package/.docs/reference/processors/prefill-error-handler.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # PrefillErrorHandler
 
 The `PrefillErrorHandler` is an **error processor** that handles assistant-response prefill errors. This error occurs when a conversation ends with an assistant message and the model rejects the request because it interprets it as prefilling the assistant response.

package/.docs/reference/processors/processor-interface.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Processor interface
 
 The `Processor` interface defines the contract for all processors in Mastra. Processors can implement one or more methods to handle different stages of the agent execution pipeline.

package/.docs/reference/processors/prompt-injection-detector.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # PromptInjectionDetector
 
 The `PromptInjectionDetector` is an **input processor** that detects and prevents prompt injection attacks, jailbreaks, and system manipulation attempts before messages are sent to the language model. This processor helps maintain security by identifying various types of injection attempts and providing flexible strategies for handling them, including content rewriting to neutralize attacks while preserving legitimate user intent.

package/.docs/reference/processors/provider-history-compat.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ProviderHistoryCompat
 
 The `ProviderHistoryCompat` processor handles provider-specific history incompatibilities. It can rewrite the outbound language model prompt before a provider call, or react to API errors and retry with repaired message history.

package/.docs/reference/processors/regex-filter-processor.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # RegexFilterProcessor
 
 The `RegexFilterProcessor` applies zero-cost regex pattern matching to filter, redact, or block content in agent messages. No LLM calls are made — all detection is regex-based.

package/.docs/reference/processors/response-cache.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ResponseCache
 
 `ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` (cache lookup; short-circuits on hit) and `processLLMResponse` (cache write on completion).

package/.docs/reference/processors/semantic-recall-processor.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # SemanticRecall
 
 The `SemanticRecall` is a **hybrid processor** that enables semantic search over conversation history using vector embeddings. On input, it performs semantic search to find relevant historical messages. On output, it creates embeddings for new messages to enable future semantic retrieval.

package/.docs/reference/processors/skill-search-processor.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # SkillSearchProcessor
 
 The `SkillSearchProcessor` is an **input processor** that enables on-demand skill discovery and loading. Instead of injecting all skill metadata into the system prompt upfront (like `SkillsProcessor`), it gives the agent two meta-tools (`search_skills` and `load_skill`) that let it find and load skills on demand. This reduces context token usage when workspaces have many skills.

package/.docs/reference/processors/stream-error-retry-processor.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # StreamErrorRetryProcessor
 
 `StreamErrorRetryProcessor` is an **error processor** that retries transient errors emitted after an LLM stream starts. It includes built-in matching for OpenAI Responses stream errors and supports additional matchers for other provider-specific stream error shapes.

package/.docs/reference/processors/system-prompt-scrubber.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # SystemPromptScrubber
 
 The `SystemPromptScrubber` is an **output processor** that detects and handles system prompts, instructions, and other revealing information that could introduce security vulnerabilities. This processor helps maintain security by identifying various types of system prompts and providing flexible strategies for handling them, including multiple redaction methods to ensure sensitive information is properly sanitized.

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

@@ -1,3 +1,5 @@
+> 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:

package/.docs/reference/processors/tool-call-filter.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ToolCallFilter
 
 The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the message history before sending to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.

package/.docs/reference/processors/tool-search-processor.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ToolSearchProcessor
 
 The `ToolSearchProcessor` is an **input processor** that enables dynamic tool discovery and loading. Instead of providing all tools to the agent upfront, it gives the agent two meta-tools (`search_tools` and `load_tool`) that let it find and load tools on demand. This reduces context token usage when working with large tool libraries.

package/.docs/reference/processors/unicode-normalizer.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # UnicodeNormalizer
 
 The `UnicodeNormalizer` is an **input processor** that normalizes Unicode text to ensure consistent formatting and remove potentially problematic characters before messages are sent to the language model. This processor helps maintain text quality by handling various Unicode representations, removing control characters, and standardizing whitespace formatting.

package/.docs/reference/processors/working-memory-processor.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # WorkingMemory
 
 The `WorkingMemory` is an **input processor** that injects working memory data as a system message. It retrieves persistent information from storage and formats it as instructions for the LLM, enabling the agent to maintain context about users across conversations.

package/.docs/reference/pubsub/base.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # PubSub
 
 `PubSub` is the abstract base class for Mastra's event system. It defines the contract that every pub/sub backend implements, so the rest of Mastra can publish and subscribe to events without knowing which transport is in use.

package/.docs/reference/pubsub/caching-pubsub.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # CachingPubSub
 
 `CachingPubSub` wraps any [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation and adds event caching and replay. It records every published event per topic in a cache, so a subscriber that connects late or reconnects after a disconnect can replay the events it missed before continuing with live events.

package/.docs/reference/pubsub/event-emitter.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # EventEmitterPubSub
 
 `EventEmitterPubSub` is the default [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation. It delivers events in-process using a Node.js [`EventEmitter`](https://nodejs.org/api/events.html#class-eventemitter), so it works without any external service.

package/.docs/reference/pubsub/google-cloud-pubsub.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # GoogleCloudPubSub
 
 `GoogleCloudPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation backed by [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/docs). It delivers events across processes and hosts using Google Cloud topics and subscriptions, with ordered delivery and message acknowledgment.

package/.docs/reference/pubsub/lease-provider.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # LeaseProvider
 
 `LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/agents/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a given resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.

package/.docs/reference/pubsub/redis-streams.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # RedisStreamsPubSub
 
 `RedisStreamsPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation backed by [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/). It delivers events across processes and hosts, with persistence, consumer groups, and redelivery on failure. It also implements [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider), so the signals layer can elect a single owner per resource across instances, which is what lets signals coordinate runs in distributed and serverless deployments.

package/.docs/reference/pubsub/unix-socket-pubsub.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # UnixSocketPubSub
 
 `UnixSocketPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation that delivers events across processes on a single host using a Unix domain socket. It elects one process as a broker, and other processes connect to it as clients. If the broker exits, the remaining clients elect a new broker automatically.

package/.docs/reference/rag/chunk.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # .chunk()
 
 The `.chunk()` function splits documents into smaller segments using various strategies and options.

package/.docs/reference/rag/database-config.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # DatabaseConfig
 
 The `DatabaseConfig` type allows you to specify database-specific configurations when using vector query tools. These configurations enable you to leverage unique features and optimizations offered by different vector stores.

package/.docs/reference/rag/document.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MDocument
 
 The MDocument class processes documents for RAG applications. The main methods are `.chunk()` and `.extractMetadata()`.

package/.docs/reference/rag/embeddings.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Embed
 
 Mastra uses the AI SDK's `embed` and `embedMany` functions to generate vector embeddings for text inputs, enabling similarity search and RAG workflows.

package/.docs/reference/rag/extract-params.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ExtractParams
 
 ExtractParams configures metadata extraction from document chunks using LLM analysis.

package/.docs/reference/rag/graph-rag.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # GraphRAG
 
 The `GraphRAG` class implements a graph-based approach to retrieval augmented generation. It creates a knowledge graph from document chunks where nodes represent documents and edges represent semantic relationships, enabling both direct similarity matching and discovery of related content through graph traversal.

package/.docs/reference/rag/metadata-filters.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Metadata filters
 
 Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.

package/.docs/reference/rag/rerank.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # rerank()
 
 The `rerank()` function provides advanced reranking capabilities for vector search results by combining semantic relevance, vector similarity, and position-based scoring.

package/.docs/reference/rag/rerankWithScorer.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # rerankWithScorer()
 
 The `rerankWithScorer()` function provides advanced reranking capabilities for vector search results by combining semantic relevance, vector similarity, and position-based scoring.

package/.docs/reference/server/create-route.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createRoute()
 
 The `createRoute()` function creates type-safe routes with Zod validation. When an `openapiPath` is configured on the server adapter, it generates OpenAPI schema entries from the supplied Zod schemas.

package/.docs/reference/server/express-adapter.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Express adapter
 
 The `@mastra/express` package provides a server adapter for running Mastra with [Express](https://expressjs.com).

package/.docs/reference/server/fastify-adapter.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Fastify adapter
 
 The `@mastra/fastify` package provides a server adapter for running Mastra with [Fastify](https://fastify.dev).

package/.docs/reference/server/hono-adapter.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Hono adapter
 
 The `@mastra/hono` package provides a server adapter for running Mastra with [Hono](https://hono.dev).

package/.docs/reference/server/koa-adapter.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Koa adapter
 
 The `@mastra/koa` package provides a server adapter for running Mastra with [Koa](https://koajs.com).

package/.docs/reference/server/mastra-server.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MastraServer
 
 The `MastraServer` abstract class is the base for all server adapters. Extend this class to create adapters for frameworks other than Hono or Express.

package/.docs/reference/server/nestjs-adapter.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # NestJS Adapter
 
 The `@mastra/nestjs` package provides a NestJS module for running Mastra with the Express-based NestJS platform.

package/.docs/reference/server/register-api-route.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # registerApiRoute()
 
 The `registerApiRoute()` function creates custom HTTP routes that integrate with the Mastra server. Routes can include OpenAPI metadata to appear in the Swagger UI documentation.

package/.docs/reference/server/routes.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Server routes
 
 Server adapters register these routes when you call `server.init()`. All routes are prefixed with the `prefix` option if configured.

package/.docs/reference/signals/create-notification-inbox-tool.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createNotificationInboxTool()
 
 **Added in:** `@mastra/core@1.39.0`

package/.docs/reference/signals/signal-provider.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # SignalProvider
 
 **Added in:** `@mastra/core@1.39.0`

package/.docs/reference/signals/task-signal-provider.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # TaskSignalProvider
 
 Bundles the built-in task tools (`task_write`, `task_update`, `task_complete`, `task_check`) and the `TaskStateProcessor` behind a single agent registration. Use it to add a structured, durable task list to an agent without wiring the tools and processor separately.

package/.docs/reference/signals/webhook-signal-provider.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # WebhookSignalProvider
 
 **Added in:** `@mastra/core@1.39.0`

package/.docs/reference/storage/clickhouse.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ClickHouse storage
 
 [ClickHouse](https://clickhouse.com/) is a columnar database designed for analytical workloads. The `@mastra/clickhouse` package provides storage adapters for several Mastra storage domains and is the recommended backend for production observability.

package/.docs/reference/storage/cloudflare-d1.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Cloudflare D1 storage
 
 The Cloudflare D1 storage implementation provides a serverless SQL database solution using Cloudflare D1, supporting relational operations and transactional consistency.

package/.docs/reference/storage/cloudflare.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Cloudflare storage
 
 Mastra provides two Cloudflare storage implementations:

package/.docs/reference/storage/composite.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Composite storage
 
 `MastraCompositeStore` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.

package/.docs/reference/storage/convex.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Convex storage
 
 The Convex storage implementation provides a serverless storage solution using [Convex](https://convex.dev), a full-stack TypeScript development platform with real-time sync and automatic caching.

package/.docs/reference/storage/dsql.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Aurora DSQL Storage
 
 The Aurora DSQL storage implementation provides storage using Amazon Aurora DSQL with IAM authentication.

package/.docs/reference/storage/duckdb.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # DuckDB storage
 
 [DuckDB](https://duckdb.org/) is an embedded, in-process analytical database. The `@mastra/duckdb` package provides an OLAP-backed observability store for local development, suitable for traces, logs, metrics, scores, and feedback without running an external service.

package/.docs/reference/storage/dynamodb.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # DynamoDB storage
 
 The DynamoDB storage implementation provides a scalable and performant NoSQL database solution for Mastra, leveraging a single-table design pattern with [ElectroDB](https://electrodb.dev/).

package/.docs/reference/storage/lance.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # LanceDB storage
 
 The LanceDB storage implementation provides a high-performance storage solution using the LanceDB database system, which excels at handling both traditional data storage and vector operations.

package/.docs/reference/storage/libsql.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # libSQL storage
 
 [libSQL](https://docs.turso.tech/libsql) is an open-source, SQLite-compatible database that supports both local and remote deployments. It can be used to store message history, workflow snapshots, traces, and eval scores.

package/.docs/reference/storage/mongodb.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MongoDB storage
 
 The MongoDB storage implementation provides a scalable storage solution using MongoDB databases with support for both document storage and vector operations.

package/.docs/reference/storage/mssql.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MSSQL storage
 
 The MSSQL storage implementation provides a production-ready storage solution using Microsoft SQL Server databases.

package/.docs/reference/storage/overview.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Storage overview
 
 Mastra storage is organized into domains. Each domain owns a set of tables or collections. Depending on your adapter and configuration, you may use all domains or only a subset.

package/.docs/reference/storage/postgresql.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # PostgreSQL storage
 
 The PostgreSQL storage implementation provides a production-ready storage solution using PostgreSQL databases.

package/.docs/reference/storage/redis.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Redis Storage
 
 The Redis storage implementation provides a high-performance storage solution using direct Redis connections via [`node-redis`](https://github.com/redis/node-redis) (the official Redis client for Node.js). It supports standalone Redis, and through custom client configuration, Redis Sentinel and Cluster deployments.

package/.docs/reference/storage/retention.md

@@ -0,0 +1,180 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Storage retention
+
+Storage grows without bound by default. Retention is an opt-in, age-based cleanup system: you declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Anything you don't configure is kept forever, so there is no behavior change until you opt in.
+
+`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk — on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
+
+Retention covers **growth tables** only — tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they are not valid retention keys.
+
+The reference implementations are [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). Other adapters keep rows forever until they implement retention.
+
+## Usage example
+
+Declare `retention` on any `MastraCompositeStore` (or an adapter that extends it, such as `LibSQLStore`), then call `prune()` from your own scheduler.
+
+```typescript
+import { LibSQLStore } from '@mastra/libsql'
+
+const storage = new LibSQLStore({
+  id: 'mastra-storage',
+  url: 'file:./mastra.db',
+  retention: {
+    memory: {
+      messages: { maxAge: '30d' },
+      threads: { maxAge: '90d', batchSize: 500 },
+    },
+    observability: {
+      spans: { maxAge: '7d' },
+    },
+  },
+})
+
+// Wire this to your own cron/scheduler — Mastra never runs it for you.
+const results = await storage.prune()
+```
+
+`retention` is fully typed. Keys must be real domain keys, and each table key must be one the domain declares as retention-eligible. Passing the object straight into a store config type-checks it; if you build it standalone, use `satisfies RetentionConfig` so unknown domains or tables are compile errors:
+
+```typescript
+import type { RetentionConfig } from '@mastra/core/storage'
+
+const retention = {
+  memory: {
+    messages: { maxAge: '30d' }, // ok
+    bogus: { maxAge: '30d' }, // Error: not a memory retention table
+  },
+  bogusDomain: {}, // Error: not a storage domain
+} satisfies RetentionConfig
+```
+
+## Retention config
+
+Set the `retention` field on the store config.
+
+**retention** (`RetentionConfig`): Per-domain, per-table age policies. Unset domains and tables are kept forever.
+
+**retention.\[domain]** (`Record<TableKey, TableRetentionPolicy>`): A real storage domain key (e.g. \`memory\`, \`observability\`). Maps that domain's retention-eligible table keys to their policies.
+
+### TableRetentionPolicy
+
+**maxAge** (`Duration`): Maximum age to keep rows. Rows whose anchor timestamp is strictly older than \`Date.now() - maxAge\` are eligible for deletion. A number is milliseconds, or a string with a unit suffix: \`ms\`, \`s\`, \`m\`, \`h\`, \`d\`, \`w\` (e.g. \`'30d'\`, \`'12h'\`).
+
+**batchSize** (`number`): Rows deleted per batch. Each batch is its own transaction, which bounds lock duration and WAL growth on large tables. (Default: `1000`)
+
+### Retention-eligible tables
+
+Each domain declares which of its tables can be age-pruned and which timestamp column anchors the comparison. The anchor is chosen so `maxAge` means what you'd expect for that data: creation time for append-only logs, last activity for live state, and completion time for jobs and runs (so in-flight work is never pruned).
+
+| Domain            | Table key          | Anchor column    | `maxAge` measures                                                 |
+| ----------------- | ------------------ | ---------------- | ----------------------------------------------------------------- |
+| `memory`          | `threads`          | `createdAt`      | Thread age                                                        |
+| `memory`          | `messages`         | `createdAt`      | Message age                                                       |
+| `memory`          | `resources`        | `createdAt`      | Resource age                                                      |
+| `threadState`     | `threadState`      | `updatedAt`      | Inactivity — state for still-active threads survives              |
+| `observability`   | `spans`            | `startedAt`      | Span age                                                          |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (v-next only)                                    |
+| `observability`   | `logs`             | `timestamp`      | Log event age (v-next only)                                       |
+| `observability`   | `scores`           | `timestamp`      | Score event age (v-next only)                                     |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (v-next only)                                  |
+| `scores`          | `scorers`          | `createdAt`      | Score record age                                                  |
+| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity — suspended or long-running workflows survive          |
+| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion — in-flight tasks (`NULL`) are never pruned |
+| `experiments`     | `experiments`      | `completedAt`    | Time since completion — running experiments are never pruned      |
+| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                  |
+| `harness`         | `sessions`         | `createdAt`      | Session record age                                                |
+| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                                |
+
+> **Note:**
+>
+> - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
+> - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. There is no separate `results` key.
+> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire) — schedule definitions are config and are not pruned.
+> - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
+> - LibSQL supports all domains above; PostgreSQL and MongoDB support all except `threadState` and `harness`, which they don't implement.
+> - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows — effective granularity is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
+
+## Methods
+
+### Retention
+
+#### `prune(options?)`
+
+Deletes rows older than their configured `maxAge` across every domain that has a policy in `retention`. Returns one `PruneResult` per table touched. With no `retention` configured it's a no-op returning `[]`.
+
+`prune()` is designed to be safe on tables with millions of rows. It deletes in bounded, batched chunks — each batch is its own transaction — so it never takes a long lock or bloats the transaction log. It never runs a `VACUUM`.
+
+Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy — never at `init()` — so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build; subsequent prunes reuse the index.
+
+```typescript
+const results = await storage.prune({
+  maxRows: 50_000, // cap work this call
+  pauseMs: 50, // breathe between batches
+})
+
+for (const r of results) {
+  console.log(`${r.domain}.${r.table}: deleted ${r.deleted}, done=${r.done}`)
+}
+```
+
+Returns: `Promise<PruneResult[]>`
+
+##### PruneOptions
+
+**maxBatches** (`number`): Maximum delete batches per table per call. When reached, that table's result is returned with \`done: false\`.
+
+**maxRows** (`number`): Maximum rows deleted per table per call. When reached, that table's result is returned with \`done: false\`.
+
+**pauseMs** (`number`): Delay in milliseconds between batches, to avoid starving live traffic.
+
+**signal** (`AbortSignal`): Cooperative cancellation. The batch loop checks it between batches and stops cleanly, returning partial results with \`done: false\`.
+
+##### PruneResult
+
+Each result describes one table's progress:
+
+```typescript
+interface PruneResult {
+  domain: string // e.g. 'memory'
+  table: string // physical table name, e.g. 'mastra_messages'
+  deleted: number // rows deleted during this call
+  done: boolean // false => eligible rows remain; call prune() again
+}
+```
+
+## Running prune on a schedule
+
+`prune()` has no built-in scheduler — you decide when it runs. Because it is bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
+
+```typescript
+// Runs on your own cron (node-cron, a workflow schedule, an external job, etc.).
+async function retentionTick() {
+  const results = await storage.prune({ maxRows: 100_000, pauseMs: 25 })
+  const incomplete = results.filter(r => !r.done)
+  if (incomplete.length) {
+    // Rows remain; the next scheduled tick will continue where this one stopped.
+    console.log(
+      'retention still draining:',
+      incomplete.map(r => `${r.domain}.${r.table}`),
+    )
+  }
+}
+```
+
+You can also cancel a long-running prune with an `AbortSignal` — the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
+
+## Reclaiming disk
+
+`prune()` deletes rows but does not shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing — for most users this alone solves the unbounded-growth problem.
+
+Handing that free space back to the OS is a separate concern that Mastra does not manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself, in a maintenance window — a full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically; a manual `VACUUM FULL` is only needed if you must return disk to the OS.
+
+> **LibSQL and Turso:** [Turso Cloud](https://mastra.ai/reference/storage/libsql) manages storage compaction for you, so there's nothing to reclaim manually. This applies only to self-hosted libSQL files.
+
+## Related
+
+- [libSQL storage](https://mastra.ai/reference/storage/libsql)
+- [PostgreSQL storage](https://mastra.ai/reference/storage/postgresql)
+- [Composite storage](https://mastra.ai/reference/storage/composite)
+- [Storage overview](https://mastra.ai/reference/storage/overview)