@o-zakstam/voltagent-convex 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 VoltAgent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# @o-zakstam/voltagent-convex
+
+Convex Storage Adapter for [VoltAgent](https://voltagent.dev) - A StorageAdapter implementation that persists conversation history, working memory, and workflow state to a [Convex](https://convex.dev) database using Convex Components.
+
+## Features
+
+- Full `StorageAdapter` interface implementation
+- Convex Component architecture for clean integration
+- Conversation and message persistence
+- Working memory support (conversation and user scopes)
+- Workflow state management for suspendable workflows
+- Conversation steps for observability
+- Real-time updates with Convex subscriptions
+- TypeScript support with full type definitions
+
+## Installation
+
+```bash
+npm install @o-zakstam/voltagent-convex convex
+# or
+pnpm add @o-zakstam/voltagent-convex convex
+# or
+yarn add @o-zakstam/voltagent-convex convex
+```
+
+## Quick Start
+
+### 1. Install the VoltAgent Component
+
+In your `convex/convex.config.ts`, import and install the VoltAgent component:
+
+```typescript
+import { defineApp } from "convex/server";
+import voltagent from "@o-zakstam/voltagent-convex/convex.config";
+
+const app = defineApp();
+app.use(voltagent);
+
+export default app;
+```
+
+### 2. Create the API Wrapper Functions
+
+Create a `convex/voltagent.ts` file that generates the public API functions:
+
+```typescript
+import { components } from "./_generated/api";
+import { defineVoltAgentAPI } from "@o-zakstam/voltagent-convex/api";
+
+export const {
+  createConversation,
+  getConversation,
+  getConversations,
+  getConversationsByUserId,
+  queryConversations,
+  updateConversation,
+  deleteConversation,
+  addMessage,
+  addMessages,
+  getMessages,
+  clearMessages,
+  saveConversationSteps,
+  getConversationSteps,
+  getWorkingMemory,
+  setWorkingMemory,
+  deleteWorkingMemory,
+  getWorkflowState,
+  queryWorkflowRuns,
+  setWorkflowState,
+  updateWorkflowState,
+  getSuspendedWorkflowStates,
+} = defineVoltAgentAPI(components.voltagent);
+```
+
+### 3. Run Convex code generation
+
+After updating your config and creating the wrapper file, run:
+
+```bash
+npx convex dev
+```
+
+This will generate the component types in your `convex/_generated/` directory.
+
+### 4. Use the adapter in your VoltAgent
+
+```typescript
+import { Agent, Memory, VoltAgent } from "@voltagent/core";
+import { ConvexHttpClient } from "convex/browser";
+import { ConvexMemoryAdapter } from "@o-zakstam/voltagent-convex";
+import { api } from "./convex/_generated/api";
+import { openai } from "@ai-sdk/openai";
+
+// Create a Convex client
+const convexClient = new ConvexHttpClient(process.env.CONVEX_URL!);
+
+// Create the memory adapter
+const memory = new Memory({
+  storage: new ConvexMemoryAdapter({
+    client: convexClient,
+    api: api.voltagent,
+    debug: process.env.NODE_ENV === "development",
+  }),
+});
+
+// Create your agent with Convex-backed memory
+const agent = new Agent({
+  name: "Assistant",
+  instructions: "A helpful assistant that remembers conversations.",
+  model: openai("gpt-4o-mini"),
+  memory,
+});
+
+// Run VoltAgent
+new VoltAgent({
+  agents: { agent },
+});
+```
+
+## Configuration Options
+
+```typescript
+interface ConvexMemoryAdapterOptions {
+  /**
+   * The Convex client instance.
+   * Can be ConvexHttpClient or ConvexReactClient.
+   */
+  client: ConvexClient;
+
+  /**
+   * The VoltAgent API from your Convex generated code.
+   * Import from "./convex/_generated/api" and use api.voltagent
+   */
+  api: VoltAgentApi;
+
+  /**
+   * Enable debug logging (default: false)
+   */
+  debug?: boolean;
+
+  /**
+   * Custom logger instance
+   */
+  logger?: Logger;
+}
+```
+
+## Component Architecture
+
+This package uses [Convex Components](https://docs.convex.dev/components) to provide a clean, isolated integration. The component:
+
+- Creates its own isolated set of tables
+- Manages all schema and functions internally
+- Doesn't conflict with your existing Convex tables
+- Updates automatically when you update the package
+
+## Table Structure
+
+The component creates the following tables (isolated in the component namespace):
+
+| Table | Description |
+|-------|-------------|
+| `conversations` | Stores conversation metadata |
+| `messages` | Stores individual messages |
+| `users` | Stores user-level working memory |
+| `workflowStates` | Stores workflow execution state |
+| `conversationSteps` | Stores detailed steps for observability |
+
+## Working Memory
+
+The adapter supports both conversation-scoped and user-scoped working memory:
+
+```typescript
+const memory = new Memory({
+  storage: new ConvexMemoryAdapter({ client, api: api.voltagent }),
+  workingMemory: {
+    enabled: true,
+    scope: "conversation", // or "user"
+  },
+});
+```
+
+## Workflow State
+
+For suspendable workflows, the adapter persists workflow state including:
+
+- Workflow execution status
+- Suspension checkpoints
+- Workflow events for visualization
+- Output and cancellation data
+
+## Using with React
+
+With Convex React, you can use the `ConvexReactClient`:
+
+```typescript
+import { useConvex } from "convex/react";
+import { ConvexMemoryAdapter } from "@o-zakstam/voltagent-convex";
+import { api } from "./convex/_generated/api";
+
+function useMemoryAdapter() {
+  const convex = useConvex();
+  
+  return new ConvexMemoryAdapter({
+    client: convex,
+    api: api.voltagent,
+  });
+}
+```
+
+## Known Limitations
+
+### OperationContext Not Supported
+
+The `OperationContext` parameter is accepted by all methods for interface compatibility but is currently not used. This means the following features from the VoltAgent interface are not implemented:
+
+- **Multi-tenancy isolation**: Context-based tenant separation is not applied
+- **Audit logging**: Operation context is not logged or stored
+- **Access control**: Context-based permissions are not enforced
+
+If you need these features, you can extend `ConvexMemoryAdapter` and override the relevant methods to implement custom context handling:
+
+```typescript
+import { ConvexMemoryAdapter } from "@o-zakstam/voltagent-convex";
+import type { OperationContext } from "@voltagent/core";
+
+class CustomConvexMemoryAdapter extends ConvexMemoryAdapter {
+  async addMessage(
+    message: UIMessage,
+    userId: string,
+    conversationId: string,
+    context?: OperationContext,
+  ): Promise<void> {
+    // Custom context handling
+    if (context) {
+      const tenantId = context.context.get("tenantId");
+      // Apply tenant isolation logic
+    }
+    return super.addMessage(message, userId, conversationId, context);
+  }
+}
+```
+
+## API Reference
+
+### ConvexMemoryAdapter
+
+Implements the `StorageAdapter` interface from `@voltagent/core`:
+
+#### Message Operations
+- `addMessage(message, userId, conversationId)` - Add a single message
+- `addMessages(messages, userId, conversationId)` - Add multiple messages
+- `getMessages(userId, conversationId, options?)` - Get messages with filtering
+- `clearMessages(userId, conversationId?)` - Clear messages
+
+#### Conversation Operations
+- `createConversation(input)` - Create a new conversation
+- `getConversation(id)` - Get a conversation by ID
+- `getConversations(resourceId)` - Get conversations by resource
+- `getConversationsByUserId(userId, options?)` - Get user's conversations
+- `queryConversations(options)` - Query with filters
+- `updateConversation(id, updates)` - Update a conversation
+- `deleteConversation(id)` - Delete a conversation
+
+#### Working Memory Operations
+- `getWorkingMemory(params)` - Get working memory content
+- `setWorkingMemory(params)` - Set working memory content
+- `deleteWorkingMemory(params)` - Delete working memory
+
+#### Workflow State Operations
+- `getWorkflowState(executionId)` - Get workflow state
+- `queryWorkflowRuns(query)` - Query workflow runs
+- `setWorkflowState(executionId, state)` - Set workflow state
+- `updateWorkflowState(executionId, updates)` - Update workflow state
+- `getSuspendedWorkflowStates(workflowId)` - Get suspended workflows
+
+#### Conversation Steps Operations
+- `saveConversationSteps(steps)` - Save conversation steps
+- `getConversationSteps(userId, conversationId, options?)` - Get steps
+
+## License
+
+MIT
+
+## Links
+
+- [VoltAgent Documentation](https://voltagent.dev/docs/)
+- [Convex Documentation](https://docs.convex.dev/)
+- [Convex Components Documentation](https://docs.convex.dev/components)
+- [GitHub Repository](https://github.com/zakstam/voltagent-convex)

package/convex/conversations.ts

@@ -0,0 +1,310 @@
+/**
+ * Conversation-related Convex functions
+ */
+import { mutation, query } from "./_generated/server";
+import { v } from "convex/values";
+import { vMetadata } from "./validators";
+
+/**
+ * Create a new conversation
+ */
+export const create = mutation({
+  args: {
+    id: v.string(),
+    resourceId: v.string(),
+    userId: v.string(),
+    title: v.string(),
+    metadata: vMetadata,
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("conversations")
+      .withIndex("by_visible_id", (q) => q.eq("visibleId", args.id))
+      .first();
+
+    if (existing) {
+      throw new Error("Conversation already exists");
+    }
+
+    const now = new Date().toISOString();
+    const id = await ctx.db.insert("conversations", {
+      visibleId: args.id,
+      resourceId: args.resourceId,
+      userId: args.userId,
+      title: args.title,
+      metadata: args.metadata || {},
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    return {
+      _id: id,
+      id: args.id,
+      resourceId: args.resourceId,
+      userId: args.userId,
+      title: args.title,
+      metadata: args.metadata || {},
+      createdAt: now,
+      updatedAt: now,
+    };
+  },
+});
+
+/**
+ * Get a conversation by visible ID
+ */
+export const get = query({
+  args: { id: v.string() },
+  handler: async (ctx, args) => {
+    const conversation = await ctx.db
+      .query("conversations")
+      .withIndex("by_visible_id", (q) => q.eq("visibleId", args.id))
+      .first();
+
+    if (!conversation) {
+      return null;
+    }
+
+    return {
+      id: conversation.visibleId,
+      resourceId: conversation.resourceId,
+      userId: conversation.userId,
+      title: conversation.title,
+      metadata: conversation.metadata,
+      createdAt: conversation.createdAt,
+      updatedAt: conversation.updatedAt,
+    };
+  },
+});
+
+/**
+ * Get conversations by resource ID
+ */
+export const getByResourceId = query({
+  args: { resourceId: v.string() },
+  handler: async (ctx, args) => {
+    const conversations = await ctx.db
+      .query("conversations")
+      .withIndex("by_resource_id", (q) => q.eq("resourceId", args.resourceId))
+      .collect();
+
+    return conversations.map((c) => ({
+      id: c.visibleId,
+      resourceId: c.resourceId,
+      userId: c.userId,
+      title: c.title,
+      metadata: c.metadata,
+      createdAt: c.createdAt,
+      updatedAt: c.updatedAt,
+    }));
+  },
+});
+
+/**
+ * Get conversations by user ID with pagination and ordering
+ */
+// Map API field names to Convex schema field names
+const orderByFieldMap: Record<string, string> = {
+  created_at: "createdAt",
+  updated_at: "updatedAt",
+  title: "title",
+  // Also support camelCase for flexibility
+  createdAt: "createdAt",
+  updatedAt: "updatedAt",
+};
+
+export const getByUserId = query({
+  args: {
+    userId: v.string(),
+    limit: v.optional(v.number()),
+    offset: v.optional(v.number()),
+    orderBy: v.optional(v.string()),
+    orderDirection: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    let conversations = await ctx.db
+      .query("conversations")
+      .withIndex("by_user_id", (q) => q.eq("userId", args.userId))
+      .collect();
+
+    // Map the orderBy field and default to createdAt DESC per VoltAgent spec
+    const sortField = orderByFieldMap[args.orderBy || ""] || "createdAt";
+    const orderDir = args.orderDirection === "ASC" ? 1 : -1;
+
+    conversations.sort((a, b) => {
+      const aVal = a[sortField as keyof typeof a] as string;
+      const bVal = b[sortField as keyof typeof b] as string;
+      return orderDir * aVal.localeCompare(bVal);
+    });
+
+    const offset = args.offset || 0;
+    const limit = args.limit || 50;
+    conversations = conversations.slice(offset, offset + limit);
+
+    return conversations.map((c) => ({
+      id: c.visibleId,
+      resourceId: c.resourceId,
+      userId: c.userId,
+      title: c.title,
+      metadata: c.metadata,
+      createdAt: c.createdAt,
+      updatedAt: c.updatedAt,
+    }));
+  },
+});
+
+/**
+ * Query conversations with filters
+ * Uses indexed queries to avoid loading all data into memory
+ */
+export const queryConversations = query({
+  args: {
+    userId: v.optional(v.string()),
+    resourceId: v.optional(v.string()),
+    limit: v.optional(v.number()),
+    offset: v.optional(v.number()),
+    orderBy: v.optional(v.string()),
+    orderDirection: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    // Use indexed queries based on available filters to avoid full table scans
+    let conversations;
+
+    if (args.userId) {
+      // Use user_id index - most common query pattern
+      conversations = await ctx.db
+        .query("conversations")
+        .withIndex("by_user_id", (q) => q.eq("userId", args.userId!))
+        .collect();
+
+      // Apply secondary filter if needed
+      if (args.resourceId) {
+        conversations = conversations.filter(
+          (c) => c.resourceId === args.resourceId
+        );
+      }
+    } else if (args.resourceId) {
+      // Use resource_id index
+      conversations = await ctx.db
+        .query("conversations")
+        .withIndex("by_resource_id", (q) => q.eq("resourceId", args.resourceId!))
+        .collect();
+    } else {
+      // No filters - apply a reasonable limit to prevent memory issues
+      // Return most recent conversations by default
+      const maxUnfilteredResults = 1000;
+      conversations = await ctx.db
+        .query("conversations")
+        .order("desc")
+        .take(maxUnfilteredResults);
+    }
+
+    // Map the orderBy field and default to createdAt DESC per VoltAgent spec
+    const sortField = orderByFieldMap[args.orderBy || ""] || "createdAt";
+    const orderDir = args.orderDirection === "ASC" ? 1 : -1;
+
+    conversations.sort((a, b) => {
+      const aVal = a[sortField as keyof typeof a] as string;
+      const bVal = b[sortField as keyof typeof b] as string;
+      return orderDir * aVal.localeCompare(bVal);
+    });
+
+    const offset = args.offset || 0;
+    const limit = args.limit || 50;
+    conversations = conversations.slice(offset, offset + limit);
+
+    return conversations.map((c) => ({
+      id: c.visibleId,
+      resourceId: c.resourceId,
+      userId: c.userId,
+      title: c.title,
+      metadata: c.metadata,
+      createdAt: c.createdAt,
+      updatedAt: c.updatedAt,
+    }));
+  },
+});
+
+/**
+ * Update a conversation
+ */
+export const update = mutation({
+  args: {
+    id: v.string(),
+    title: v.optional(v.string()),
+    resourceId: v.optional(v.string()),
+    metadata: v.optional(vMetadata),
+  },
+  handler: async (ctx, args) => {
+    const conversation = await ctx.db
+      .query("conversations")
+      .withIndex("by_visible_id", (q) => q.eq("visibleId", args.id))
+      .first();
+
+    if (!conversation) {
+      throw new Error("Conversation not found");
+    }
+
+    const updates: Record<string, unknown> = {
+      updatedAt: new Date().toISOString(),
+    };
+
+    if (args.title !== undefined) updates.title = args.title;
+    if (args.resourceId !== undefined) updates.resourceId = args.resourceId;
+    if (args.metadata !== undefined) updates.metadata = args.metadata;
+
+    await ctx.db.patch(conversation._id, updates);
+
+    const updated = await ctx.db.get(conversation._id);
+    return {
+      id: updated!.visibleId,
+      resourceId: updated!.resourceId,
+      userId: updated!.userId,
+      title: updated!.title,
+      metadata: updated!.metadata,
+      createdAt: updated!.createdAt,
+      updatedAt: updated!.updatedAt,
+    };
+  },
+});
+
+/**
+ * Delete a conversation and all associated data
+ */
+export const remove = mutation({
+  args: { id: v.string() },
+  handler: async (ctx, args) => {
+    const conversation = await ctx.db
+      .query("conversations")
+      .withIndex("by_visible_id", (q) => q.eq("visibleId", args.id))
+      .first();
+
+    if (!conversation) {
+      throw new Error("Conversation not found");
+    }
+
+    // Delete associated messages
+    const messages = await ctx.db
+      .query("messages")
+      .withIndex("by_conversation_id", (q) => q.eq("conversationId", args.id))
+      .collect();
+
+    for (const message of messages) {
+      await ctx.db.delete(message._id);
+    }
+
+    // Delete associated steps
+    const steps = await ctx.db
+      .query("conversationSteps")
+      .withIndex("by_conversation_id", (q) => q.eq("conversationId", args.id))
+      .collect();
+
+    for (const step of steps) {
+      await ctx.db.delete(step._id);
+    }
+
+    await ctx.db.delete(conversation._id);
+
+    return { success: true };
+  },
+});

package/convex/convex.config.ts

@@ -0,0 +1,22 @@
+/**
+ * VoltAgent Convex Component Configuration
+ *
+ * This file defines the VoltAgent component for Convex.
+ * When users install this component in their Convex project,
+ * they get isolated tables and functions for VoltAgent memory storage.
+ */
+import { defineComponent } from "convex/server";
+
+/**
+ * VoltAgent component definition.
+ *
+ * This component provides:
+ * - Conversation storage with metadata
+ * - Message persistence with UIMessage format
+ * - Working memory (conversation and user scoped)
+ * - Workflow state management for suspendable workflows
+ * - Conversation steps for observability
+ */
+const component = defineComponent("voltagent");
+
+export default component;