@mastra/memory 1.0.0 → 1.0.1-alpha.1

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

@@ -11,24 +11,26 @@
 
 The DynamoDB storage implementation provides a scalable and performant NoSQL database solution for Mastra, leveraging a single-table design pattern with [ElectroDB](https://electrodb.dev/).
 
+> **Observability Not Supported**
+DynamoDB storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to DynamoDB, and Mastra Studio's observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+
+> **Item Size Limit**
+DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage#handling-large-attachments) for workarounds including uploading attachments to external storage.
+
 ## Features
 
 - Efficient single-table design for all Mastra storage needs
 - Based on ElectroDB for type-safe DynamoDB access
 - Support for AWS credentials, regions, and endpoints
 - Compatible with AWS DynamoDB Local for development
-- Stores Thread, Message, Trace, Eval, and Workflow data
+- Stores Thread, Message, Eval, and Workflow data
 - Optimized for serverless environments
 - Configurable TTL (Time To Live) for automatic data expiration per entity type
 
 ## Installation
 
-```bash
-npm install @mastra/dynamodb@beta
-# or
-pnpm add @mastra/dynamodb@beta
-# or
-yarn add @mastra/dynamodb@beta
+```bash npm2yarn
+npm install @mastra/dynamodb@latest
 ```
 
 ## Prerequisites
@@ -260,14 +262,14 @@ This implementation uses a single-table design pattern with ElectroDB, which off
 
 [libSQL](https://docs.turso.tech/libsql) is an open-source, SQLite-compatible database that supports both local and remote deployments. It can be used to store message history, workflow snapshots, traces, and eval scores.
 
-For vectors like semantic recall or traditional RAG, use [libSQL Vector](https://mastra.ai/reference/v1/vectors/libsql) which covers embeddings and vector search.
+For vectors like semantic recall or traditional RAG, use [libSQL Vector](https://mastra.ai/reference/vectors/libsql) which covers embeddings and vector search.
 
 ## Installation
 
 Storage providers must be installed as separate packages:
 
-```bash
-npm install @mastra/libsql@beta
+```bash npm2yarn
+npm install @mastra/libsql@latest
 ```
 
 ## Usage
@@ -330,7 +332,7 @@ In-memory storage resets when the process changes. Only suitable for development
 
 ## Initialization
 
-When you pass storage to the Mastra class, `init()` is called automatically to create the [core schema](https://mastra.ai/reference/v1/storage/overview#core-schema):
+When you pass storage to the Mastra class, `init()` is called automatically to create the [core schema](https://mastra.ai/reference/storage/overview#core-schema):
 
 ```typescript 
 import { Mastra } from "@mastra/core";
@@ -363,6 +365,12 @@ const memoryStore = await storage.getStore('memory');
 const thread = await memoryStore?.getThreadById({ threadId: "..." });
 ```
 
+## Observability
+
+libSQL supports observability and is ideal for local development. Use the `realtime` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/default#tracing-strategies) for immediate visibility while debugging.
+
+For production environments with higher trace volumes, consider using [PostgreSQL](https://mastra.ai/reference/storage/postgresql) or [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability).
+
 ---
 
 ## Reference: MongoDB Storage
@@ -373,8 +381,8 @@ The MongoDB storage implementation provides a scalable storage solution using Mo
 
 ## Installation
 
-```bash
-npm install @mastra/mongodb@beta
+```bash npm2yarn
+npm install @mastra/mongodb@latest
 ```
 
 ## Usage
@@ -612,8 +620,8 @@ The PostgreSQL storage implementation provides a production-ready storage soluti
 
 ## Installation
 
-```bash
-npm install @mastra/pg@beta
+```bash npm2yarn
+npm install @mastra/pg@latest
 ```
 
 ## Usage
@@ -635,22 +643,26 @@ You can instantiate `PostgresStore` in the following ways:
 
 ```ts
 import { PostgresStore } from "@mastra/pg";
+import { Pool } from "pg";
 
-// Using a connection string only
+// Using a connection string
 const store1 = new PostgresStore({
   id: 'pg-storage-1',
   connectionString: "postgresql://user:password@localhost:5432/mydb",
 });
 
-// Using a connection string with a custom schema name
+// Using a connection string with pool options
 const store2 = new PostgresStore({
   id: 'pg-storage-2',
   connectionString: "postgresql://user:password@localhost:5432/mydb",
-  schemaName: "custom_schema", // optional
+  schemaName: "custom_schema",
+  max: 30,                    // Max pool connections
+  idleTimeoutMillis: 60000,   // Idle timeout
+  ssl: { rejectUnauthorized: false },
 });
 
 // Using individual connection parameters
-const store4 = new PostgresStore({
+const store3 = new PostgresStore({
   id: 'pg-storage-3',
   host: "localhost",
   port: 5432,
@@ -659,14 +671,16 @@ const store4 = new PostgresStore({
   password: "password",
 });
 
-// Individual parameters with schemaName
-const store5 = new PostgresStore({
+// Using a pre-configured pg.Pool (recommended for pool reuse)
+const existingPool = new Pool({
+  connectionString: "postgresql://user:password@localhost:5432/mydb",
+  max: 20,
+  // ... your custom pool configuration
+});
+
+const store4 = new PostgresStore({
   id: 'pg-storage-4',
-  host: "localhost",
-  port: 5432,
-  database: "mydb",
-  user: "user",
-  password: "password",
+  pool: existingPool,
   schemaName: "custom_schema", // optional
 });
 ```
@@ -685,6 +699,14 @@ The storage implementation handles schema creation and updates automatically. It
 - `mastra_scorers`: Stores scoring and evaluation data
 - `mastra_resources`: Stores resource working memory data
 
+### Observability
+
+PostgreSQL supports observability and can handle low trace volumes. Throughput capacity depends on deployment factors such as hardware, schema design, indexing, and retention policies, and should be validated for your specific environment. For high-volume production environments, consider:
+
+- Using the `insert-only` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/default#tracing-strategies) to reduce database write operations
+- Setting up table partitioning for efficient data retention
+- Migrating observability to [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability) if you need to scale further
+
 ### Initialization
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
@@ -724,19 +746,74 @@ const thread = await memoryStore?.getThreadById({ threadId: "..." });
 > **Note:**
 If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
 
+### Using an Existing Pool
+
+If you already have a `pg.Pool` in your application (e.g., shared with an ORM or for Row Level Security), you can pass it directly to `PostgresStore`:
+
+```typescript
+import { Pool } from "pg";
+import { PostgresStore } from "@mastra/pg";
+
+// Your existing pool (shared across your application)
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,
+});
+
+const storage = new PostgresStore({
+  id: "shared-storage",
+  pool: pool,
+});
+```
+
+**Pool lifecycle behavior:**
+
+- When you **provide a pool**: Mastra uses your pool but does **not** close it when `store.close()` is called. You manage the pool lifecycle.
+- When Mastra **creates a pool**: Mastra owns the pool and will close it when `store.close()` is called.
+
 ### Direct Database and Pool Access
 
-`PostgresStore` exposes both the underlying database object and the pg-promise instance as public fields:
+`PostgresStore` exposes the underlying database client and pool for advanced use cases:
 
 ```typescript
-store.db; // pg-promise database instance
-store.pgp; // pg-promise main instance
+store.db;   // DbClient - query interface with helpers (any, one, tx, etc.)
+store.pool; // pg.Pool - the underlying connection pool
 ```
 
-This enables direct queries and custom transaction management. When using these fields:
+**Using `store.db` for queries:**
+
+```typescript
+// Execute queries with helper methods
+const users = await store.db.any("SELECT * FROM users WHERE active = $1", [true]);
+const user = await store.db.one("SELECT * FROM users WHERE id = $1", [userId]);
+const maybeUser = await store.db.oneOrNone("SELECT * FROM users WHERE email = $1", [email]);
+
+// Use transactions
+const result = await store.db.tx(async (t) => {
+  await t.none("INSERT INTO logs (message) VALUES ($1)", ["Started"]);
+  const data = await t.any("SELECT * FROM items");
+  return data;
+});
+```
+
+**Using `store.pool` directly:**
+
+```typescript
+// Get a client for manual connection management
+const client = await store.pool.connect();
+try {
+  await client.query("SET LOCAL app.user_id = $1", [userId]);
+  const result = await client.query("SELECT * FROM protected_table");
+  return result.rows;
+} finally {
+  client.release();
+}
+```
+
+When using these fields:
 
 - You are responsible for proper connection and transaction handling.
-- Closing the store (`store.close()`) will destroy the associated connection pool.
+- Closing the store (`store.close()`) will destroy the pool only if Mastra created it.
 - Direct access bypasses any additional logic or validation provided by PostgresStore methods.
 
 This approach is intended for advanced scenarios where low-level access is required.
@@ -1007,14 +1084,16 @@ PostgreSQL offers different index types optimized for specific scenarios:
 
 The Upstash storage implementation provides a serverless-friendly storage solution using Upstash's Redis-compatible key-value store.
 
-> **Note:**
+> **Pricing**
+When using Mastra with Upstash, the pay-as-you-go model can result in unexpectedly high costs due to the high volume of Redis commands generated during agent conversations. We strongly recommend using a **fixed pricing plan** for predictable costs. See [Upstash pricing](https://upstash.com/pricing/redis) for details and [GitHub issue #5850](https://github.com/mastra-ai/mastra/issues/5850) for context.
 
-**Important:** When using Mastra with Upstash, the pay-as-you-go model can result in unexpectedly high costs due to the high volume of Redis commands generated during agent conversations. We strongly recommend using a **fixed pricing plan** for predictable costs. See [Upstash pricing](https://upstash.com/pricing/redis) for details and [GitHub issue #5850](https://github.com/mastra-ai/mastra/issues/5850) for context.
+> **Observability Not Supported**
+Upstash storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to Upstash, and Mastra Studio's observability features won't work with Upstash as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability) to route observability data to a supported provider like ClickHouse or PostgreSQL.
 
 ## Installation
 
-```bash
-npm install @mastra/upstash@beta
+```bash npm2yarn
+npm install @mastra/upstash@latest
 ```
 
 ## Usage

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

@@ -14,8 +14,8 @@ It's part of the `@mastra/libsql` package and offers efficient vector similarity
 
 ## Installation
 
-```bash
-npm install @mastra/libsql@beta
+```bash npm2yarn
+npm install @mastra/libsql@latest
 ```
 
 ## Usage
@@ -168,8 +168,8 @@ Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve rel
 
 Install `fastembed` to get started:
 
-```bash 
-npm install @mastra/fastembed@beta
+```bash npm2yarn
+npm install @mastra/fastembed@latest
 ```
 
 Add the following to your agent:
@@ -222,8 +222,8 @@ The `MongoDBVector` class provides vector search using [MongoDB Atlas Vector Sea
 
 ## Installation
 
-```bash
-npm install @mastra/mongodb@beta
+```bash npm2yarn
+npm install @mastra/mongodb@latest
 ```
 
 ## Usage Example
@@ -363,8 +363,8 @@ Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve rel
 This setup uses FastEmbed, a local embedding model, to generate vector embeddings.
 To use this, install `@mastra/fastembed`:
 
-```bash 
-npm install @mastra/fastembed@beta
+```bash npm2yarn
+npm install @mastra/fastembed@latest
 ```
 
 Add the following to your agent:
@@ -669,8 +669,8 @@ Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve rel
 
 Install `fastembed` to get started:
 
-```bash
-npm install @mastra/fastembed@beta
+```bash npm2yarn
+npm install @mastra/fastembed@latest
 ```
 
 Add the following to your agent:
@@ -896,8 +896,8 @@ Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve rel
 
 Install `fastembed` to get started:
 
-```bash
-npm install @mastra/fastembed@beta
+```bash npm2yarn
+npm install @mastra/fastembed@latest
 ```
 
 Add the following to your agent:

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkSG3GRV3O_cjs = require('./chunk-SG3GRV3O.cjs');
-var chunkZUQPUTTO_cjs = require('./chunk-ZUQPUTTO.cjs');
+var chunk23EXJLET_cjs = require('./chunk-23EXJLET.cjs');
+var chunkO3CS4UGX_cjs = require('./chunk-O3CS4UGX.cjs');
 var zod = require('zod');
 var z4 = require('zod/v4');
 var v3 = require('zod/v3');
@@ -65,7 +65,7 @@ var __toESM3 = (mod, isNodeMode, target) => (target = mod != null ? __create(__g
   mod
 ));
 var require_secure_json_parse = __commonJS3({
-  "../../../node_modules/.pnpm/secure-json-parse@2.7.0/node_modules/secure-json-parse/index.js"(exports, module) {
+  "../../../node_modules/.pnpm/secure-json-parse@2.7.0/node_modules/secure-json-parse/index.js"(exports$1, module) {
     var hasBuffer = typeof Buffer !== "undefined";
     var suspectProtoRx3 = /"(?:_|\\u005[Ff])(?:_|\\u005[Ff])(?:p|\\u0070)(?:r|\\u0072)(?:o|\\u006[Ff])(?:t|\\u0074)(?:o|\\u006[Ff])(?:_|\\u005[Ff])(?:_|\\u005[Ff])"\s*:/;
     var suspectConstructorRx3 = /"(?:c|\\u0063)(?:o|\\u006[Ff])(?:n|\\u006[Ee])(?:s|\\u0073)(?:t|\\u0074)(?:r|\\u0072)(?:u|\\u0075)(?:c|\\u0063)(?:t|\\u0074)(?:o|\\u006[Ff])(?:r|\\u0072)"\s*:/;
@@ -6180,8 +6180,8 @@ function asSchema2(schema) {
 function withoutTrailingSlash(url) {
   return url == null ? void 0 : url.replace(/\/$/, "");
 }
-var require_get_context = chunkSG3GRV3O_cjs.__commonJS({
-  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/get-context.js"(exports, module) {
+var require_get_context = chunk23EXJLET_cjs.__commonJS({
+  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/get-context.js"(exports$1, module) {
     var __defProp22 = Object.defineProperty;
     var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
     var __getOwnPropNames2 = Object.getOwnPropertyNames;
@@ -6212,8 +6212,8 @@ var require_get_context = chunkSG3GRV3O_cjs.__commonJS({
     }
   }
 });
-var require_get_vercel_oidc_token = chunkSG3GRV3O_cjs.__commonJS({
-  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/get-vercel-oidc-token.js"(exports, module) {
+var require_get_vercel_oidc_token = chunk23EXJLET_cjs.__commonJS({
+  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/get-vercel-oidc-token.js"(exports$1, module) {
     var __defProp22 = Object.defineProperty;
     var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
     var __getOwnPropNames2 = Object.getOwnPropertyNames;
@@ -6238,7 +6238,7 @@ var require_get_vercel_oidc_token = chunkSG3GRV3O_cjs.__commonJS({
     });
     module.exports = __toCommonJS(get_vercel_oidc_token_exports);
     var import_get_context = require_get_context();
-    var import_token_error = chunkSG3GRV3O_cjs.require_token_error();
+    var import_token_error = chunk23EXJLET_cjs.require_token_error();
     async function getVercelOidcToken3() {
       let token = "";
       let err;
@@ -6249,8 +6249,8 @@ var require_get_vercel_oidc_token = chunkSG3GRV3O_cjs.__commonJS({
       }
       try {
         const [{ getTokenPayload, isExpired }, { refreshToken }] = await Promise.all([
-          await import('./token-util-NEHG7TUY-7IL6JUVY.cjs'),
-          await import('./token-6GSAFR2W-YCB5SK2Z.cjs')
+          await import('./token-util-NEHG7TUY-GYFEVMWP.cjs'),
+          await import('./token-6GSAFR2W-TW2P7HCS.cjs')
         ]);
         if (!token || isExpired(getTokenPayload(token))) {
           await refreshToken();
@@ -6276,8 +6276,8 @@ ${error.message}`;
     }
   }
 });
-var require_dist = chunkSG3GRV3O_cjs.__commonJS({
-  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/index.js"(exports, module) {
+var require_dist = chunk23EXJLET_cjs.__commonJS({
+  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/index.js"(exports$1, module) {
     var __defProp22 = Object.defineProperty;
     var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
     var __getOwnPropNames2 = Object.getOwnPropertyNames;
@@ -6306,8 +6306,8 @@ var require_dist = chunkSG3GRV3O_cjs.__commonJS({
     var import_get_context = require_get_context();
   }
 });
-var import_oidc = chunkSG3GRV3O_cjs.__toESM(require_dist(), 1);
-var import_oidc2 = chunkSG3GRV3O_cjs.__toESM(require_dist(), 1);
+var import_oidc = chunk23EXJLET_cjs.__toESM(require_dist(), 1);
+var import_oidc2 = chunk23EXJLET_cjs.__toESM(require_dist(), 1);
 var marker18 = "vercel.ai.gateway.error";
 var symbol18 = Symbol.for(marker18);
 var _a18;
@@ -11138,8 +11138,8 @@ var createJsonResponseHandler2 = (responseSchema) => async ({ response, url, req
 function withoutTrailingSlash2(url) {
   return url == null ? void 0 : url.replace(/\/$/, "");
 }
-var require_get_context2 = chunkZUQPUTTO_cjs.__commonJS({
-  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/get-context.js"(exports, module) {
+var require_get_context2 = chunkO3CS4UGX_cjs.__commonJS({
+  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/get-context.js"(exports$1, module) {
     var __defProp22 = Object.defineProperty;
     var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
     var __getOwnPropNames2 = Object.getOwnPropertyNames;
@@ -11170,8 +11170,8 @@ var require_get_context2 = chunkZUQPUTTO_cjs.__commonJS({
     }
   }
 });
-var require_get_vercel_oidc_token2 = chunkZUQPUTTO_cjs.__commonJS({
-  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/get-vercel-oidc-token.js"(exports, module) {
+var require_get_vercel_oidc_token2 = chunkO3CS4UGX_cjs.__commonJS({
+  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/get-vercel-oidc-token.js"(exports$1, module) {
     var __defProp22 = Object.defineProperty;
     var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
     var __getOwnPropNames2 = Object.getOwnPropertyNames;
@@ -11196,7 +11196,7 @@ var require_get_vercel_oidc_token2 = chunkZUQPUTTO_cjs.__commonJS({
     });
     module.exports = __toCommonJS(get_vercel_oidc_token_exports);
     var import_get_context = require_get_context2();
-    var import_token_error = chunkZUQPUTTO_cjs.require_token_error();
+    var import_token_error = chunkO3CS4UGX_cjs.require_token_error();
     async function getVercelOidcToken3() {
       let token = "";
       let err;
@@ -11207,8 +11207,8 @@ var require_get_vercel_oidc_token2 = chunkZUQPUTTO_cjs.__commonJS({
       }
       try {
         const [{ getTokenPayload, isExpired }, { refreshToken }] = await Promise.all([
-          await import('./token-util-NEHG7TUY-HF7KBP2H.cjs'),
-          await import('./token-6GSAFR2W-JV3TZR4M.cjs')
+          await import('./token-util-NEHG7TUY-WJZIPNNX.cjs'),
+          await import('./token-6GSAFR2W-2B4WM6AQ.cjs')
         ]);
         if (!token || isExpired(getTokenPayload(token))) {
           await refreshToken();
@@ -11234,8 +11234,8 @@ ${error.message}`;
     }
   }
 });
-var require_dist2 = chunkZUQPUTTO_cjs.__commonJS({
-  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/index.js"(exports, module) {
+var require_dist2 = chunkO3CS4UGX_cjs.__commonJS({
+  "../../../node_modules/.pnpm/@vercel+oidc@3.0.5/node_modules/@vercel/oidc/dist/index.js"(exports$1, module) {
     var __defProp22 = Object.defineProperty;
     var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
     var __getOwnPropNames2 = Object.getOwnPropertyNames;
@@ -11264,8 +11264,8 @@ var require_dist2 = chunkZUQPUTTO_cjs.__commonJS({
     var import_get_context = require_get_context2();
   }
 });
-var import_oidc3 = chunkZUQPUTTO_cjs.__toESM(require_dist2(), 1);
-var import_oidc22 = chunkZUQPUTTO_cjs.__toESM(require_dist2(), 1);
+var import_oidc3 = chunkO3CS4UGX_cjs.__toESM(require_dist2(), 1);
+var import_oidc22 = chunkO3CS4UGX_cjs.__toESM(require_dist2(), 1);
 var marker20 = "vercel.ai.gateway.error";
 var symbol20 = Symbol.for(marker20);
 var _a20;
@@ -14958,7 +14958,7 @@ ${workingMemory}`;
     const promise = embedFn({
       values: chunks,
       maxRetries: 3,
-      // @ts-ignore
+      // @ts-expect-error - embedder type mismatch
       model: this.embedder,
       ...this.embedderOptions || {}
     });
@@ -15142,6 +15142,12 @@ ${workingMemory}`;
     if (!workingMemoryTemplate) {
       return null;
     }
+    if (config?.readOnly) {
+      return this.getReadOnlyWorkingMemoryInstruction({
+        template: workingMemoryTemplate,
+        data: workingMemoryData
+      });
+    }
     return this.isVNextWorkingMemoryConfig(memoryConfig) ? this.__experimental_getWorkingMemoryToolInstructionVNext({
       template: workingMemoryTemplate,
       data: workingMemoryData
@@ -15229,10 +15235,32 @@ Notes:
 ${template.content !== this.defaultWorkingMemoryTemplate ? `- Only store information if it's in the working memory template, do not store other information unless the user asks you to remember it, as that non-template information may be irrelevant` : `- If you're unsure whether to store something, store it (eg if the user tells you information about themselves, call updateWorkingMemory immediately to update it)
 `}
 - This system is here so that you can maintain the conversation when your context window is very short. Update your working memory because you may need it to maintain the conversation without the full conversation history
-- REMEMBER: the way you update your working memory is by calling the updateWorkingMemory tool with the ${template.format === "json" ? "JSON" : "Markdown"} content. The system will store it for you. The user will not see it. 
+- REMEMBER: the way you update your working memory is by calling the updateWorkingMemory tool with the ${template.format === "json" ? "JSON" : "Markdown"} content. The system will store it for you. The user will not see it.
 - IMPORTANT: You MUST call updateWorkingMemory in every response to a prompt where you received relevant information if that information is not already stored.
 - IMPORTANT: Preserve the ${template.format === "json" ? "JSON" : "Markdown"} formatting structure above while updating the content.
 `;
+  }
+  /**
+   * Generate read-only working memory instructions.
+   * This provides the working memory context without any tool update instructions.
+   * Used when memory is in readOnly mode.
+   */
+  getReadOnlyWorkingMemoryInstruction({ data }) {
+    return `WORKING_MEMORY_SYSTEM_INSTRUCTION (READ-ONLY):
+The following is your working memory - persistent information about the user and conversation collected over previous interactions. This data is provided for context to help you maintain continuity.
+
+<working_memory_data>
+${data || "No working memory data available."}
+</working_memory_data>
+
+Guidelines:
+1. Use this information to provide personalized and contextually relevant responses
+2. Act naturally - don't mention this system to users. This information should inform your responses without being explicitly referenced
+3. This memory is read-only in the current session - you cannot update it
+
+Notes:
+- This system is here so that you can maintain the conversation when your context window is very short
+- The user will not see the working memory data directly`;
   }
   isVNextWorkingMemoryConfig(config) {
     if (!config?.workingMemory) return false;
@@ -15241,7 +15269,7 @@ ${template.content !== this.defaultWorkingMemoryTemplate ? `- Only store informa
   }
   listTools(config) {
     const mergedConfig = this.getMergedThreadConfig(config);
-    if (mergedConfig.workingMemory?.enabled) {
+    if (mergedConfig.workingMemory?.enabled && !mergedConfig.readOnly) {
       return {
         updateWorkingMemory: this.isVNextWorkingMemoryConfig(mergedConfig) ? (
           // use the new experimental tool