@mastra/pg 1.0.0-beta.9 → 1.0.0

package/dist/docs/README.md

@@ -0,0 +1,36 @@
+# @mastra/pg 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
+├── memory/ (4 files)
+├── processors/ (3 files)
+├── rag/ (4 files)
+├── storage/ (3 files)
+├── tools/ (1 files)
+├── vectors/ (1 files)
+```
+
+## Version
+
+Package: @mastra/pg
+Version: 1.0.0

package/dist/docs/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: mastra-pg-docs
+description: Documentation for @mastra/pg. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/pg Documentation
+
+> **Version**: 1.0.0
+> **Package**: @mastra/pg
+
+## 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
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Memory](memory/) - 4 file(s)
+- [Processors](processors/) - 3 file(s)
+- [Rag](rag/) - 4 file(s)
+- [Storage](storage/) - 3 file(s)
+- [Tools](tools/) - 1 file(s)
+- [Vectors](vectors/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0.0",
+  "package": "@mastra/pg",
+  "exports": {},
+  "modules": {}
+}

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

@@ -0,0 +1,233 @@
+> Configure storage for Mastra
+
+# Storage
+
+For Mastra to remember previous interactions, you must configure a storage adapter. Mastra is designed to work with your preferred database provider - choose from the [supported providers](#supported-providers) and pass it to your Mastra instance.
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: "file:./mastra.db",
+  }),
+});
+```
+On first interaction, Mastra automatically creates the necessary tables following the [core schema](https://mastra.ai/reference/v1/storage/overview#core-schema). This includes tables for messages, threads, resources, workflows, traces, and evaluation datasets.
+
+## Supported providers
+
+Each provider page includes installation instructions, configuration parameters, and usage examples:
+
+- [libSQL Storage](https://mastra.ai/reference/v1/storage/libsql)
+- [PostgreSQL Storage](https://mastra.ai/reference/v1/storage/postgresql)
+- [MongoDB Storage](https://mastra.ai/reference/v1/storage/mongodb)
+- [Upstash Storage](https://mastra.ai/reference/v1/storage/upstash)
+- [Cloudflare D1](https://mastra.ai/reference/v1/storage/cloudflare-d1)
+- [Cloudflare Durable Objects](https://mastra.ai/reference/v1/storage/cloudflare)
+- [Convex](https://mastra.ai/reference/v1/storage/convex)
+- [DynamoDB](https://mastra.ai/reference/v1/storage/dynamodb)
+- [LanceDB](https://mastra.ai/reference/v1/storage/lance)
+- [Microsoft SQL Server](https://mastra.ai/reference/v1/storage/mssql)
+
+> **Note:**
+libSQL is the easiest way to get started because it doesn’t require running a separate database server
+
+## Configuration scope
+
+You can configure storage at two different scopes:
+
+### Instance-level storage
+
+Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same memory provider:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { PostgresStore } from "@mastra/pg";
+
+export const mastra = new Mastra({
+  storage: new PostgresStore({
+    id: 'mastra-storage',
+    connectionString: process.env.DATABASE_URL,
+  }),
+});
+
+// All agents automatically use this storage
+const agent1 = new Agent({ id: "agent-1", memory: new Memory() });
+const agent2 = new Agent({ id: "agent-2", memory: new Memory() });
+```
+
+This is useful when all primitives share the same storage backend and have similar performance, scaling, and operational requirements.
+
+#### Composite storage
+
+Add storage to your Mastra instance using `MastraCompositeStore` and configure individual storage domains to use different storage providers.
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryLibSQL } from "@mastra/libsql";
+import { WorkflowsPG } from "@mastra/pg";
+import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: "composite",
+    domains: {
+      memory: new MemoryLibSQL({ url: "file:./memory.db" }),
+      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      observability: new ObservabilityStorageClickhouse({
+        url: process.env.CLICKHOUSE_URL,
+        username: process.env.CLICKHOUSE_USERNAME,
+        password: process.env.CLICKHOUSE_PASSWORD,
+      }),
+    },
+  }),
+});
+```
+
+This is useful when different types of data have different performance or operational requirements, such as low-latency storage for memory, durable storage for workflows, and high-throughput storage for observability.
+
+> **Note:**
+See [Storage Domains](https://mastra.ai/reference/v1/storage/composite#storage-domains) for more information.
+
+### Agent-level storage
+
+Agent-level storage overrides storage configured at the instance-level. Add storage to a specific agent when you need data boundaries or compliance requirements:
+
+```typescript title="src/mastra/agents/memory-agent.ts"
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { PostgresStore } from "@mastra/pg";
+
+export const agent = new Agent({
+  id: "agent",
+  memory: new Memory({
+    storage: new PostgresStore({
+      id: 'agent-storage',
+      connectionString: process.env.AGENT_DATABASE_URL,
+    }),
+  }),
+});
+```
+
+This is useful when different agents need to store data in separate databases for security, compliance, or organizational reasons.
+
+> **Mastra Cloud Store limitation**
+Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/v1/mastra-cloud/deployment#using-mastra-cloud-store). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+
+## Threads and resources
+
+Mastra organizes memory into threads using two identifiers:
+
+- **Thread**: A conversation session containing a sequence of messages (e.g., `convo_123`)
+- **Resource**: An identifier for the entity the thread belongs to, typically a user (e.g., `user_123`)
+
+Both identifiers are required for agents to store and recall information:
+
+```typescript
+const stream = await agent.stream("message for agent", {
+  memory: {
+    thread: "convo_123",
+    resource: "user_123",
+  },
+});
+```
+
+> **Note:**
+[Studio](https://mastra.ai/docs/v1/getting-started/studio) automatically generates a thread and resource ID for you. Remember to  to pass these explicitly when calling `stream` or `generate` yourself.
+
+### Thread and resource relationship
+
+Each thread has an owner (its `resourceId`) that is set when the thread is created and cannot be changed. When you query a thread, you must use the correct owner's resource ID. Attempting to query a thread with a different resource ID will result in an error:
+
+```text
+Thread with id <thread_id> is for resource with id <resource_a>
+but resource <resource_b> was queried
+```
+
+Note that while each thread has one owner, messages within that thread can have different `resourceId` values. This is used for message attribution and filtering (e.g., distinguishing between different agents in a multi-agent system, or filtering messages for analytics).
+
+**Security:** Memory is a storage layer, not an authorization layer. Your application must implement access control before calling memory APIs. The `resourceId` parameter controls both validation and filtering - provide it to validate ownership and filter messages, or omit it for server-side access without validation.
+
+To avoid accidentally reusing thread IDs across different owners, use UUIDs: `crypto.randomUUID()`
+
+### Thread title generation
+
+Mastra can automatically generate descriptive thread titles based on the user's first message.
+
+Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
+
+```typescript
+export const testAgent = new Agent({
+  id: "test-agent",
+  memory: new Memory({
+    options: {
+      generateTitle: true,
+    },
+  }),
+});
+```
+
+Title generation runs asynchronously after the agent responds and does not affect response time.
+
+To optimize cost or behavior, provide a smaller `model` and custom `instructions`:
+
+```typescript
+export const testAgent = new Agent({
+  id: "test-agent",
+  memory: new Memory({
+    options: {
+      generateTitle: {
+        model: "openai/gpt-4o-mini",
+        instructions: "Generate a concise title based on the user's first message",
+      },
+    },
+  }),
+});
+```
+
+## Semantic recall
+
+Semantic recall uses vector embeddings to retrieve relevant past messages based on meaning rather than recency. This requires a vector database instance, which can be configured at the instance or agent level.
+
+The vector database doesn't have to be the same as your storage provider. For example, you might use PostgreSQL for storage and Pinecone for vectors:
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { PostgresStore } from "@mastra/pg";
+import { PineconeVector } from "@mastra/pinecone";
+
+// Instance-level vector configuration
+export const mastra = new Mastra({
+  storage: new PostgresStore({
+    id: 'mastra-storage',
+    connectionString: process.env.DATABASE_URL,
+  }),
+});
+
+// Agent-level vector configuration
+export const agent = new Agent({
+  id: "agent",
+  memory: new Memory({
+    vector: new PineconeVector({
+      id: 'agent-vector',
+      apiKey: process.env.PINECONE_API_KEY,
+    }),
+    options: {
+      semanticRecall: {
+        topK: 5,
+        messageRange: 2,
+      },
+    },
+  }),
+});
+```
+
+We support all popular vector providers including [Pinecone](https://mastra.ai/reference/v1/vectors/pinecone), [Chroma](https://mastra.ai/reference/v1/vectors/chroma), [Qdrant](https://mastra.ai/reference/v1/vectors/qdrant), and many more.
+
+For more information on configuring semantic recall, see the [Semantic Recall](./semantic-recall) documentation.

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

@@ -0,0 +1,390 @@
+> Learn how to configure working memory in Mastra to store persistent user data, preferences.
+
+# Working Memory
+
+While [message history](https://mastra.ai/docs/v1/memory/message-history) and [semantic recall](./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 {11-15}
+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 id="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 {5-28}
+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 title="src/app/medical-consultation.ts"
+// 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 title="src/app/medical-consultation.ts"
+// 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 title="src/app/medical-consultation.ts"
+await memory.updateWorkingMemory({
+  threadId: "thread-123",
+  resourceId: "user-456", // Required for resource-scoped memory
+  workingMemory: "Updated memory content...",
+});
+```
+
+## 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