@mastra/libsql 1.15.1 → 1.16.0-alpha.0

package/dist/docs/references/reference-file-based-agents-memory.md

@@ -0,0 +1,58 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory
+
+A file-based agent gets [memory](https://mastra.ai/docs/memory/overview) from a `memory.ts` file that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance. Use this page for the file-based convention; use the memory docs for message history, semantic recall, storage, and processors.
+
+Without `memory.ts` or `config.memory`, the agent has no memory by default. Each `generate()` or `stream()` call starts without remembered conversation state unless you pass the prior context yourself.
+
+## Quickstart
+
+Create `memory.ts` next to the agent's `config.ts`:
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory()
+```
+
+The exported instance becomes the agent's `memory`. If your app configures a storage provider on the main Mastra instance, memory data is stored there. See [storage](https://mastra.ai/docs/storage/overview) for more information.
+
+Use the same `resource` and `thread` values when calling the agent to continue a conversation:
+
+```typescript
+const response = await weatherAgent.generate('Remember that I prefer Celsius.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'weather-chat',
+  },
+})
+```
+
+## Configure memory
+
+Pass options to `new Memory()` when the default behavior isn't enough.
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory({
+  options: {
+    lastMessages: 20,
+    workingMemory: {
+      enabled: true,
+      scope: 'resource',
+    },
+  },
+})
+```
+
+Visit the [`Memory` reference](https://mastra.ai/reference/memory/memory-class) for constructor options. Use these pages for related memory features:
+
+- [Storage](https://mastra.ai/docs/storage/overview): configure persistence for memory data.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): retrieve relevant past messages by semantic meaning.
+- [Memory processors](https://mastra.ai/docs/memory/memory-processors): filter, trim, or transform messages before memory adds them to model context.
+
+## Precedence with config
+
+`config.memory` wins over `memory.ts`. If neither is present, the assembled file-based agent has no memory. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.

package/dist/docs/references/reference-file-based-agents-storage.md

@@ -0,0 +1,30 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Storage
+
+Mastra sets the project's default [storage](https://mastra.ai/docs/storage/overview) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
+
+Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage/overview).
+
+## Quickstart
+
+Use [`LibSQLStore`](https://mastra.ai/reference/storage/libsql) for a local file-backed store:
+
+```typescript
+import { LibSQLStore } from '@mastra/libsql'
+
+export default new LibSQLStore({
+  id: 'mastra-storage',
+  url: 'file:./mastra.db',
+})
+```
+
+Mastra registers the store before file-based agents and workflows, so storage-dependent primitives bind to this store instead of the default in-memory store.
+
+## Production backends
+
+`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability storage](https://mastra.ai/docs/observability/storage), and the [storage reference](https://mastra.ai/reference/storage/overview).
+
+## Precedence with code
+
+Code-registered storage wins over `storage.ts`. Use `storage.ts` when one project-wide store is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

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

@@ -37,7 +37,7 @@ export const agent = new Agent({
 
 **options** (`MemoryConfig`): Memory configuration options.
 
-**options.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.
+**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option.
 
 **options.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.
 

package/dist/docs/references/reference-storage-composite.md

@@ -37,25 +37,25 @@ You'll also need to install the storage providers you want to compose:
 **npm**:
 
 ```bash
-npm install @mastra/pg@latest @mastra/libsql@latest
+npm install @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **pnpm**:
 
 ```bash
-pnpm add @mastra/pg@latest @mastra/libsql@latest
+pnpm add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **Yarn**:
 
 ```bash
-yarn add @mastra/pg@latest @mastra/libsql@latest
+yarn add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **Bun**:
 
 ```bash
-bun add @mastra/pg@latest @mastra/libsql@latest
+bun add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 ## Storage domains
@@ -124,6 +124,64 @@ export const mastra = new Mastra({
 })
 ```
 
+### Mixed backends
+
+Use domain classes from each storage package to route different domains to different backends. The following example stores memory and workflow state in MongoDB, then routes observability to ClickHouse:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'
+import { MemoryStorageMongoDB, WorkflowsStorageMongoDB } from '@mastra/mongodb'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    domains: {
+      memory: new MemoryStorageMongoDB({
+        uri: process.env.MONGODB_URI,
+        dbName: 'mastra_memory',
+      }),
+      workflows: new WorkflowsStorageMongoDB({
+        uri: process.env.MONGODB_URI,
+        dbName: 'mastra_workflows',
+      }),
+      observability: new ObservabilityStorageClickhouse({
+        url: process.env.CLICKHOUSE_URL,
+        username: process.env.CLICKHOUSE_USERNAME,
+        password: process.env.CLICKHOUSE_PASSWORD,
+      }),
+    },
+  }),
+})
+```
+
+### Disabling a domain
+
+Set a domain to `false` to disable it. A disabled domain doesn't fall back to `default`, so data for that domain isn't persisted:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg',
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    default: pgStore,
+    domains: {
+      // don't persist traces and spans
+      observability: false,
+    },
+  }),
+})
+```
+
 ## Options
 
 **id** (`string`): Unique identifier for this storage instance.
@@ -132,7 +190,7 @@ export const mastra = new Mastra({
 
 **disableInit** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
 
-**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage.
+**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage. Set a domain to false to disable it entirely; a disabled domain does not fall back to editor or default.
 
 **domains.memory** (`MemoryStorage`): Storage for threads, messages, and resources.
 
@@ -274,6 +332,6 @@ const storage = new MastraCompositeStore({
 })
 ```
 
-Do not set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
+Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
 
 > **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for the full list of supported providers.

package/dist/docs/references/reference-storage-dynamodb.md

@@ -6,7 +6,7 @@ The DynamoDB storage implementation provides a scalable and performant NoSQL dat
 
 > **Observability Not Supported:** DynamoDB storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to DynamoDB, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
-> **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
+> **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/memory-processors) for workarounds including uploading attachments to external storage.
 
 ## Features
 

package/dist/docs/references/reference-storage-retention.md

@@ -6,7 +6,7 @@ Storage grows without bound by default. Retention is an opt-in, age-based cleanu
 
 `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.
+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're 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.
 
@@ -89,8 +89,8 @@ Each domain declares which of its tables can be age-pruned and which timestamp c
 > **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.
+> - 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. Retention doesn't have a separate `results` key.
+> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire) — schedule definitions are config and aren't 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.
@@ -105,6 +105,8 @@ Deletes rows older than their configured `maxAge` across every domain that has a
 
 `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`.
 
+Pass `options.retention` to replace the configured policies for that call only — for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
+
 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
@@ -116,6 +118,13 @@ const results = await storage.prune({
 for (const r of results) {
   console.log(`${r.domain}.${r.table}: deleted ${r.deleted}, done=${r.done}`)
 }
+
+// One-off pass with different policies (configured retention untouched):
+await storage.prune({
+  retention: {
+    observability: { spans: { maxAge: '1d' } },
+  },
+})
 ```
 
 Returns: `Promise<PruneResult[]>`
@@ -130,6 +139,8 @@ Returns: `Promise<PruneResult[]>`
 
 **signal** (`AbortSignal`): Cooperative cancellation. The batch loop checks it between batches and stops cleanly, returning partial results with done: false.
 
+**retention** (`RetentionConfig`): Replaces the store's configured retention policies for this call only — e.g. to skip a domain or prune more aggressively. The configured retention is unchanged.
+
 ##### PruneResult
 
 Each result describes one table's progress:
@@ -145,7 +156,7 @@ interface PruneResult {
 
 ## 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.
+`prune()` has no built-in scheduler — you decide when it runs. Because it's 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.).
@@ -164,11 +175,68 @@ async function retentionTick() {
 
 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.
 
+## MongoDB TTL indexes (alternative to prune)
+
+MongoDB offers native [TTL (Time-To-Live) indexes](https://www.mongodb.com/docs/manual/core/index-ttl/) that automatically delete expired documents without requiring manual `prune()` calls. This is a database-level feature that runs as a background thread.
+
+> **When to use TTL vs prune():** **Use MongoDB TTL indexes when:**
+>
+> - You want automated, zero-maintenance deletion
+> - Your retention periods are fixed (e.g., "always 30 days")
+> - You prefer database-native solutions
+>
+> **Use `prune()` when:**
+>
+> - You need fine-grained control over deletion timing
+> - You want to cap deletion rate during business hours
+> - You need resumable, cancellable cleanup operations
+> - You're using composite storage with multiple databases
+>
+> Both approaches are valid. TTL is simpler; `prune()` gives more control.
+
+### Setting up TTL indexes on MongoDB
+
+TTL indexes work on date fields. MongoDB checks the index every 60 seconds and deletes documents where the date field + TTL duration < current time.
+
+```typescript
+import { MongoDBStore } from '@mastra/mongodb'
+
+const storage = new MongoDBStore({
+  id: 'mongodb-storage',
+  uri: process.env.MONGODB_URI!,
+  dbName: process.env.MONGODB_DB_NAME!,
+  indexes: [
+    // Messages expire after 30 days
+    {
+      collection: 'mastra_messages',
+      keys: { createdAt: 1 },
+      options: { expireAfterSeconds: 30 * 24 * 60 * 60 }, // 30 days
+    },
+    // Threads expire after 90 days
+    {
+      collection: 'mastra_threads',
+      keys: { createdAt: 1 },
+      options: { expireAfterSeconds: 90 * 24 * 60 * 60 }, // 90 days
+    },
+    // Spans expire after 7 days
+    {
+      collection: 'mastra_ai_spans',
+      keys: { startedAt: 1 },
+      options: { expireAfterSeconds: 7 * 24 * 60 * 60 }, // 7 days
+    },
+  ],
+})
+```
+
+> **Tip:** TTL indexes delete documents shortly after they expire (background thread runs every \~60 seconds), but the exact timing is not guaranteed. For precise, immediate cleanup, use `prune()` instead.
+
 ## 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.
+`prune()` deletes rows but doesn't 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 doesn't 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.
 
-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.
+For MongoDB, deleted documents are reused by future insertions. To reclaim disk space, run [`db.runCommand({ compact: "collection_name" })`](https://www.mongodb.com/docs/manual/reference/command/compact/) during a maintenance window.
 
 > **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.
 

package/dist/index.cjs

@@ -545,6 +545,31 @@ var LibSQLVector = class extends vector.MastraVector {
     }
     this.vectorIndexes = this.isMemoryDb ? Promise.resolve(/* @__PURE__ */ new Set()) : this.discoverVectorIndexes();
   }
+  /**
+   * Closes the underlying libsql client, releasing all OS file handles.
+   *
+   * For local file databases, first runs PRAGMA wal_checkpoint(TRUNCATE) and
+   * switches back to journal_mode=DELETE so the -wal and -shm sidecar files
+   * are released promptly (mirrors LibSQLStore.close()).
+   *
+   * Remote (Turso) databases skip the WAL pragmas and just close the client.
+   *
+   * Safe to call more than once; subsequent calls are no-ops.
+   */
+  async close() {
+    if (this.turso.closed) {
+      return;
+    }
+    if (this.turso.protocol === "file" && !this.isMemoryDb) {
+      try {
+        await this.turso.execute("PRAGMA wal_checkpoint(TRUNCATE);");
+        await this.turso.execute("PRAGMA journal_mode=DELETE;");
+      } catch (err) {
+        this.logger.warn("LibSQLVector: Failed to checkpoint WAL before close.", err);
+      }
+    }
+    this.turso.close();
+  }
   async discoverVectorIndexes() {
     try {
       const result = await this.turso.execute({