@mastra/convex 0.0.0-top-level-fix-20251211111608 → 0.0.0-unified-workspace-snapshot-20260128233410

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**: 1.0.0
+> **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": "1.0.0",
+  "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-G5FLGAPE.js"
+    },
+    "TABLE_RESOURCES": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "TABLE_SCORERS": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "TABLE_THREADS": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "TABLE_WORKFLOW_SNAPSHOT": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraDocumentsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraMessagesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraResourcesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraScoresTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraThreadsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraVectorIndexesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraVectorsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraWorkflowSnapshotsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    }
+  },
+  "modules": {}
+}

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

@@ -0,0 +1,146 @@
+# 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.
+
+> **Observability Not Supported**
+Convex storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to Convex, and Mastra Studio's observability features won't work with Convex as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability-recommended-for-production) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+
+> **Record Size Limit**
+Convex enforces a **1 MiB maximum record 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#handling-large-attachments) for workarounds including uploading attachments to external storage like S3, Cloudflare R2, or [Convex file storage](https://docs.convex.dev/file-storage).
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/convex@latest
+```
+
+## 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 npm2yarn
+npm install @mastra/convex@latest
+```
+
+## 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/)