@mastra/mongodb 1.0.0 → 1.1.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # @mastra/mongodb
 
+## 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

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

package/dist/docs/SKILL.md

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

package/dist/docs/SOURCE_MAP.json

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

package/dist/docs/memory/01-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/rag/01-vector-databases.md

@@ -376,7 +376,7 @@ The dimension size must match the output dimension of your chosen embedding mode
 
 - OpenAI text-embedding-3-small: 1536 dimensions (or custom, e.g., 256)
 - Cohere embed-multilingual-v3: 1024 dimensions
-- Google text-embedding-004: 768 dimensions (or custom)
+- Google gemini-embedding-001: 768 dimensions (or custom)
 
 > **Note:**
 Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.

package/dist/docs/rag/02-retrieval.md

@@ -73,7 +73,7 @@ Filter results based on metadata fields to narrow down the search space. This ap
 
 This is useful when you have documents from different sources, time periods, or with specific attributes. Mastra provides a unified MongoDB-style query syntax that works across all supported vector stores.
 
-For detailed information about available operators and syntax, see the [Metadata Filters Reference](https://mastra.ai/reference/v1/rag/metadata-filters).
+For detailed information about available operators and syntax, see the [Metadata Filters Reference](https://mastra.ai/reference/rag/metadata-filters).
 
 Basic filtering examples:
 
@@ -264,7 +264,7 @@ await pineconeQueryTool.execute(
 );
 ```
 
-For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/v1/tools/vector-query-tool).
+For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/tools/vector-query-tool).
 
 ### Vector Store Prompts
 
@@ -543,6 +543,6 @@ const relevanceProvider = new ZeroEntropyRelevanceScorer("zerank-1");
 
 The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
 
-For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/v1/rag/rerankWithScorer) method.
+For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
 
-For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/docs/v1/rag/graph-rag) documentation.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/docs/rag/graph-rag) documentation.

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

@@ -13,8 +13,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

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

@@ -13,8 +13,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
@@ -154,8 +154,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:

package/dist/index.cjs

@@ -13,7 +13,7 @@ var evals = require('@mastra/core/evals');
 
 // package.json
 var package_default = {
-  version: "1.0.0"};
+  version: "1.1.0-alpha.0"};
 var MongoDBFilterTranslator = class extends filter.BaseFilterTranslator {
   getSupportedOperators() {
     return {
@@ -899,7 +899,7 @@ var MongoDBAgentsStorage = class _MongoDBAgentsStorage extends storage.AgentsSto
   #skipDefaultIndexes;
   #indexes;
   /** Collections managed by this domain */
-  static MANAGED_COLLECTIONS = [storage.TABLE_AGENTS];
+  static MANAGED_COLLECTIONS = [storage.TABLE_AGENTS, storage.TABLE_AGENT_VERSIONS];
   constructor(config) {
     super();
     this.#connector = resolveMongoDBConfig(config);
@@ -919,7 +919,10 @@ var MongoDBAgentsStorage = class _MongoDBAgentsStorage extends storage.AgentsSto
     return [
       { collection: storage.TABLE_AGENTS, keys: { id: 1 }, options: { unique: true } },
       { collection: storage.TABLE_AGENTS, keys: { createdAt: -1 } },
-      { collection: storage.TABLE_AGENTS, keys: { updatedAt: -1 } }
+      { collection: storage.TABLE_AGENTS, keys: { updatedAt: -1 } },
+      { collection: storage.TABLE_AGENT_VERSIONS, keys: { id: 1 }, options: { unique: true } },
+      { collection: storage.TABLE_AGENT_VERSIONS, keys: { agentId: 1, versionNumber: -1 }, options: { unique: true } },
+      { collection: storage.TABLE_AGENT_VERSIONS, keys: { agentId: 1, createdAt: -1 } }
     ];
   }
   async createDefaultIndexes() {
@@ -956,8 +959,10 @@ var MongoDBAgentsStorage = class _MongoDBAgentsStorage extends storage.AgentsSto
     await this.createCustomIndexes();
   }
   async dangerouslyClearAll() {
-    const collection = await this.getCollection(storage.TABLE_AGENTS);
-    await collection.deleteMany({});
+    const versionsCollection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+    await versionsCollection.deleteMany({});
+    const agentsCollection = await this.getCollection(storage.TABLE_AGENTS);
+    await agentsCollection.deleteMany({});
   }
   async getAgentById({ id }) {
     try {
@@ -1043,6 +1048,9 @@ var MongoDBAgentsStorage = class _MongoDBAgentsStorage extends storage.AgentsSto
       if (updates.outputProcessors !== void 0) updateDoc.outputProcessors = updates.outputProcessors;
       if (updates.memory !== void 0) updateDoc.memory = updates.memory;
       if (updates.scorers !== void 0) updateDoc.scorers = updates.scorers;
+      if (updates.integrationTools !== void 0) updateDoc.integrationTools = updates.integrationTools;
+      if (updates.ownerId !== void 0) updateDoc.ownerId = updates.ownerId;
+      if (updates.activeVersionId !== void 0) updateDoc.activeVersionId = updates.activeVersionId;
       if (updates.metadata !== void 0) {
         const existingMetadata = existingAgent.metadata || {};
         updateDoc.metadata = { ...existingMetadata, ...updates.metadata };
@@ -1076,6 +1084,7 @@ var MongoDBAgentsStorage = class _MongoDBAgentsStorage extends storage.AgentsSto
   }
   async deleteAgent({ id }) {
     try {
+      await this.deleteVersionsByAgentId(id);
       const collection = await this.getCollection(storage.TABLE_AGENTS);
       await collection.deleteOne({ id });
     } catch (error$1) {
@@ -1159,6 +1168,212 @@ var MongoDBAgentsStorage = class _MongoDBAgentsStorage extends storage.AgentsSto
       ...agent
     };
   }
+  // ==========================================================================
+  // Agent Version Methods
+  // ==========================================================================
+  async createVersion(input) {
+    try {
+      const collection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+      const now = /* @__PURE__ */ new Date();
+      const versionDoc = {
+        id: input.id,
+        agentId: input.agentId,
+        versionNumber: input.versionNumber,
+        name: input.name ?? void 0,
+        snapshot: input.snapshot,
+        changedFields: input.changedFields ?? void 0,
+        changeMessage: input.changeMessage ?? void 0,
+        createdAt: now
+      };
+      await collection.insertOne(versionDoc);
+      return {
+        ...input,
+        createdAt: now
+      };
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "CREATE_VERSION", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { versionId: input.id, agentId: input.agentId }
+        },
+        error$1
+      );
+    }
+  }
+  async getVersion(id) {
+    try {
+      const collection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+      const result = await collection.findOne({ id });
+      if (!result) {
+        return null;
+      }
+      return this.transformVersion(result);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "GET_VERSION", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { versionId: id }
+        },
+        error$1
+      );
+    }
+  }
+  async getVersionByNumber(agentId, versionNumber) {
+    try {
+      const collection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+      const result = await collection.findOne({ agentId, versionNumber });
+      if (!result) {
+        return null;
+      }
+      return this.transformVersion(result);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "GET_VERSION_BY_NUMBER", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { agentId, versionNumber }
+        },
+        error$1
+      );
+    }
+  }
+  async getLatestVersion(agentId) {
+    try {
+      const collection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+      const result = await collection.find({ agentId }).sort({ versionNumber: -1 }).limit(1).toArray();
+      if (!result || result.length === 0) {
+        return null;
+      }
+      return this.transformVersion(result[0]);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "GET_LATEST_VERSION", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { agentId }
+        },
+        error$1
+      );
+    }
+  }
+  async listVersions(input) {
+    const { agentId, page = 0, perPage: perPageInput, orderBy } = input;
+    if (page < 0) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "LIST_VERSIONS", "INVALID_PAGE"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.USER,
+          details: { page }
+        },
+        new Error("page must be >= 0")
+      );
+    }
+    const perPage = storage.normalizePerPage(perPageInput, 20);
+    const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
+    try {
+      const { field, direction } = this.parseVersionOrderBy(orderBy);
+      const collection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+      const total = await collection.countDocuments({ agentId });
+      if (total === 0 || perPage === 0) {
+        return {
+          versions: [],
+          total,
+          page,
+          perPage: perPageForResponse,
+          hasMore: false
+        };
+      }
+      const sortOrder = direction === "ASC" ? 1 : -1;
+      let cursor = collection.find({ agentId }).sort({ [field]: sortOrder }).skip(offset);
+      if (perPageInput !== false) {
+        cursor = cursor.limit(perPage);
+      }
+      const results = await cursor.toArray();
+      const versions = results.map((doc) => this.transformVersion(doc));
+      return {
+        versions,
+        total,
+        page,
+        perPage: perPageForResponse,
+        hasMore: perPageInput !== false && offset + perPage < total
+      };
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "LIST_VERSIONS", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { agentId }
+        },
+        error$1
+      );
+    }
+  }
+  async deleteVersion(id) {
+    try {
+      const collection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+      await collection.deleteOne({ id });
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "DELETE_VERSION", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { versionId: id }
+        },
+        error$1
+      );
+    }
+  }
+  async deleteVersionsByAgentId(agentId) {
+    try {
+      const collection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+      await collection.deleteMany({ agentId });
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "DELETE_VERSIONS_BY_AGENT_ID", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { agentId }
+        },
+        error$1
+      );
+    }
+  }
+  async countVersions(agentId) {
+    try {
+      const collection = await this.getCollection(storage.TABLE_AGENT_VERSIONS);
+      return await collection.countDocuments({ agentId });
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("MONGODB", "COUNT_VERSIONS", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { agentId }
+        },
+        error$1
+      );
+    }
+  }
+  // ==========================================================================
+  // Private Helper Methods
+  // ==========================================================================
+  transformVersion(doc) {
+    const { _id, ...version } = doc;
+    return {
+      ...version,
+      createdAt: version.createdAt instanceof Date ? version.createdAt : new Date(version.createdAt)
+    };
+  }
 };
 function formatDateForMongoDB(date) {
   return typeof date === "string" ? new Date(date) : date;
@@ -2492,7 +2707,7 @@ Note: This migration may take some time for large collections.
             perPage,
             hasMore: (page + 1) * perPage < count2
           },
-          spans: spans2.map((span) => this.transformSpanFromMongo(span))
+          spans: storage.toTraceSpans(spans2.map((span) => this.transformSpanFromMongo(span)))
         };
       }
       const count = await collection.countDocuments(mongoFilter);
@@ -2535,7 +2750,7 @@ Note: This migration may take some time for large collections.
           perPage,
           hasMore: (page + 1) * perPage < count
         },
-        spans: spans.map((span) => this.transformSpanFromMongo(span))
+        spans: storage.toTraceSpans(spans.map((span) => this.transformSpanFromMongo(span)))
       };
     } catch (error$1) {
       throw new error.MastraError(