@mastra/convex 0.1.0-beta.7 → 0.1.0-beta.8

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @mastra/convex
 
+## 0.1.0-beta.8
+
+### Patch Changes
+
+- Add embedded documentation support for Mastra packages ([#11472](https://github.com/mastra-ai/mastra/pull/11472))
+
+  Mastra packages now include embedded documentation in the published npm package under `dist/docs/`. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from `node_modules`.
+
+  Each package includes:
+  - **SKILL.md** - Entry point explaining the package's purpose and capabilities
+  - **SOURCE_MAP.json** - Machine-readable index mapping exports to types and implementation files
+  - **Topic folders** - Conceptual documentation organized by feature area
+
+  Documentation is driven by the `packages` frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
+
+- Added `startExclusive` and `endExclusive` options to `dateRange` filter for message queries. ([#11479](https://github.com/mastra-ai/mastra/pull/11479))
+
+  **What changed:** The `filter.dateRange` parameter in `listMessages()` and `Memory.recall()` now supports `startExclusive` and `endExclusive` boolean options. When set to `true`, messages with timestamps exactly matching the boundary are excluded from results.
+
+  **Why this matters:** Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using `endExclusive: true` with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.
+
+  **Example:**
+
+  ```typescript
+  // Get first page
+  const page1 = await memory.recall({
+    threadId: 'thread-123',
+    perPage: 10,
+    orderBy: { field: 'createdAt', direction: 'DESC' },
+  });
+
+  // Get next page using cursor-based pagination
+  const oldestMessage = page1.messages[page1.messages.length - 1];
+  const page2 = await memory.recall({
+    threadId: 'thread-123',
+    perPage: 10,
+    orderBy: { field: 'createdAt', direction: 'DESC' },
+    filter: {
+      dateRange: {
+        end: oldestMessage.createdAt,
+        endExclusive: true, // Excludes the cursor message
+      },
+    },
+  });
+  ```
+
+- Updated dependencies [[`d2d3e22`](https://github.com/mastra-ai/mastra/commit/d2d3e22a419ee243f8812a84e3453dd44365ecb0), [`bc72b52`](https://github.com/mastra-ai/mastra/commit/bc72b529ee4478fe89ecd85a8be47ce0127b82a0), [`05b8bee`](https://github.com/mastra-ai/mastra/commit/05b8bee9e50e6c2a4a2bf210eca25ee212ca24fa), [`c042bd0`](https://github.com/mastra-ai/mastra/commit/c042bd0b743e0e86199d0cb83344ca7690e34a9c), [`940a2b2`](https://github.com/mastra-ai/mastra/commit/940a2b27480626ed7e74f55806dcd2181c1dd0c2), [`e0941c3`](https://github.com/mastra-ai/mastra/commit/e0941c3d7fc75695d5d258e7008fd5d6e650800c), [`0c0580a`](https://github.com/mastra-ai/mastra/commit/0c0580a42f697cd2a7d5973f25bfe7da9055038a), [`28f5f89`](https://github.com/mastra-ai/mastra/commit/28f5f89705f2409921e3c45178796c0e0d0bbb64), [`e601b27`](https://github.com/mastra-ai/mastra/commit/e601b272c70f3a5ecca610373aa6223012704892), [`3d3366f`](https://github.com/mastra-ai/mastra/commit/3d3366f31683e7137d126a3a57174a222c5801fb), [`5a4953f`](https://github.com/mastra-ai/mastra/commit/5a4953f7d25bb15ca31ed16038092a39cb3f98b3), [`eb9e522`](https://github.com/mastra-ai/mastra/commit/eb9e522ce3070a405e5b949b7bf5609ca51d7fe2), [`20e6f19`](https://github.com/mastra-ai/mastra/commit/20e6f1971d51d3ff6dd7accad8aaaae826d540ed), [`4f0b3c6`](https://github.com/mastra-ai/mastra/commit/4f0b3c66f196c06448487f680ccbb614d281e2f7), [`74c4f22`](https://github.com/mastra-ai/mastra/commit/74c4f22ed4c71e72598eacc346ba95cdbc00294f), [`81b6a8f`](https://github.com/mastra-ai/mastra/commit/81b6a8ff79f49a7549d15d66624ac1a0b8f5f971), [`e4d366a`](https://github.com/mastra-ai/mastra/commit/e4d366aeb500371dd4210d6aa8361a4c21d87034), [`a4f010b`](https://github.com/mastra-ai/mastra/commit/a4f010b22e4355a5fdee70a1fe0f6e4a692cc29e), [`73b0bb3`](https://github.com/mastra-ai/mastra/commit/73b0bb394dba7c9482eb467a97ab283dbc0ef4db), [`5627a8c`](https://github.com/mastra-ai/mastra/commit/5627a8c6dc11fe3711b3fa7a6ffd6eb34100a306), [`3ff45d1`](https://github.com/mastra-ai/mastra/commit/3ff45d10e0c80c5335a957ab563da72feb623520), [`251df45`](https://github.com/mastra-ai/mastra/commit/251df4531407dfa46d805feb40ff3fb49769f455), [`f894d14`](https://github.com/mastra-ai/mastra/commit/f894d148946629af7b1f452d65a9cf864cec3765), [`c2b9547`](https://github.com/mastra-ai/mastra/commit/c2b9547bf435f56339f23625a743b2147ab1c7a6), [`580b592`](https://github.com/mastra-ai/mastra/commit/580b5927afc82fe460dfdf9a38a902511b6b7e7f), [`58e3931`](https://github.com/mastra-ai/mastra/commit/58e3931af9baa5921688566210f00fb0c10479fa), [`08bb631`](https://github.com/mastra-ai/mastra/commit/08bb631ae2b14684b2678e3549d0b399a6f0561e), [`4fba91b`](https://github.com/mastra-ai/mastra/commit/4fba91bec7c95911dc28e369437596b152b04cd0), [`12b0cc4`](https://github.com/mastra-ai/mastra/commit/12b0cc4077d886b1a552637dedb70a7ade93528c)]:
+  - @mastra/core@1.0.0-beta.20
+
 ## 0.1.0-beta.7
 
 ### Patch Changes

package/dist/docs/README.md

@@ -0,0 +1,32 @@
+# @mastra/convex Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── storage/ (1 files)
+├── vectors/ (1 files)
+```
+
+## Version
+
+Package: @mastra/convex
+Version: 0.1.0-beta.8

package/dist/docs/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: mastra-convex-docs
+description: Documentation for @mastra/convex. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/convex Documentation
+
+> **Version**: 0.1.0-beta.8
+> **Package**: @mastra/convex
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+  - mastraStorage: dist/index.d.ts
+  - TABLE_MESSAGES: dist/index.d.ts
+  - TABLE_RESOURCES: dist/index.d.ts
+  - TABLE_SCORERS: dist/index.d.ts
+  - TABLE_THREADS: dist/index.d.ts
+  - TABLE_WORKFLOW_SNAPSHOT: dist/index.d.ts
+  - mastraDocumentsTable: dist/index.d.ts
+  - mastraMessagesTable: dist/index.d.ts
+  - mastraResourcesTable: dist/index.d.ts
+  - mastraScoresTable: dist/index.d.ts
+  - mastraThreadsTable: dist/index.d.ts
+  - mastraVectorIndexesTable: dist/index.d.ts
+  - mastraVectorsTable: dist/index.d.ts
+  - mastraWorkflowSnapshotsTable: dist/index.d.ts
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Storage](storage/) - 1 file(s)
+- [Vectors](vectors/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,63 @@
+{
+  "version": "0.1.0-beta.8",
+  "package": "@mastra/convex",
+  "exports": {
+    "mastraStorage": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KSAPIIEJ.js"
+    },
+    "TABLE_MESSAGES": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "TABLE_RESOURCES": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "TABLE_SCORERS": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "TABLE_THREADS": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "TABLE_WORKFLOW_SNAPSHOT": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "mastraDocumentsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "mastraMessagesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "mastraResourcesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "mastraScoresTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "mastraThreadsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "mastraVectorIndexesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "mastraVectorsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    },
+    "mastraWorkflowSnapshotsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-HXB4DWFE.js"
+    }
+  },
+  "modules": {}
+}

package/dist/docs/storage/01-reference.md

@@ -0,0 +1,140 @@
+# Storage API Reference
+
+> API reference for storage - 1 entries
+
+
+---
+
+## Reference: Convex Storage
+
+> Documentation for the Convex storage implementation in Mastra.
+
+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.
+
+## Installation
+
+```bash
+npm install @mastra/convex@beta
+```
+
+## Convex Setup
+
+Before using `ConvexStore`, you need to set up the Convex schema and storage handler in your Convex project.
+
+### 1. Set up Convex Schema
+
+In `convex/schema.ts`:
+
+```typescript
+import { defineSchema } from 'convex/server';
+import {
+  mastraThreadsTable,
+  mastraMessagesTable,
+  mastraResourcesTable,
+  mastraWorkflowSnapshotsTable,
+  mastraScoresTable,
+  mastraVectorIndexesTable,
+  mastraVectorsTable,
+  mastraDocumentsTable,
+} from '@mastra/convex/schema';
+
+export default defineSchema({
+  mastra_threads: mastraThreadsTable,
+  mastra_messages: mastraMessagesTable,
+  mastra_resources: mastraResourcesTable,
+  mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
+  mastra_scorers: mastraScoresTable,
+  mastra_vector_indexes: mastraVectorIndexesTable,
+  mastra_vectors: mastraVectorsTable,
+  mastra_documents: mastraDocumentsTable,
+});
+```
+
+### 2. Create the Storage Handler
+
+In `convex/mastra/storage.ts`:
+
+```typescript
+import { mastraStorage } from '@mastra/convex/server';
+
+export const handle = mastraStorage;
+```
+
+### 3. Deploy to Convex
+
+```bash
+npx convex dev
+# or for production
+npx convex deploy
+```
+
+## Usage
+
+```typescript
+import { ConvexStore } from "@mastra/convex";
+
+const storage = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: process.env.CONVEX_URL!,
+  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
+});
+```
+
+## Parameters
+
+## Constructor Examples
+
+```ts
+import { ConvexStore } from "@mastra/convex";
+
+// Basic configuration
+const store = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+});
+
+// With custom storage function path
+const storeCustom = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+  storageFunction: "custom/path:handler",
+});
+```
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation uses typed Convex tables for each Mastra domain:
+
+| Domain         | Convex Table                | Purpose              |
+| -------------- | --------------------------- | -------------------- |
+| Threads        | `mastra_threads`            | Conversation threads |
+| Messages       | `mastra_messages`           | Chat messages        |
+| Resources      | `mastra_resources`          | User working memory  |
+| Workflows      | `mastra_workflow_snapshots` | Workflow state       |
+| Scorers        | `mastra_scorers`            | Evaluation data      |
+| Fallback       | `mastra_documents`          | Unknown tables       |
+
+### Architecture
+
+All typed tables include:
+
+- An `id` field for Mastra's record ID (distinct from Convex's auto-generated `_id`)
+- A `by_record_id` index for efficient lookups by Mastra ID
+
+This design ensures compatibility with Mastra's storage contract while leveraging Convex's automatic indexing and real-time capabilities.
+
+### Environment Variables
+
+Set these environment variables for your deployment:
+
+- `CONVEX_URL` – Your Convex deployment URL
+- `CONVEX_ADMIN_KEY` – Admin authentication token (get from Convex dashboard)
+
+## Related
+
+- [Convex Vector Store](../vectors/convex)
+- [Convex Documentation](https://docs.convex.dev/)

package/dist/docs/vectors/01-reference.md

@@ -0,0 +1,240 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: Convex Vector Store
+
+> Documentation for the ConvexVector class in Mastra, which provides vector search using Convex.
+
+The ConvexVector class provides vector storage and similarity search using [Convex](https://convex.dev). It stores embeddings inside Convex and performs cosine similarity search.
+
+## Installation
+
+```bash
+npm install @mastra/convex@beta
+```
+
+## Convex Setup
+
+Before using `ConvexVector`, you need to set up the Convex schema and storage handler. See [Convex Storage Setup](../storage/convex#convex-setup) for setup instructions.
+
+## Constructor Options
+
+## Constructor Examples
+
+### Basic Configuration
+
+```ts
+import { ConvexVector } from "@mastra/convex";
+
+const vectorStore = new ConvexVector({
+  id: 'convex-vectors',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+});
+```
+
+### Custom Storage Function
+
+```ts
+const vectorStore = new ConvexVector({
+  id: 'convex-vectors',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+  storageFunction: "custom/path:handler",
+});
+```
+
+## Methods
+
+### createIndex()
+
+```typescript
+await vectorStore.createIndex({
+  indexName: "my_vectors",
+  dimension: 1536,
+});
+```
+
+### upsert()
+
+```typescript
+await vectorStore.upsert({
+  indexName: "my_vectors",
+  vectors: [[0.1, 0.2, 0.3, ...]],
+  metadata: [{ label: "example" }],
+  ids: ["vec-1"],
+});
+```
+
+### query()
+
+```typescript
+const results = await vectorStore.query({
+  indexName: "my_vectors",
+  queryVector: [0.1, 0.2, 0.3, ...],
+  topK: 5,
+  filter: { category: "documents" },
+});
+```
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+```typescript
+const indexes = await vectorStore.listIndexes();
+// ["my_vectors", "embeddings", ...]
+```
+
+### describeIndex()
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+Deletes the index and all its vectors.
+
+```typescript
+await vectorStore.deleteIndex({ indexName: "my_vectors" });
+```
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+```typescript
+// Update by ID
+await vectorStore.updateVector({
+  indexName: "my_vectors",
+  id: "vector123",
+  update: {
+    vector: [0.1, 0.2, 0.3],
+    metadata: { label: "updated" },
+  },
+});
+
+// Update by filter
+await vectorStore.updateVector({
+  indexName: "my_vectors",
+  filter: { category: "product" },
+  update: {
+    metadata: { status: "reviewed" },
+  },
+});
+```
+
+### deleteVector()
+
+```typescript
+await vectorStore.deleteVector({ indexName: "my_vectors", id: "vector123" });
+```
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+```typescript
+// Delete by IDs
+await vectorStore.deleteVectors({
+  indexName: "my_vectors",
+  ids: ["vec1", "vec2", "vec3"],
+});
+
+// Delete by filter
+await vectorStore.deleteVectors({
+  indexName: "my_vectors",
+  filter: { status: "archived" },
+});
+```
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Metadata Filtering
+
+ConvexVector supports metadata filtering with various operators:
+
+```typescript
+// Simple equality
+const results = await vectorStore.query({
+  indexName: "my_vectors",
+  queryVector: embedding,
+  filter: { category: "documents" },
+});
+
+// Comparison operators
+const results = await vectorStore.query({
+  indexName: "my_vectors",
+  queryVector: embedding,
+  filter: {
+    price: { $gt: 100 },
+    status: { $in: ["active", "pending"] },
+  },
+});
+
+// Logical operators
+const results = await vectorStore.query({
+  indexName: "my_vectors",
+  queryVector: embedding,
+  filter: {
+    $and: [
+      { category: "electronics" },
+      { price: { $lte: 500 } },
+    ],
+  },
+});
+```
+
+### Supported Filter Operators
+
+| Operator | Description |
+| -------- | ----------- |
+| `$eq` | Equal to |
+| `$ne` | Not equal to |
+| `$gt` | Greater than |
+| `$gte` | Greater than or equal |
+| `$lt` | Less than |
+| `$lte` | Less than or equal |
+| `$in` | In array |
+| `$nin` | Not in array |
+| `$and` | Logical AND |
+| `$or` | Logical OR |
+
+## Architecture
+
+ConvexVector stores vectors in the `mastra_vectors` table with the following structure:
+
+- `id`: Unique vector identifier
+- `indexName`: Name of the index
+- `embedding`: The vector data (array of floats)
+- `metadata`: Optional JSON metadata
+
+Vector similarity search is performed using cosine similarity, computed in the Convex function.
+
+## Related
+
+- [Convex Storage](../storage/convex)
+- [Metadata Filters](../rag/metadata-filters)
+- [Convex Documentation](https://docs.convex.dev/)

package/dist/index.cjs

@@ -295,15 +295,7 @@ var MemoryConvex = class extends storage.MemoryStorage {
     if (resourceId) {
       rows = rows.filter((row) => row.resourceId === resourceId);
     }
-    if (filter?.dateRange) {
-      const { start, end } = filter.dateRange;
-      rows = rows.filter((row) => {
-        const created = new Date(row.createdAt).getTime();
-        if (start && created < start.getTime()) return false;
-        if (end && created > end.getTime()) return false;
-        return true;
-      });
-    }
+    rows = storage.filterByDateRange(rows, (row) => new Date(row.createdAt), filter?.dateRange);
     rows.sort((a, b) => {
       const aValue = field === "createdAt" || field === "updatedAt" ? new Date(a[field]).getTime() : a[field];
       const bValue = field === "createdAt" || field === "updatedAt" ? new Date(b[field]).getTime() : b[field];