feat(storage): add libsql file-based storage with network volume support (#9)

* fix(docs): correct agent endpoint, model references, add experimental notice

- fix test-endpoint-agent.mjs to use /generate instead of /chat
- update README.md with correct model name (qwen3-32b-awq)
- update .runpod/README.md with experimental notice explaining:
  - cold start time (20-40s) and flash boot coming for cpu
  - load balancer is experimental for mastra api exposure
  - recommend active workers = 1 to avoid cold start
  - in-memory storage is file-based and lost when worker stops

* feat(storage): add libsql file-based storage with network volume support

- add libsql as storage backend when postgresql not configured
- detect /runpod-volume at runtime for persistent storage
- fallback to /tmp for ephemeral storage when no volume attached
- update documentation with three storage modes

Author: TimPietruskyRunPod

.runpod/README.md

@@ -1,32 +1,54 @@
 ![Mastra AI Agent Server](https://mastra.ai/favicon.ico)
 
-Deploy AI agents powered by [Mastra](https://mastra.ai) with OpenAI-compatible endpoints
+Deploy AI agents powered by [Mastra](https://mastra.ai) on Runpod Serverless
 
 ---
 
 [![Runpod](https://api.runpod.io/badge/runpod-workers/worker-mastra)](https://www.runpod.io/console/hub/runpod-workers/worker-mastra)
 
 ---
 
+## Experimental
+
+This worker is **experimental** and designed to explore running AI agents on Runpod Serverless CPU endpoints.
+
+### Current Limitations
+
+**Cold Start Time:** CPU pods currently have a cold start time of 20-40 seconds. We are actively working on bringing **Flash Boot** to CPU pods (currently available for GPU pods) to enable instant startups.
+
+**Load Balancer:** This worker uses the experimental Load Balancer endpoint type to expose Mastra's HTTP API directly, without requiring the Runpod Python SDK.
+
+### Recommended Configuration
+
+To avoid cold start delays, we recommend setting **Active Workers to 1** in your endpoint configuration. This keeps one worker always running and ready to handle requests immediately.
+
+## Storage and Memory
+
+The worker supports three storage modes for agent memory:
+
+**Ephemeral (Default):** Without database credentials and no network volume, the worker uses LibSQL (SQLite) file storage at `/tmp/mastra-storage.db`. This data is **lost when the worker stops**.
+
+**Network Volume (Persistent):** Attach a network volume to the endpoint. The worker automatically detects `/runpod-volume` and stores data at `/runpod-volume/mastra-storage.db`, surviving worker restarts.
+
+**PostgreSQL (Persistent):** Configure a PostgreSQL database with the `pgvector` extension for full-featured persistent agent memory with vector embeddings.
+
 ## Endpoint Configuration
 
 All behaviour is controlled through environment variables:
 
-| Environment Variable | Description                          | Default | Required |
-| -------------------- | ------------------------------------ | ------- | -------- |
-| `RUNPOD_API_KEY`     | Runpod API key for AI model access   |         | Yes      |
-| `DB_HOST`            | PostgreSQL database host             |         | No       |
-| `DB_USERNAME`        | PostgreSQL database username         |         | No       |
-| `DB_NAME`            | PostgreSQL database name             |         | No       |
-| `DB_PASSWORD`        | PostgreSQL database password         |         | No       |
-| `DB_PORT`            | PostgreSQL database port             | 6543    | No       |
-| `PORT`               | Server port                          | 80      | No       |
-| `MASTRA_PORT`        | Internal Mastra server port          | 4111    | No       |
+| Environment Variable | Description                        | Default | Required |
+| -------------------- | ---------------------------------- | ------- | -------- |
+| `RUNPOD_API_KEY`     | Runpod API key for AI model access |         | Yes      |
+| `DB_HOST`            | PostgreSQL database host           |         | No       |
+| `DB_USERNAME`        | PostgreSQL database username       |         | No       |
+| `DB_NAME`            | PostgreSQL database name           |         | No       |
+| `DB_PASSWORD`        | PostgreSQL database password       |         | No       |
+| `DB_PORT`            | PostgreSQL database port           | 6543    | No       |
+| `PORT`               | Server port                        | 80      | No       |
+| `MASTRA_PORT`        | Internal Mastra server port        | 4111    | No       |
 
 ## Database Setup (Optional)
 
-Database is optional. Without database credentials, the worker uses in-memory storage (no persistent memory between requests).
-
 For persistent agent memory, configure a PostgreSQL database with the `pgvector` extension. We recommend **Supabase** for easy setup:
 
 1. Create a new project at [Supabase Dashboard](https://supabase.com/dashboard)
@@ -43,8 +65,9 @@ curl https://YOUR_ENDPOINT_ID.api.runpod.ai/ping
 ```
 
 Response:
+
 ```json
-{"status": "healthy"}
+{ "status": "healthy" }
 ```
 
 ### List Available Agents
@@ -70,7 +93,7 @@ curl -X POST https://YOUR_ENDPOINT_ID.api.runpod.ai/api/tools/get-weather/execut
 ### Chat with Weather Agent
 
 ```bash
-curl -X POST https://YOUR_ENDPOINT_ID.api.runpod.ai/api/agents/weatherAgent/chat \
+curl -X POST https://YOUR_ENDPOINT_ID.api.runpod.ai/api/agents/weatherAgent/generate \
   -H "Content-Type: application/json" \
   -d '{
     "messages": [
@@ -82,20 +105,18 @@ curl -X POST https://YOUR_ENDPOINT_ID.api.runpod.ai/api/agents/weatherAgent/chat
 ## Features
 
 - Mastra AI framework with multi-agent support
-- Runpod AI SDK provider with OpenAI GPT-OSS-120B
-- PostgreSQL storage with PgVector for agent memory
+- Runpod AI SDK provider with Qwen3-32B model
+- PostgreSQL storage with PgVector for agent memory (optional)
 - `/ping` health check for load balancer monitoring
-- OpenAI-compatible chat API
 
 ## Architecture
 
 - **Runtime:** CPU (serverless)
-- **Endpoint Type:** Load Balancer (LB)
+- **Endpoint Type:** Load Balancer (experimental)
 - **Framework:** Mastra + Hono server
-- **Storage:** PostgreSQL with pgvector extension
+- **Storage:** In-memory (default) or PostgreSQL with pgvector
 
 ## Documentation
 
 - [Mastra Documentation](https://mastra.ai/docs)
 - [Runpod Serverless Documentation](https://docs.runpod.io/serverless)
-

README.md

@@ -7,7 +7,7 @@ Mastra production server running on Runpod Serverless CPU with Load Balancer sup
 ## Features
 
 - Mastra Hono server with weather agent and tool (no API key required for weather)
-- Runpod AI SDK provider with OpenAI GPT-OSS-120B support
+- Runpod AI SDK provider with Qwen3-32B model support
 - `/ping` health check endpoint for Runpod serverless load balancer
 - PostgreSQL storage with PgVector for agent memory
 - Observability and telemetry enabled (Mastra Cloud)
@@ -160,7 +160,7 @@ For local development and testing, you can run Mastra directly without building
    - 🔌 **API Endpoints**: http://localhost:4111/api - REST API for agents
    - 📚 **API Documentation**: http://localhost:4111/swagger-ui - Interactive API explorer
 
-**Note:** Make sure the `runpod-mcp` project is built and available at `../runpod-mcp/build/index.js` for the RunPod Infra Management agent to work. If you haven't built it yet:
+**Note:** Make sure the `runpod-mcp` project is built and available at `../runpod-mcp/build/index.js` for the Runpod Infra Management agent to work. If you haven't built it yet:
 
 ```bash
 cd ../runpod-mcp
@@ -315,7 +315,7 @@ Once deployed, access at: `https://YOUR_ENDPOINT_ID.api.runpod.ai/`
 - `GET /api/tools` - List available tools
 - `POST /api/tools/get-weather/execute` - Execute weather tool
 - `GET /api/agents` - List available agents
-- `POST /api/agents/weatherAgent/chat` - Chat with weather agent
+- `POST /api/agents/weatherAgent/generate` - Chat with weather agent
 
 ## Requirements Met
 

docs/context.md

@@ -9,7 +9,7 @@ This document outlines the key technical conventions and architectural decisions
   - Core logic is implemented as Mastra Agents (e.g., `weatherAgent`, `runpodInfraAgent`).
   - External functionalities are integrated as Mastra Tools or via MCP (Model Context Protocol).
   - Multiple agents can coexist in a single Mastra instance.
-- **AI Provider:** RunPod AI SDK Provider (`@runpod/ai-sdk-provider` v0.9.0)
+- **AI Provider:** Runpod AI SDK Provider (`@runpod/ai-sdk-provider` v0.9.0)
   - Uses Qwen3-32B model (`qwen/qwen3-32b-awq`) for agent reasoning.
   - Supports streaming and non-streaming text generation.
 - **Server Framework:** Hono (via Mastra's built-in server)
@@ -18,7 +18,7 @@ This document outlines the key technical conventions and architectural decisions
   - Agent memory: `PgVector` from `@mastra/pg` for embeddings (when DB credentials provided)
   - Falls back to in-memory storage when no database credentials are configured
 - **External Tool Integration:** MCP (Model Context Protocol) via `@mastra/mcp`
-  - MCP servers provide external tools to agents (e.g., RunPod API tools)
+  - MCP servers provide external tools to agents (e.g., Runpod API tools)
   - MCP configuration in `src/mastra/mcp-config.ts` manages server connections
 - **Project Structure:**
   - `src/mastra/agents/` - Agent definitions
@@ -100,7 +100,7 @@ When all DB credentials are provided, PostgreSQL with PgVector is used. Otherwis
 - **Memory Initialization:** Agents import `createAgentMemory()` from `utils/db.ts` - they do not handle database logic themselves.
 - **Tool Integration:** Agents can use:
   - Mastra Tools: Direct tool implementations (e.g., `weatherTool`)
-  - MCP Tools: External tools provided via MCP servers (e.g., RunPod API tools)
+  - MCP Tools: External tools provided via MCP servers (e.g., Runpod API tools)
 - **MCP Integration:** MCP servers are configured in `src/mastra/mcp-config.ts`. Agents access MCP tools by importing the MCP client and filtering available tools as needed.
 
 ## Local Development
@@ -117,7 +117,7 @@ When all DB credentials are provided, PostgreSQL with PgVector is used. Otherwis
 - **Docker Hub:** Images pushed to `runpod/worker-mastra:<version>`
 - **Runpod Git Pipeline:** Configure to build and deploy on push to `main` branch
 
-## RunPod Hub Integration
+## Runpod Hub Integration
 
 - **Hub Metadata:** `.runpod/` folder contains Hub publishing configuration
   - `hub.json`: Worker metadata, environment variables, and deployment config

package-lock.json

@@ -13,7 +13,7 @@
   "license": "ISC",
   "dependencies": {
     "@mastra/core": "^0.23.3",
-    "@mastra/libsql": "^0.16.1",
+    "@mastra/libsql": "^0.16.4",
     "@mastra/loggers": "^0.10.18",
     "@mastra/mcp": "^0.14.1",
     "@mastra/memory": "^0.15.10",

package.json

@@ -27,7 +27,7 @@ async function testAgent() {
 
   try {
     const response = await fetch(
-      `${ENDPOINT_URL}/api/agents/weatherAgent/chat`,
+      `${ENDPOINT_URL}/api/agents/weatherAgent/generate`,
       {
         method: "POST",
         headers: {

scripts/test-endpoint-agent.mjs

@@ -1,4 +1,6 @@
+import { existsSync } from "fs";
 import { PostgresStore, PgVector } from "@mastra/pg";
+import { LibSQLStore } from "@mastra/libsql";
 import { Memory } from "@mastra/memory";
 
 // Check if all required DB credentials are provided
@@ -12,26 +14,47 @@ export const hasDbCredentials =
 export const getConnectionString = () =>
   `postgresql://${process.env.DB_USERNAME}:${process.env.DB_PASSWORD}@${process.env.DB_HOST}:${process.env.DB_PORT || "6543"}/${process.env.DB_NAME}`;
 
+// Determine storage path: prefer /runpod-volume (network volume), fallback to /tmp
+const getStoragePath = () => {
+  if (process.env.STORAGE_PATH) {
+    return process.env.STORAGE_PATH;
+  }
+  // Use network volume if available, otherwise ephemeral /tmp
+  if (existsSync("/runpod-volume")) {
+    return "/runpod-volume/mastra-storage.db";
+  }
+  return "/tmp/mastra-storage.db";
+};
+
 // Global storage for Mastra instance
 export const createStorage = () => {
-  if (!hasDbCredentials) {
-    console.log("[Mastra] No database credentials provided, using in-memory storage");
-    return undefined;
+  if (hasDbCredentials) {
+    console.log("[Mastra] Using PostgreSQL storage");
+    return new PostgresStore({
+      host: process.env.DB_HOST!,
+      port: parseInt(process.env.DB_PORT || "6543"),
+      user: process.env.DB_USERNAME!,
+      database: process.env.DB_NAME!,
+      password: process.env.DB_PASSWORD!,
+    });
   }
 
-  return new PostgresStore({
-    host: process.env.DB_HOST!,
-    port: parseInt(process.env.DB_PORT || "6543"),
-    user: process.env.DB_USERNAME!,
-    database: process.env.DB_NAME!,
-    password: process.env.DB_PASSWORD!,
+  const storagePath = getStoragePath();
+  const isPersistent = storagePath.startsWith("/runpod-volume");
+  console.log(
+    `[Mastra] Using file-based storage at ${storagePath} (${isPersistent ? "persistent" : "ephemeral"})`
+  );
+  return new LibSQLStore({
+    url: `file:${storagePath}`,
   });
 };
 
 // Agent memory with PgVector for embeddings
 export const createAgentMemory = (agentName: string) => {
   if (!hasDbCredentials) {
-    console.log(`[${agentName}] No database credentials provided, running without persistent memory`);
+    console.log(
+      `[${agentName}] No database credentials provided, running without persistent memory`
+    );
     return undefined;
   }
 
@@ -48,4 +71,3 @@ export const createAgentMemory = (agentName: string) => {
     },
   });
 };
-