@mastra/pg 1.0.0 → 1.1.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # @mastra/pg
 
+## 1.1.0-alpha.0
+
+### Minor Changes
+
+- Added dynamic agent management with CRUD operations and version tracking ([#12038](https://github.com/mastra-ai/mastra/pull/12038))
+
+  **New Features:**
+  - Create, edit, and delete agents directly from the Mastra Studio UI
+  - Full version history for agents with compare and restore capabilities
+  - Visual diff viewer to compare agent configurations across versions
+  - Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
+  - AI-powered instruction enhancement
+
+  **Storage:**
+  - New storage interfaces for stored agents and agent versions
+  - PostgreSQL, LibSQL, and MongoDB implementations included
+  - In-memory storage for development and testing
+
+  **API:**
+  - RESTful endpoints for agent CRUD operations
+  - Version management endpoints (create, list, activate, restore, delete, compare)
+  - Automatic versioning on agent updates when enabled
+
+  **Client SDK:**
+  - JavaScript client with full support for stored agents and versions
+  - Type-safe methods for all CRUD and version operations
+
+  **Usage Example:**
+
+  ```typescript
+  // Server-side: Configure storage
+  import { Mastra } from '@mastra/core';
+  import { PgAgentsStorage } from '@mastra/pg';
+
+  const mastra = new Mastra({
+    agents: { agentOne },
+    storage: {
+      agents: new PgAgentsStorage({
+        connectionString: process.env.DATABASE_URL,
+      }),
+    },
+  });
+
+  // Client-side: Use the SDK
+  import { MastraClient } from '@mastra/client-js';
+
+  const client = new MastraClient({ baseUrl: 'http://localhost:3000' });
+
+  // Create a stored agent
+  const agent = await client.createStoredAgent({
+    name: 'Customer Support Agent',
+    description: 'Handles customer inquiries',
+    model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
+    instructions: 'You are a helpful customer support agent...',
+    tools: ['search', 'email'],
+  });
+
+  // Create a version snapshot
+  await client.storedAgent(agent.id).createVersion({
+    name: 'v1.0 - Initial release',
+    changeMessage: 'First production version',
+  });
+
+  // Compare versions
+  const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');
+  ```
+
+  **Why:**
+  This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.
+
+- Added `status` field to `listTraces` response. The status field indicates the trace state: `success` (completed without error), `error` (has error), or `running` (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the `error` and `endedAt` fields. ([#12213](https://github.com/mastra-ai/mastra/pull/12213))
+
+### Patch Changes
+
+- Updated dependencies [[`90fc0e5`](https://github.com/mastra-ai/mastra/commit/90fc0e5717cb280c2d4acf4f0410b510bb4c0a72), [`1cf5d2e`](https://github.com/mastra-ai/mastra/commit/1cf5d2ea1b085be23e34fb506c80c80a4e6d9c2b), [`833ae96`](https://github.com/mastra-ai/mastra/commit/833ae96c3e34370e58a1e979571c41f39a720592), [`943772b`](https://github.com/mastra-ai/mastra/commit/943772b4378f625f0f4e19ea2b7c392bd8e71786), [`b5c711b`](https://github.com/mastra-ai/mastra/commit/b5c711b281dd1fb81a399a766bc9f86c55efc13e), [`3efbe5a`](https://github.com/mastra-ai/mastra/commit/3efbe5ae20864c4f3143457f4f3ee7dc2fa5ca76), [`1e49e7a`](https://github.com/mastra-ai/mastra/commit/1e49e7ab5f173582154cb26b29d424de67d09aef), [`751eaab`](https://github.com/mastra-ai/mastra/commit/751eaab4e0d3820a94e4c3d39a2ff2663ded3d91), [`69d8156`](https://github.com/mastra-ai/mastra/commit/69d81568bcf062557c24471ce26812446bec465d), [`60d9d89`](https://github.com/mastra-ai/mastra/commit/60d9d899e44b35bc43f1bcd967a74e0ce010b1af), [`5c544c8`](https://github.com/mastra-ai/mastra/commit/5c544c8d12b08ab40d64d8f37b3c4215bee95b87), [`771ad96`](https://github.com/mastra-ai/mastra/commit/771ad962441996b5c43549391a3e6a02c6ddedc2), [`2b0936b`](https://github.com/mastra-ai/mastra/commit/2b0936b0c9a43eeed9bef63e614d7e02ee803f7e), [`3b04f30`](https://github.com/mastra-ai/mastra/commit/3b04f3010604f3cdfc8a0674731700ad66471cee), [`97e26de`](https://github.com/mastra-ai/mastra/commit/97e26deaebd9836647a67b96423281d66421ca07), [`10523f4`](https://github.com/mastra-ai/mastra/commit/10523f4882d9b874b40ce6e3715f66dbcd4947d2), [`cb72d20`](https://github.com/mastra-ai/mastra/commit/cb72d2069d7339bda8a0e76d4f35615debb07b84), [`42856b1`](https://github.com/mastra-ai/mastra/commit/42856b1c8aeea6371c9ee77ae2f5f5fe34400933), [`66f33ff`](https://github.com/mastra-ai/mastra/commit/66f33ff68620018513e499c394411d1d39b3aa5c), [`ab3c190`](https://github.com/mastra-ai/mastra/commit/ab3c1901980a99910ca9b96a7090c22e24060113), [`d4f06c8`](https://github.com/mastra-ai/mastra/commit/d4f06c85ffa5bb0da38fb82ebf3b040cc6b4ec4e), [`0350626`](https://github.com/mastra-ai/mastra/commit/03506267ec41b67add80d994c0c0fcce93bbc75f), [`bc9fa00`](https://github.com/mastra-ai/mastra/commit/bc9fa00859c5c4a796d53a0a5cae46ab4a3072e4), [`f46a478`](https://github.com/mastra-ai/mastra/commit/f46a4782f595949c696569e891f81c8d26338508), [`90fc0e5`](https://github.com/mastra-ai/mastra/commit/90fc0e5717cb280c2d4acf4f0410b510bb4c0a72), [`f05a3a5`](https://github.com/mastra-ai/mastra/commit/f05a3a5cf2b9a9c2d40c09cb8c762a4b6cd5d565), [`a291da9`](https://github.com/mastra-ai/mastra/commit/a291da9363efd92dafd8775dccb4f2d0511ece7a), [`c5d71da`](https://github.com/mastra-ai/mastra/commit/c5d71da1c680ce5640b1a7f8ca0e024a4ab1cfed), [`07042f9`](https://github.com/mastra-ai/mastra/commit/07042f9f89080f38b8f72713ba1c972d5b1905b8), [`0423442`](https://github.com/mastra-ai/mastra/commit/0423442b7be2dfacba95890bea8f4a810db4d603)]:
+  - @mastra/core@1.1.0-alpha.0
+
 ## 1.0.0
 
 ### Major Changes

package/dist/docs/README.md

@@ -33,4 +33,4 @@ docs/
 ## Version
 
 Package: @mastra/pg
-Version: 1.0.0
+Version: 1.1.0-alpha.0

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/pg. Includes links to type definitions an
 
 # @mastra/pg Documentation
 
-> **Version**: 1.0.0
+> **Version**: 1.1.0-alpha.0
 > **Package**: @mastra/pg
 
 ## Quick Navigation

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0",
+  "version": "1.1.0-alpha.0",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

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

@@ -2,7 +2,7 @@
 
 # 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.
+For agents to remember previous interactions, Mastra needs a database. Use a storage adapter for one of the [supported databases](#supported-providers) and pass it to your Mastra instance. 
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
@@ -15,35 +15,37 @@ export const mastra = new Mastra({
   }),
 });
 ```
-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.
+This configures instance-level storage, which all agents share by default. You can also configure [agent-level storage](#agent-level-storage) for isolated data boundaries.
+
+Mastra automatically creates the necessary tables on first interaction. See the [core schema](https://mastra.ai/reference/storage/overview#core-schema) for details on what gets created, including 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)
+- [libSQL](https://mastra.ai/reference/storage/libsql)
+- [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
+- [MongoDB](https://mastra.ai/reference/storage/mongodb)
+- [Upstash](https://mastra.ai/reference/storage/upstash)
+- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
+- [Cloudflare Durable Objects](https://mastra.ai/reference/storage/cloudflare)
+- [Convex](https://mastra.ai/reference/storage/convex)
+- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
+- [LanceDB](https://mastra.ai/reference/storage/lance)
+- [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
 
 > **Note:**
-libSQL is the easiest way to get started because it doesn’t require running a separate database server
+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:
+Storage can be configured at the instance level (shared by all agents) or at the agent level (isolated to a specific agent).
 
 ### Instance-level storage
 
 Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same memory provider:
 
-```typescript
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { PostgresStore } from "@mastra/pg";
 
@@ -54,7 +56,7 @@ export const mastra = new Mastra({
   }),
 });
 
-// All agents automatically use this storage
+// Both agents inherit storage from the Mastra instance above
 const agent1 = new Agent({ id: "agent-1", memory: new Memory() });
 const agent2 = new Agent({ id: "agent-2", memory: new Memory() });
 ```
@@ -63,7 +65,7 @@ This is useful when all primitives share the same storage backend and have simil
 
 #### Composite storage
 
-Add storage to your Mastra instance using `MastraCompositeStore` and configure individual storage domains to use different storage providers.
+[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to set the `memory` domain (and any other [domains](https://mastra.ai/reference/storage/composite#storage-domains) you need) to different storage providers.
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
@@ -76,6 +78,7 @@ export const mastra = new Mastra({
   storage: new MastraCompositeStore({
     id: "composite",
     domains: {
+      // highlight-next-line
       memory: new MemoryLibSQL({ url: "file:./memory.db" }),
       workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
       observability: new ObservabilityStorageClickhouse({
@@ -90,14 +93,11 @@ export const mastra = new Mastra({
 
 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:
+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"
+```typescript title="src/mastra/agents/your-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { PostgresStore } from "@mastra/pg";
@@ -113,56 +113,55 @@ export const agent = new Agent({
 });
 ```
 
-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.
+> **Note:**
+[Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment#using-mastra-cloud-store) doesn't support agent-level storage.
 
 ## Threads and resources
 
-Mastra organizes memory into threads using two identifiers:
+Mastra organizes conversations using two identifiers: 
+
+- **Thread** - a conversation session containing a sequence of messages.
+- **Resource** - the entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
 
-- **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 information:
 
-Both identifiers are required for agents to store and recall information:
+  **generate:**
 
 ```typescript
-const stream = await agent.stream("message for agent", {
+const response = await agent.generate("hello", {
   memory: {
-    thread: "convo_123",
+    thread: "conversation-abc-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
+  
+  **stream:**
 
-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
+```typescript
+const stream = await agent.stream("hello", {
+  memory: {
+    thread: "conversation-abc-123",
+    resource: "user_123",
+  },
+});
 ```
 
-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()`
+> **Note:**
+[Studio](https://mastra.ai/docs/getting-started/studio) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
 
 ### Thread title generation
 
-Mastra can automatically generate descriptive thread titles based on the user's first message.
+Mastra can automatically generate descriptive thread titles based on the user's first message when `generateTitle` is enabled.
 
 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",
+```typescript title="src/mastra/agents/my-agent.ts"
+export const agent = new Agent({
+  id: "agent",
   memory: new Memory({
     options: {
       generateTitle: true,
@@ -173,16 +172,16 @@ export const testAgent = new Agent({
 
 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`:
+To optimize cost or behavior, provide a smaller [`model`](/models) and custom `instructions`:
 
-```typescript
-export const testAgent = new Agent({
-  id: "test-agent",
+```typescript title="src/mastra/agents/my-agent.ts"
+export const agent = new Agent({
+  id: "agent",
   memory: new Memory({
     options: {
       generateTitle: {
         model: "openai/gpt-4o-mini",
-        instructions: "Generate a concise title based on the user's first message",
+        instructions: "Generate a 1 word title",
       },
     },
   }),
@@ -191,43 +190,72 @@ export const testAgent = new Agent({
 
 ## 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.
+Semantic recall has different storage requirements - it needs a vector database in addition to the standard storage adapter. See [Semantic recall](https://mastra.ai/docs/memory/semantic-recall) for setup and supported vector providers.
 
-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:
+## Handling large attachments
 
-```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";
+Some storage providers enforce record size limits that base64-encoded file attachments (such as images) can exceed:
 
-// Instance-level vector configuration
-export const mastra = new Mastra({
-  storage: new PostgresStore({
-    id: 'mastra-storage',
-    connectionString: process.env.DATABASE_URL,
-  }),
-});
+| Provider | Record size limit |
+| -------- | ----------------- |
+| [DynamoDB](https://mastra.ai/reference/storage/dynamodb) | 400 KB |
+| [Convex](https://mastra.ai/reference/storage/convex) | 1 MiB |
+| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB |
 
-// 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,
-      },
-    },
-  }),
-});
+PostgreSQL, MongoDB, and libSQL have higher limits and are generally unaffected.
+
+To avoid this, use an input processor to upload attachments to external storage (S3, R2, GCS, [Convex file storage](https://docs.convex.dev/file-storage), etc.) and replace them with URL references before persistence.
+
+```typescript title="src/mastra/processors/attachment-uploader.ts"
+import type { Processor } from "@mastra/core/processors";
+import type { MastraDBMessage } from "@mastra/core/memory";
+
+export class AttachmentUploader implements Processor {
+  id = "attachment-uploader";
+
+  async processInput({ messages }: { messages: MastraDBMessage[] }) {
+    return Promise.all(messages.map((msg) => this.processMessage(msg)));
+  }
+
+  async processMessage(msg: MastraDBMessage) {
+    const attachments = msg.content.experimental_attachments;
+    if (!attachments?.length) return msg;
+
+    const uploaded = await Promise.all(
+      attachments.map(async (att) => {
+        // Skip if already a URL
+        if (!att.url?.startsWith("data:")) return att;
+
+        // Upload base64 data and replace with URL
+        const url = await this.upload(att.url, att.contentType);
+        return { ...att, url };
+      })
+    );
+
+    return { ...msg, content: { ...msg.content, experimental_attachments: uploaded } };
+  }
+
+  async upload(dataUri: string, contentType?: string): Promise<string> {
+    const base64 = dataUri.split(",")[1];
+    const buffer = Buffer.from(base64, "base64");
+
+    // Replace with your storage provider (S3, R2, GCS, Convex, etc.)
+    // return await s3.upload(buffer, contentType);
+    throw new Error("Implement upload() with your storage provider");
+  }
+}
 ```
 
-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.
+Use the processor with your agent:
 
-For more information on configuring semantic recall, see the [Semantic Recall](./semantic-recall) documentation.
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { AttachmentUploader } from "./processors/attachment-uploader";
+
+const agent = new Agent({
+  id: "my-agent",
+  memory: new Memory({ storage: yourStorage }),
+  inputProcessors: [new AttachmentUploader()],
+});
+```

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

@@ -2,7 +2,7 @@
 
 # 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.
+While [message history](https://mastra.ai/docs/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.
 
@@ -383,6 +383,27 @@ await memory.updateWorkingMemory({
 });
 ```
 
+## 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)

package/dist/docs/memory/03-semantic-recall.md

@@ -37,9 +37,32 @@ const agent = new Agent({
 });
 ```
 
+## Using the recall() Method
+
+While `listMessages` retrieves messages by thread ID with basic pagination, [`recall()`](https://mastra.ai/reference/memory/recall) adds support for **semantic search**. When you need to find messages by meaning rather than just recency, use `recall()` with a `vectorSearchString`:
+
+```typescript
+const memory = await agent.getMemory();
+
+// Basic recall - similar to listMessages
+const { messages } = await memory!.recall({
+  threadId: "thread-123",
+  perPage: 50,
+});
+
+// Semantic recall - find messages by meaning
+const { messages: relevantMessages } = await memory!.recall({
+  threadId: "thread-123",
+  vectorSearchString: "What did we discuss about the project deadline?",
+  threadConfig: {
+    semanticRecall: true,
+  },
+});
+```
+
 ## Storage configuration
 
-Semantic recall relies on a [storage and vector db](https://mastra.ai/reference/v1/memory/memory-class) to store messages and their embeddings.
+Semantic recall relies on a [storage and vector db](https://mastra.ai/reference/memory/memory-class) to store messages and their embeddings.
 
 ```ts {8-16}
 import { Memory } from "@mastra/memory";
@@ -64,23 +87,23 @@ const agent = new Agent({
 
 Each vector store page below includes installation instructions, configuration parameters, and usage examples:
 
-- [Astra](https://mastra.ai/reference/v1/vectors/astra)
-- [Chroma](https://mastra.ai/reference/v1/vectors/chroma)
-- [Cloudflare Vectorize](https://mastra.ai/reference/v1/vectors/vectorize)
-- [Convex](https://mastra.ai/reference/v1/vectors/convex)
-- [Couchbase](https://mastra.ai/reference/v1/vectors/couchbase)
-- [DuckDB](https://mastra.ai/reference/v1/vectors/duckdb)
-- [Elasticsearch](https://mastra.ai/reference/v1/vectors/elasticsearch)
-- [LanceDB](https://mastra.ai/reference/v1/vectors/lance)
-- [libSQL](https://mastra.ai/reference/v1/vectors/libsql)
-- [MongoDB](https://mastra.ai/reference/v1/vectors/mongodb)
-- [OpenSearch](https://mastra.ai/reference/v1/vectors/opensearch)
-- [Pinecone](https://mastra.ai/reference/v1/vectors/pinecone)
-- [PostgreSQL](https://mastra.ai/reference/v1/vectors/pg)
-- [Qdrant](https://mastra.ai/reference/v1/vectors/qdrant)
-- [S3 Vectors](https://mastra.ai/reference/v1/vectors/s3vectors)
-- [Turbopuffer](https://mastra.ai/reference/v1/vectors/turbopuffer)
-- [Upstash](https://mastra.ai/reference/v1/vectors/upstash)
+- [Astra](https://mastra.ai/reference/vectors/astra)
+- [Chroma](https://mastra.ai/reference/vectors/chroma)
+- [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
+- [Convex](https://mastra.ai/reference/vectors/convex)
+- [Couchbase](https://mastra.ai/reference/vectors/couchbase)
+- [DuckDB](https://mastra.ai/reference/vectors/duckdb)
+- [Elasticsearch](https://mastra.ai/reference/vectors/elasticsearch)
+- [LanceDB](https://mastra.ai/reference/vectors/lance)
+- [libSQL](https://mastra.ai/reference/vectors/libsql)
+- [MongoDB](https://mastra.ai/reference/vectors/mongodb)
+- [OpenSearch](https://mastra.ai/reference/vectors/opensearch)
+- [Pinecone](https://mastra.ai/reference/vectors/pinecone)
+- [PostgreSQL](https://mastra.ai/reference/vectors/pg)
+- [Qdrant](https://mastra.ai/reference/vectors/qdrant)
+- [S3 Vectors](https://mastra.ai/reference/vectors/s3vectors)
+- [Turbopuffer](https://mastra.ai/reference/vectors/turbopuffer)
+- [Upstash](https://mastra.ai/reference/vectors/upstash)
 
 ## Recall configuration
 
@@ -106,7 +129,7 @@ const agent = new Agent({
 
 ## Embedder configuration
 
-Semantic recall relies on an [embedding model](https://mastra.ai/reference/v1/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
+Semantic recall relies on an [embedding model](https://mastra.ai/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
 
 #### Using the Model Router (Recommended)
 
@@ -127,7 +150,7 @@ const agent = new Agent({
 Supported embedding models:
 
 - **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
-- **Google**: `gemini-embedding-001`, `text-embedding-004`
+- **Google**: `gemini-embedding-001`
 
 The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`).
 
@@ -152,7 +175,7 @@ const agent = new Agent({
 To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
 
 ```bash npm2yarn
-npm install @mastra/fastembed@beta
+npm install @mastra/fastembed@latest
 ```
 
 Then configure it in your memory:
@@ -205,7 +228,7 @@ const agent = new Agent({
 });
 ```
 
-For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/v1/vectors/pg#index-configuration-guide).
+For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg#index-configuration-guide).
 
 ## Disabling
 

package/dist/docs/memory/04-reference.md

@@ -120,14 +120,14 @@ export const agent = new Agent({
 
 ### Related
 
-- [Getting Started with Memory](https://mastra.ai/docs/v1/memory/overview)
-- [Semantic Recall](https://mastra.ai/docs/v1/memory/semantic-recall)
-- [Working Memory](https://mastra.ai/docs/v1/memory/working-memory)
-- [Memory Processors](https://mastra.ai/docs/v1/memory/memory-processors)
-- [createThread](https://mastra.ai/reference/v1/memory/createThread)
-- [recall](https://mastra.ai/reference/v1/memory/recall)
-- [getThreadById](https://mastra.ai/reference/v1/memory/getThreadById)
-- [listThreads](https://mastra.ai/reference/v1/memory/listThreads)
-- [deleteMessages](https://mastra.ai/reference/v1/memory/deleteMessages)
-- [cloneThread](https://mastra.ai/reference/v1/memory/cloneThread)
-- [Clone Utility Methods](https://mastra.ai/reference/v1/memory/clone-utilities)
+- [Getting Started with Memory](https://mastra.ai/docs/memory/overview)
+- [Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)
+- [Working Memory](https://mastra.ai/docs/memory/working-memory)
+- [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
+- [createThread](https://mastra.ai/reference/memory/createThread)
+- [recall](https://mastra.ai/reference/memory/recall)
+- [getThreadById](https://mastra.ai/reference/memory/getThreadById)
+- [listThreads](https://mastra.ai/reference/memory/listThreads)
+- [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)
+- [cloneThread](https://mastra.ai/reference/memory/cloneThread)
+- [Clone Utility Methods](https://mastra.ai/reference/memory/clone-utilities)

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

@@ -75,7 +75,7 @@ export const agent = new Agent({
 
 ## Related
 
-- [Guardrails](https://mastra.ai/docs/v1/agents/guardrails)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)
 
 ---
 
@@ -172,7 +172,7 @@ When `scope` is set to `'resource'`, the processor can recall messages from othe
 
 ## Related
 
-- [Guardrails](https://mastra.ai/docs/v1/agents/guardrails)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)
 
 ---
 
@@ -276,10 +276,9 @@ const processor = new WorkingMemory({
    - Thread metadata (`scope: 'thread'`)
    - Resource record (`scope: 'resource'`)
 3. Resolves the template (from provider, options, or default)
-4. Generates system instructions that include:
-   - Guidelines for the LLM on storing and updating information
-   - The template structure
-   - Current working memory data
+4. Generates system instructions based on mode:
+   - **Normal mode**: Includes guidelines for storing/updating information, template structure, and current data
+   - **Read-only mode** (`readOnly: true`): Includes only the current data as context without update instructions
 5. Adds the instruction as a system message with `source: 'memory'` tag
 
 ### Working memory updates
@@ -294,4 +293,4 @@ If no template is provided, the processor uses a default markdown template with
 
 ## Related
 
-- [Guardrails](https://mastra.ai/docs/v1/agents/guardrails)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)