@mastra/pg 1.14.3-alpha.0 → 1.15.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @mastra/pg
 
+## 1.15.0-alpha.0
+
+### Minor Changes
+
+- Added storage retention support to PostgreSQL. When you set a `retention` config, `PostgresStore` can prune old rows from every growth-table domain it implements: `memory` (threads, messages, resources by `createdAtZ`), `observability` (spans by `startedAtZ`), `scores` (by `createdAtZ`), `workflows` (run snapshots by `updatedAtZ`), `backgroundTasks` (by `completedAtZ`, so in-flight tasks are never pruned), `experiments` (whole runs by `completedAtZ`, results cascade with their parent), `notifications` (by `createdAtZ`), and `schedules` fire history (by `actual_fire_at`). ([#18733](https://github.com/mastra-ai/mastra/pull/18733))
+
+  Deletes run in batches via `ctid` subqueries (bounded, resumable, and cancellable) so they stay safe on large tables. Anchor-column indexes are created lazily on the first `prune()` call — never at init — so deployments that don't configure retention pay no extra index overhead. `prune()` only deletes rows; PostgreSQL's autovacuum reclaims the dead tuples for reuse.
+
+  The v-next observability domain (day-partitioned signal event tables: `spans`, `metrics`, `logs`, `scores`, `feedback`) is also covered: `prune()` drops whole day partitions — TimescaleDB chunks via `drop_chunks()`, pg_partman children and native partitions via detach + drop — that are entirely older than the cutoff, so aging out event data is a metadata operation instead of a row-by-row delete.
+
+  ```typescript
+  const storage = new PostgresStore({
+    id: 'mastra-storage',
+    connectionString: process.env.DATABASE_URL,
+    retention: {
+      memory: { messages: { maxAge: '30d' } },
+      observability: { spans: { maxAge: '7d' } },
+    },
+  });
+
+  await storage.prune();
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`700619b`](https://github.com/mastra-ai/mastra/commit/700619b61d572e592cbaaf758121d168844ca4d2), [`0c3d4bc`](https://github.com/mastra-ai/mastra/commit/0c3d4bcae13ea3699d379403e6f350d5cf4efe9f), [`17369b2`](https://github.com/mastra-ai/mastra/commit/17369b25250561e9ed994ae509be1d15bfb33bcb), [`bcae929`](https://github.com/mastra-ai/mastra/commit/bcae929945cbf265bd9f327cc715ecafa072b5b9), [`b33822e`](https://github.com/mastra-ai/mastra/commit/b33822e8d470884954b02f7b0745407ee4ef74b1), [`d5c11e3`](https://github.com/mastra-ai/mastra/commit/d5c11e3ba5045969caa7272a7bd1fd141c93ab6c), [`ff80671`](https://github.com/mastra-ai/mastra/commit/ff8067185e208b27198b4e5b71803013175c3643), [`dab1257`](https://github.com/mastra-ai/mastra/commit/dab1257b64e4ed576dc5038bb7a3f7072338bc9f), [`705ff39`](https://github.com/mastra-ai/mastra/commit/705ff3969e57214ff2fdaf3815d751dd558886ed), [`e6fbd5b`](https://github.com/mastra-ai/mastra/commit/e6fbd5bfdc28e92c0c0433f29aa1bc152d3430f6), [`6f2026c`](https://github.com/mastra-ai/mastra/commit/6f2026cdf114ff1e21e49133ca774ec7d5085059), [`f890eda`](https://github.com/mastra-ai/mastra/commit/f890eda2c8a2ae83d9b30bc6d85842f93b6c266b)]:
+  - @mastra/core@1.49.0-alpha.3
+
+## 1.14.3
+
+### Patch Changes
+
+- Fixed buffered observation extraction metadata so stored OM chunks keep extracted values and extraction failures across memory storage adapters. ([#18655](https://github.com/mastra-ai/mastra/pull/18655))
+
+- Updated dependencies [[`b9a2961`](https://github.com/mastra-ai/mastra/commit/b9a2961c1be81e3639c0879e58588c26dd0ae866), [`b33c77d`](https://github.com/mastra-ai/mastra/commit/b33c77d5293f14a794f3ec38dc947a6676de2764), [`1274eb3`](https://github.com/mastra-ai/mastra/commit/1274eb3a9508f579ceb3187fbce34408222d4b71), [`cdd5f93`](https://github.com/mastra-ai/mastra/commit/cdd5f939cefa67390629704dce92563ccbf492b2), [`1274eb3`](https://github.com/mastra-ai/mastra/commit/1274eb3a9508f579ceb3187fbce34408222d4b71), [`0ac14ce`](https://github.com/mastra-ai/mastra/commit/0ac14cea48e1b0a7857782153c78f7242fdf7e1a), [`9566d27`](https://github.com/mastra-ai/mastra/commit/9566d27ead3d95bdbe5a69e5a082a68222829cf2), [`8be63b0`](https://github.com/mastra-ai/mastra/commit/8be63b015fb8d72cea1220f05e7dc3bb997cc249), [`1009f77`](https://github.com/mastra-ai/mastra/commit/1009f772aa40016b49267c8566d0c29f6a16aa3c), [`1b8728a`](https://github.com/mastra-ai/mastra/commit/1b8728a57fd844205a452b0b4216d20ff60c784a), [`23c31de`](https://github.com/mastra-ai/mastra/commit/23c31de96ed8153402dcf092ac84b27a0c3638c1), [`0368766`](https://github.com/mastra-ai/mastra/commit/0368766744c7ea3df4d6059e2cc15f7bdf55f5a6), [`6f578ac`](https://github.com/mastra-ai/mastra/commit/6f578acba84930b406b2a0700b17cfdfaf5aae56), [`345eecc`](https://github.com/mastra-ai/mastra/commit/345eecce6ba519b5d987f0e10b5de4c8e5734580), [`1917c53`](https://github.com/mastra-ai/mastra/commit/1917c53b19dac43926f29c496893b0686462dca4), [`c01012f`](https://github.com/mastra-ai/mastra/commit/c01012f50368d29eb3fc3764df42d48291973d23), [`705ba98`](https://github.com/mastra-ai/mastra/commit/705ba98726d388a596e896225f237907ca6807a9), [`95857bc`](https://github.com/mastra-ai/mastra/commit/95857bcd6669da7193f503e803f0d72a2bd66be6), [`e62c108`](https://github.com/mastra-ai/mastra/commit/e62c108409dfd6a6cac0a48ec39c5cc81d24fd52), [`2866f04`](https://github.com/mastra-ai/mastra/commit/2866f04953edb78c1637fa45cc53abe24122edcb), [`ee14cae`](https://github.com/mastra-ai/mastra/commit/ee14cae244805783bde518a6142de28b744b169c), [`e84e791`](https://github.com/mastra-ai/mastra/commit/e84e79174031d7bc8793ca6c805eb38b06e7cfb1), [`c2f0b7f`](https://github.com/mastra-ai/mastra/commit/c2f0b7f1370f4428d165f51f0d1d9a48331cc257), [`213feb8`](https://github.com/mastra-ai/mastra/commit/213feb87bfdd1d8ec00ea660e218f9bcfcb34e7b), [`58e287b`](https://github.com/mastra-ai/mastra/commit/58e287b1edaf978b13745a1795989cad3826e82b), [`e420b3c`](https://github.com/mastra-ai/mastra/commit/e420b3c3ffc98bbc5b791897ea390bb47af99696), [`be875ed`](https://github.com/mastra-ai/mastra/commit/be875ed43f856742ce58529f531b5ea0ae6911f3), [`9eefdc0`](https://github.com/mastra-ai/mastra/commit/9eefdc0ac03f989718c6d835334940a977938895), [`bfbbb01`](https://github.com/mastra-ai/mastra/commit/bfbbb01bd845ba54cdc0c678c277d08a7cb847e4), [`7d112ca`](https://github.com/mastra-ai/mastra/commit/7d112ca17078479b2659b88ba1c85b936cfc111c)]:
+  - @mastra/core@1.48.0
+
 ## 1.14.3-alpha.0
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-pg
 description: Documentation for @mastra/pg. Use when working with @mastra/pg APIs, configuration, or implementation.
 metadata:
   package: "@mastra/pg"
-  version: "1.14.3-alpha.0"
+  version: "1.15.0-alpha.0"
 ---
 
 ## When to use
@@ -33,6 +33,7 @@ Read the individual reference documents for detailed explanations and code examp
 - [Reference: Composite storage](references/reference-storage-composite.md) - Documentation for combining multiple storage backends in Mastra.
 - [Reference: DynamoDB storage](references/reference-storage-dynamodb.md) - Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.
 - [Reference: PostgreSQL storage](references/reference-storage-postgresql.md) - Documentation for the PostgreSQL storage implementation in Mastra.
+- [Reference: Storage retention (prune)](references/reference-storage-retention.md) - API reference for retention policies and prune() on Mastra storage.
 - [Reference: createVectorQueryTool()](references/reference-tools-vector-query-tool.md) - Documentation for the Vector Query Tool in Mastra, which facilitates semantic search over vector stores with filtering and reranking capabilities.
 - [Reference: PG vector store](references/reference-vectors-pg.md) - Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.14.3-alpha.0",
+  "version": "1.15.0-alpha.0",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Semantic recall
 
 If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
@@ -130,6 +132,7 @@ The following options control semantic recall behavior:
 
 ```typescript
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     options: {
       semanticRecall: {
@@ -151,6 +154,7 @@ The `filter` option restricts semantic recall results to messages with matching
 
 ```typescript
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     options: {
       semanticRecall: {
@@ -217,6 +221,7 @@ import { Agent } from '@mastra/core/agent'
 import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
     options: {
@@ -238,6 +243,7 @@ import { Memory } from '@mastra/memory'
 import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel({
       providerId: 'openrouter',
@@ -259,6 +265,7 @@ import { Agent } from '@mastra/core/agent'
 import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   }),
@@ -301,6 +308,7 @@ import { Agent } from '@mastra/core/agent'
 import { fastembed } from '@mastra/fastembed'
 
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     embedder: fastembed,
   }),

package/dist/docs/references/docs-memory-storage.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Storage
 
 For agents to remember previous interactions, Mastra needs a storage adapter. Use one of the [supported providers](#supported-providers) and pass it to your Mastra instance.
@@ -100,6 +102,10 @@ export const mastra = new Mastra({
 
 This is useful when different types of data have different performance or operational requirements, such as low-latency storage for memory, durable storage for workflows, and high-throughput storage for observability.
 
+#### Retention
+
+Storage grows without bound by default. To cap growth, declare per-table `maxAge` policies in the `retention` config and call `storage.prune()` from your own scheduler to delete old rows. Anything you don't configure is kept forever. See [Storage retention](https://mastra.ai/reference/storage/retention) for `prune()` and the full config shape.
+
 ### Agent-level storage
 
 Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need to keep data separate or use different providers per agent.

package/dist/docs/references/docs-memory-working-memory.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Working Memory
 
 While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.

package/dist/docs/references/docs-rag-overview.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # RAG (Retrieval-Augmented Generation) in Mastra
 
 RAG in Mastra helps you enhance LLM outputs by incorporating relevant context from your own data sources, improving accuracy and grounding responses in real information.

package/dist/docs/references/docs-rag-retrieval.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Retrieval in RAG systems
 
 After storing embeddings, you need to retrieve relevant chunks to answer user queries.

package/dist/docs/references/docs-rag-vector-databases.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Storing embeddings in a vector database
 
 After generating embeddings, you need to store them in a database that supports vector similarity search. Mastra provides a consistent interface for storing and querying embeddings across various vector databases.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # 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.
@@ -9,6 +11,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'test-agent',
   name: 'test-agent',
   instructions: 'You are an agent with memory.',
   model: 'openai/gpt-5.5',

package/dist/docs/references/reference-processors-message-history-processor.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MessageHistory
 
 The `MessageHistory` is a **hybrid processor** that handles both retrieval and persistence of message history. On input, it fetches historical messages from storage and prepends them to the conversation. On output, it persists new messages to storage.
@@ -43,6 +45,7 @@ const storage = new PostgresStorage({
 })
 
 export const agent = new Agent({
+  id: 'memory-agent',
   name: 'memory-agent',
   instructions: 'You are a helpful assistant with conversation memory',
   model: 'openai/gpt-5.5',

package/dist/docs/references/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.
@@ -80,6 +82,7 @@ const semanticRecall = new SemanticRecall({
 })
 
 export const agent = new Agent({
+  id: 'semantic-memory-agent',
   name: 'semantic-memory-agent',
   instructions: 'You are a helpful assistant with semantic memory recall',
   model: 'openai/gpt-5.5',

package/dist/docs/references/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.
@@ -65,6 +67,7 @@ const storage = new PostgresStorage({
 })
 
 export const agent = new Agent({
+  id: 'personalized-agent',
   name: 'personalized-agent',
   instructions: 'You are a helpful assistant that remembers user preferences',
   model: 'openai/gpt-5.5',

package/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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)

package/dist/docs/references/reference-tools-vector-query-tool.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createVectorQueryTool()
 
 The `createVectorQueryTool()` function creates a tool for semantic search over vector stores. It supports filtering, reranking, database-specific configurations, and integrates with various vector store backends.

package/dist/docs/references/reference-vectors-pg.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # PG vector store
 
 The PgVector class provides vector search using [PostgreSQL](https://www.postgresql.org/) with [pgvector](https://github.com/pgvector/pgvector) extension. It provides robust vector similarity search capabilities within your existing PostgreSQL database.