@mastra/libsql 1.6.0 → 1.6.1-alpha.0

package/dist/docs/references/docs-memory-working-memory.md

@@ -1,400 +0,0 @@
-# Working Memory
-
-While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
-
-Think of it as the agent's active thoughts or scratchpad – the key information they keep available about the user or task. It's similar to how a person would naturally remember someone's name, preferences, or important details during a conversation.
-
-This is useful for maintaining ongoing state that's always relevant and should always be available to the agent.
-
-Working memory can persist at two different scopes:
-
-- **Resource-scoped** (default): Memory persists across all conversation threads for the same user
-- **Thread-scoped**: Memory is isolated per conversation thread
-
-**Important:** Switching between scopes means the agent won't see memory from the other scope - thread-scoped memory is completely separate from resource-scoped memory.
-
-## Quick Start
-
-Here's a minimal example of setting up an agent with working memory:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-
-// Create agent with working memory enabled
-const agent = new Agent({
-  id: "personal-assistant",
-  name: "PersonalAssistant",
-  instructions: "You are a helpful personal assistant.",
-  model: "openai/gpt-5.1",
-  memory: new Memory({
-    options: {
-      workingMemory: {
-        enabled: true,
-      },
-    },
-  }),
-});
-```
-
-## How it Works
-
-Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
-
-[YouTube video player](https://www.youtube-nocookie.com/embed/UMy_JHLf1n8)
-
-## Memory Persistence Scopes
-
-Working memory can operate in two different scopes, allowing you to choose how memory persists across conversations:
-
-### Resource-Scoped Memory (Default)
-
-By default, working memory persists across all conversation threads for the same user (resourceId), enabling persistent user memory:
-
-```typescript
-const memory = new Memory({
-  storage,
-  options: {
-    workingMemory: {
-      enabled: true,
-      scope: "resource", // Memory persists across all user threads
-      template: `# User Profile
-- **Name**:
-- **Location**:
-- **Interests**:
-- **Preferences**:
-- **Long-term Goals**:
-`,
-    },
-  },
-});
-```
-
-**Use cases:**
-
-- Personal assistants that remember user preferences
-- Customer service bots that maintain customer context
-- Educational applications that track student progress
-
-### Usage with Agents
-
-When using resource-scoped memory, make sure to pass the `resource` parameter in the memory options:
-
-```typescript
-// Resource-scoped memory requires resource
-const response = await agent.generate("Hello!", {
-  memory: {
-    thread: "conversation-123",
-    resource: "user-alice-456", // Same user across different threads
-  },
-});
-```
-
-### Thread-Scoped Memory
-
-Thread-scoped memory isolates working memory to individual conversation threads. Each thread maintains its own isolated memory:
-
-```typescript
-const memory = new Memory({
-  storage,
-  options: {
-    workingMemory: {
-      enabled: true,
-      scope: "thread", // Memory is isolated per thread
-      template: `# User Profile
-- **Name**:
-- **Interests**:
-- **Current Goal**:
-`,
-    },
-  },
-});
-```
-
-**Use cases:**
-
-- Different conversations about separate topics
-- Temporary or session-specific information
-- Workflows where each thread needs working memory but threads are ephemeral and not related to each other
-
-## Storage Adapter Support
-
-Resource-scoped working memory requires specific storage adapters that support the `mastra_resources` table:
-
-### Supported Storage Adapters
-
-- **libSQL** (`@mastra/libsql`)
-- **PostgreSQL** (`@mastra/pg`)
-- **Upstash** (`@mastra/upstash`)
-- **MongoDB** (`@mastra/mongodb`)
-
-## Custom Templates
-
-Templates guide the agent on what information to track and update in working memory. While a default template is used if none is provided, you'll typically want to define a custom template tailored to your agent's specific use case to ensure it remembers the most relevant information.
-
-Here's an example of a custom template. In this example the agent will store the users name, location, timezone, etc as soon as the user sends a message containing any of the info:
-
-```typescript
-const memory = new Memory({
-  options: {
-    workingMemory: {
-      enabled: true,
-      template: `
-# User Profile
-
-## Personal Info
-
-- Name:
-- Location:
-- Timezone:
-
-## Preferences
-
-- Communication Style: [e.g., Formal, Casual]
-- Project Goal:
-- Key Deadlines:
-  - [Deadline 1]: [Date]
-  - [Deadline 2]: [Date]
-
-## Session State
-
-- Last Task Discussed:
-- Open Questions:
-  - [Question 1]
-  - [Question 2]
-`,
-    },
-  },
-});
-```
-
-## Designing Effective Templates
-
-A well-structured template keeps the information easy for the agent to parse and update. Treat the template as a short form that you want the assistant to keep up to date.
-
-- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
-- **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy updates. Stick to Title Case or lower case for headings and bullet labels.
-- **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM fill in the correct spots.
-- **Abbreviate very long values.** If you only need a short form, include guidance like `- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
-- **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of the template directly in the agent's `instructions` field.
-
-### Alternative Template Styles
-
-Use a shorter single block if you only need a few items:
-
-```typescript
-const basicMemory = new Memory({
-  options: {
-    workingMemory: {
-      enabled: true,
-      template: `User Facts:\n- Name:\n- Favorite Color:\n- Current Topic:`,
-    },
-  },
-});
-```
-
-You can also store the key facts in a short paragraph format if you prefer a more narrative style:
-
-```typescript
-const paragraphMemory = new Memory({
-  options: {
-    workingMemory: {
-      enabled: true,
-      template: `Important Details:\n\nKeep a short paragraph capturing the user's important facts (name, main goal, current task).`,
-    },
-  },
-});
-```
-
-## Structured Working Memory
-
-Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Zod](https://zod.dev/) schema. When using a schema, the agent will see and update working memory as a JSON object matching your schema.
-
-**Important:** You must specify either `template` or `schema`, but not both.
-
-### Example: Schema-Based Working Memory
-
-```typescript
-import { z } from "zod";
-import { Memory } from "@mastra/memory";
-
-const userProfileSchema = z.object({
-  name: z.string().optional(),
-  location: z.string().optional(),
-  timezone: z.string().optional(),
-  preferences: z
-    .object({
-      communicationStyle: z.string().optional(),
-      projectGoal: z.string().optional(),
-      deadlines: z.array(z.string()).optional(),
-    })
-    .optional(),
-});
-
-const memory = new Memory({
-  options: {
-    workingMemory: {
-      enabled: true,
-      schema: userProfileSchema,
-      // template: ... (do not set)
-    },
-  },
-});
-```
-
-When a schema is provided, the agent receives the working memory as a JSON object. For example:
-
-```json
-{
-  "name": "Sam",
-  "location": "Berlin",
-  "timezone": "CET",
-  "preferences": {
-    "communicationStyle": "Formal",
-    "projectGoal": "Launch MVP",
-    "deadlines": ["2025-07-01"]
-  }
-}
-```
-
-### Merge Semantics for Schema-Based Memory
-
-Schema-based working memory uses **merge semantics**, meaning the agent only needs to include fields it wants to add or update. Existing fields are preserved automatically.
-
-- **Object fields are deep merged:** Only provided fields are updated; others remain unchanged
-- **Set a field to `null` to delete it:** This explicitly removes the field from memory
-- **Arrays are replaced entirely:** When an array field is provided, it replaces the existing array (arrays are not merged element-by-element)
-
-## Choosing Between Template and Schema
-
-- Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics** — the agent must provide the complete memory content on each update.
-- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON. Schemas use **merge semantics** — the agent only provides fields to update, and existing fields are preserved.
-- Only one mode can be active at a time: setting both `template` and `schema` is not supported.
-
-## Example: Multi-step Retention
-
-Below is a simplified view of how the `User Profile` template updates across a short user conversation:
-
-```nohighlight
-# User Profile
-
-## Personal Info
-
-- Name:
-- Location:
-- Timezone:
-
---- After user says "My name is **Sam** and I'm from **Berlin**" ---
-
-# User Profile
-- Name: Sam
-- Location: Berlin
-- Timezone:
-
---- After user adds "By the way I'm normally in **CET**" ---
-
-# User Profile
-- Name: Sam
-- Location: Berlin
-- Timezone: CET
-```
-
-The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information again because it has been stored in working memory.
-
-If your agent is not properly updating working memory when you expect it to, you can add system instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
-
-## Setting Initial Working Memory
-
-While agents typically update working memory through the `updateWorkingMemory` tool, you can also set initial working memory programmatically when creating or updating threads. This is useful for injecting user data (like their name, preferences, or other info) that you want available to the agent without passing it in every request.
-
-### Setting Working Memory via Thread Metadata
-
-When creating a thread, you can provide initial working memory through the metadata's `workingMemory` key:
-
-```typescript
-// Create a thread with initial working memory
-const thread = await memory.createThread({
-  threadId: "thread-123",
-  resourceId: "user-456",
-  title: "Medical Consultation",
-  metadata: {
-    workingMemory: `# Patient Profile
-- Name: John Doe
-- Blood Type: O+
-- Allergies: Penicillin
-- Current Medications: None
-- Medical History: Hypertension (controlled)
-`,
-  },
-});
-
-// The agent will now have access to this information in all messages
-await agent.generate("What's my blood type?", {
-  memory: {
-    thread: thread.id,
-    resource: "user-456",
-  },
-});
-// Response: "Your blood type is O+."
-```
-
-### Updating Working Memory Programmatically
-
-You can also update an existing thread's working memory:
-
-```typescript
-// Update thread metadata to add/modify working memory
-await memory.updateThread({
-  id: "thread-123",
-  title: thread.title,
-  metadata: {
-    ...thread.metadata,
-    workingMemory: `# Patient Profile
-- Name: John Doe
-- Blood Type: O+
-- Allergies: Penicillin, Ibuprofen  // Updated
-- Current Medications: Lisinopril 10mg daily  // Added
-- Medical History: Hypertension (controlled)
-`,
-  },
-});
-```
-
-### Direct Memory Update
-
-Alternatively, use the `updateWorkingMemory` method directly:
-
-```typescript
-await memory.updateWorkingMemory({
-  threadId: "thread-123",
-  resourceId: "user-456", // Required for resource-scoped memory
-  workingMemory: "Updated memory content...",
-});
-```
-
-## Read-Only Working Memory
-
-In some scenarios, you may want an agent to have access to working memory data without the ability to modify it. This is useful for:
-
-- **Routing agents** that need context but shouldn't update user profiles
-- **Sub agents** in a multi-agent system that should reference but not own the memory
-
-To enable read-only mode, set `readOnly: true` in the memory options:
-
-```typescript
-const response = await agent.generate("What do you know about me?", {
-  memory: {
-    thread: "conversation-123",
-    resource: "user-alice-456",
-    options: {
-      readOnly: true, // Working memory is provided but cannot be updated
-    },
-  },
-});
-```
-
-## Examples
-
-- [Working memory with template](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-template)
-- [Working memory with schema](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-schema)
-- [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence

package/dist/docs/references/docs-observability-overview.md

@@ -1,70 +0,0 @@
-# Observability Overview
-
-Mastra provides observability features for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with tools that understand AI-specific patterns.
-
-## Key Features
-
-### Tracing
-
-Specialized tracing for AI operations that captures:
-
-- **Model interactions**: Token usage, latency, prompts, and completions
-- **Agent execution**: Decision paths, tool calls, and memory operations
-- **Workflow steps**: Branching logic, parallel execution, and step outputs
-- **Automatic instrumentation**: Tracing with decorators
-
-## Storage Requirements
-
-The `DefaultExporter` persists traces to your configured storage backend. Not all storage providers support observability—for the full list, see [Storage Provider Support](https://mastra.ai/docs/observability/tracing/exporters/default).
-
-For production environments with high traffic, we recommend using **ClickHouse** for the observability domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
-
-## Quick Start
-
-Configure Observability in your Mastra instance:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { PinoLogger } from "@mastra/loggers";
-import { LibSQLStore } from "@mastra/libsql";
-import {
-  Observability,
-  DefaultExporter,
-  CloudExporter,
-  SensitiveDataFilter,
-} from "@mastra/observability";
-
-export const mastra = new Mastra({
-  logger: new PinoLogger(),
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: "file:./mastra.db", // Storage is required for tracing
-  }),
-  observability: new Observability({
-    configs: {
-      default: {
-        serviceName: "mastra",
-        exporters: [
-          new DefaultExporter(), // Persists traces to storage for Mastra Studio
-          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
-        ],
-        spanOutputProcessors: [
-          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
-        ],
-      },
-    },
-  }),
-});
-```
-
-> **Serverless environments:** The `file:./mastra.db` storage URL uses the local filesystem, which doesn't work in serverless environments like Vercel, AWS Lambda, or Cloudflare Workers. For serverless deployments, use external storage. See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel) for a complete example.
-
-With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
-
-We also support various external tracing providers like MLflow, Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](https://mastra.ai/docs/observability/tracing/overview) documentation.
-
-## What's Next?
-
-- **[Set up Tracing](https://mastra.ai/docs/observability/tracing/overview)**: Configure tracing for your application
-- **[Configure Logging](https://mastra.ai/docs/observability/logging)**: Add structured logging
-- **[API Reference](https://mastra.ai/reference/observability/tracing/instances)**: Detailed configuration options

package/dist/docs/references/docs-observability-tracing-exporters-default.md

@@ -1,211 +0,0 @@
-# Default Exporter
-
-The `DefaultExporter` persists traces to your configured storage backend, making them accessible through Studio. It's automatically enabled when using the default observability configuration and requires no external services.
-
-> **Production Observability:** Observability data can quickly overwhelm general-purpose databases in production. For high-traffic applications, we recommend using **ClickHouse** for the observability storage domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](#production-recommendations) for details.
-
-## Configuration
-
-### Prerequisites
-
-1. **Storage Backend**: Configure a storage provider (libSQL, PostgreSQL, etc.)
-2. **Studio**: Install for viewing traces locally
-
-### Basic Setup
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Observability, DefaultExporter } from "@mastra/observability";
-import { LibSQLStore } from "@mastra/libsql";
-
-export const mastra = new Mastra({
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: "file:./mastra.db", // Required for trace persistence
-  }),
-  observability: new Observability({
-    configs: {
-      local: {
-        serviceName: "my-service",
-        exporters: [new DefaultExporter()],
-      },
-    },
-  }),
-});
-```
-
-### Recommended Configuration
-
-Include DefaultExporter in your observability configuration:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import {
-  Observability,
-  DefaultExporter,
-  CloudExporter,
-  SensitiveDataFilter,
-} from "@mastra/observability";
-import { LibSQLStore } from "@mastra/libsql";
-
-export const mastra = new Mastra({
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: "file:./mastra.db",
-  }),
-  observability: new Observability({
-    configs: {
-      default: {
-        serviceName: "mastra",
-        exporters: [
-          new DefaultExporter(), // Persists traces to storage for Mastra Studio
-          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
-        ],
-        spanOutputProcessors: [
-          new SensitiveDataFilter(),
-        ],
-      },
-    },
-  }),
-});
-```
-
-## Viewing Traces
-
-### Studio
-
-Access your traces through Studio:
-
-1. Start Studio
-2. Navigate to Observability
-3. Filter and search your local traces
-4. Inspect detailed span information
-
-## Tracing Strategies
-
-DefaultExporter automatically selects the optimal tracing strategy based on your storage provider. You can also override this selection if needed.
-
-### Available Strategies
-
-| Strategy               | Description                                               | Use Case                            |
-| ---------------------- | --------------------------------------------------------- | ----------------------------------- |
-| **realtime**           | Process each event immediately                            | Development, debugging, low traffic |
-| **batch-with-updates** | Buffer events and batch write with full lifecycle support | Low volume Production               |
-| **insert-only**        | Only process completed spans, ignore updates              | High volume Production              |
-
-### Strategy Configuration
-
-```typescript
-new DefaultExporter({
-  strategy: "auto", // Default - let storage provider decide
-  // or explicitly set:
-  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'
-
-  // Batching configuration (applies to both batch-with-updates and insert-only)
-  maxBatchSize: 1000, // Max spans per batch
-  maxBatchWaitMs: 5000, // Max wait before flushing
-  maxBufferSize: 10000, // Max spans to buffer
-});
-```
-
-## Storage Provider Support
-
-Different storage providers support different tracing strategies. Some providers support observability for production workloads, while others are intended primarily for local development.
-
-If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects the optimal strategy for the storage provider. If you set the strategy to a mode that the storage provider doesn't support, you will get an error message.
-
-### Providers with Observability Support
-
-| Storage Provider                                                 | Preferred Strategy | Supported Strategies            | Recommended Use                       |
-| ---------------------------------------------------------------- | ------------------ | ------------------------------- | ------------------------------------- |
-| **ClickHouse** (`@mastra/clickhouse`)                            | insert-only        | insert-only                     | Production (high-volume)              |
-| **[PostgreSQL](https://mastra.ai/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
-| **[MSSQL](https://mastra.ai/reference/storage/mssql)**           | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
-| **[MongoDB](https://mastra.ai/reference/storage/mongodb)**       | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
-| **[libSQL](https://mastra.ai/reference/storage/libsql)**         | batch-with-updates | batch-with-updates, insert-only | Default storage, good for development |
-
-### Providers without Observability Support
-
-The following storage providers **do not support** the observability domain. If you're using one of these providers and need observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider:
-
-- [Convex](https://mastra.ai/reference/storage/convex)
-- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
-- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
-- [Cloudflare Durable Objects](https://mastra.ai/reference/storage/cloudflare)
-- [Upstash](https://mastra.ai/reference/storage/upstash)
-- [LanceDB](https://mastra.ai/reference/storage/lance)
-
-### Strategy Benefits
-
-- **realtime**: Immediate visibility, best for debugging
-- **batch-with-updates**: 10-100x throughput improvement, full span lifecycle
-- **insert-only**: Additional 70% reduction in database operations, perfect for analytics
-
-## Production Recommendations
-
-Observability data grows quickly in production environments. A single agent interaction can generate hundreds of spans, and high-traffic applications can produce thousands of traces per day. Most general-purpose databases aren't optimized for this write-heavy, append-only workload.
-
-### Recommended: ClickHouse for High-Volume Production
-
-[ClickHouse](https://mastra.ai/reference/storage/composite) is a columnar database designed for high-volume analytics workloads. It's the recommended choice for production observability because:
-
-- **Optimized for writes**: Handles millions of inserts per second
-- **Efficient compression**: Reduces storage costs for trace data
-- **Fast queries**: Columnar storage enables quick trace lookups and aggregations
-- **Time-series native**: Built-in support for time-based data retention and partitioning
-
-### Using Composite Storage
-
-If you're using a provider without observability support (like Convex or DynamoDB) or want to optimize performance, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to ClickHouse while keeping other data in your primary database.
-
-## Batching Behavior
-
-### Flush Triggers
-
-For both batch strategies (`batch-with-updates` and `insert-only`), traces are flushed to storage when any of these conditions are met:
-
-1. **Size trigger**: Buffer reaches `maxBatchSize` spans
-2. **Time trigger**: `maxBatchWaitMs` elapsed since first event
-3. **Emergency flush**: Buffer approaches `maxBufferSize` limit
-4. **Shutdown**: Force flush all pending events
-
-### Error Handling
-
-The DefaultExporter includes robust error handling for production use:
-
-- **Retry Logic**: Exponential backoff (500ms, 1s, 2s, 4s)
-- **Transient Failures**: Automatic retry with backoff
-- **Persistent Failures**: Drop batch after 4 failed attempts
-- **Buffer Overflow**: Prevent memory issues during storage outages
-
-### Configuration Examples
-
-```typescript
-// Zero config - recommended for most users
-new DefaultExporter();
-
-// Development override
-new DefaultExporter({
-  strategy: "realtime", // Immediate visibility for debugging
-});
-
-// High-throughput production
-new DefaultExporter({
-  maxBatchSize: 2000, // Larger batches
-  maxBatchWaitMs: 10000, // Wait longer to fill batches
-  maxBufferSize: 50000, // Handle longer outages
-});
-
-// Low-latency production
-new DefaultExporter({
-  maxBatchSize: 100, // Smaller batches
-  maxBatchWaitMs: 1000, // Flush quickly
-});
-```
-
-## Related
-
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [CloudExporter](https://mastra.ai/docs/observability/tracing/exporters/cloud)
-- [Composite Storage](https://mastra.ai/reference/storage/composite) - Combine multiple storage providers
-- [Storage Configuration](https://mastra.ai/docs/memory/storage)