feat(memory): make agentId optional for read operations (#11540)

## Description

feat(memory): make agentId optional for read operations

## Related Issue(s)

fixes #10867

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a method to list messages within a thread with selectable memory
source (agent, network, or storage).

* **Improvements**
* agentId is now optional for memory read/delete operations; omitting it
falls back to server storage so threads/messages can be accessed without
a specific agent.
* Server now supports storage-backed retrieval when no agent is
provided.

* **Documentation**
* Updated memory API docs to describe optional agentId and storage
fallback behavior.

* **Tests**
* Expanded coverage for thread/message ops and storage-fallback
scenarios.

* **Chore**
  * Added changelog entry updating client/server versions.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: roaminro

.changeset/witty-plums-pull.md

@@ -0,0 +1,8 @@
+---
+'@mastra/client-js': patch
+'@mastra/server': patch
+---
+
+Make agentId optional for memory read operations (getThread, listThreads, listMessages)
+
+When workflows use multiple agents sharing the same threadId/resourceId, users can now retrieve threads and messages without specifying an agentId. The server falls back to using storage directly when agentId is not provided.

client-sdks/client-js/src/client.test.ts

@@ -321,4 +321,140 @@ describe('MastraClient', () => {
       });
     });
   });
+
+  describe('Memory Thread Operations without agentId', () => {
+    describe('listMemoryThreads', () => {
+      it('should list threads with agentId', async () => {
+        const mockThreads = {
+          threads: [{ id: 'thread-1', title: 'Test' }],
+        };
+        (global.fetch as any).mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          headers: { get: () => 'application/json' },
+          json: async () => mockThreads,
+        });
+
+        const result = await client.listMemoryThreads({
+          agentId: 'agent-1',
+          resourceId: 'resource-1',
+        });
+
+        // Note: URL includes both resourceId and resourceid (lowercase) for backwards compatibility
+        expect(global.fetch).toHaveBeenCalledWith(expect.stringContaining('/api/memory/threads?'), expect.any(Object));
+        expect(global.fetch).toHaveBeenCalledWith(expect.stringContaining('agentId=agent-1'), expect.any(Object));
+        expect(result).toEqual(mockThreads);
+      });
+
+      it('should list threads without agentId (storage fallback)', async () => {
+        const mockThreads = {
+          threads: [{ id: 'thread-1', title: 'Test' }],
+        };
+        (global.fetch as any).mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          headers: { get: () => 'application/json' },
+          json: async () => mockThreads,
+        });
+
+        const result = await client.listMemoryThreads({
+          resourceId: 'resource-1',
+        });
+
+        // URL should NOT include agentId when not provided
+        const fetchCall = (global.fetch as any).mock.calls[0][0];
+        expect(fetchCall).toContain('/api/memory/threads?');
+        expect(fetchCall).toContain('resourceId=resource-1');
+        expect(fetchCall).not.toContain('agentId=');
+        expect(result).toEqual(mockThreads);
+      });
+    });
+
+    describe('getMemoryThread', () => {
+      it('should get thread with agentId', async () => {
+        const mockThread = { id: 'thread-1', title: 'Test' };
+        (global.fetch as any).mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          headers: { get: () => 'application/json' },
+          json: async () => mockThread,
+        });
+
+        const thread = client.getMemoryThread({
+          agentId: 'agent-1',
+          threadId: 'thread-1',
+        });
+        await thread.get();
+
+        expect(global.fetch).toHaveBeenCalledWith(
+          'http://localhost:4111/api/memory/threads/thread-1?agentId=agent-1',
+          expect.any(Object),
+        );
+      });
+
+      it('should get thread without agentId (storage fallback)', async () => {
+        const mockThread = { id: 'thread-1', title: 'Test' };
+        (global.fetch as any).mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          headers: { get: () => 'application/json' },
+          json: async () => mockThread,
+        });
+
+        const thread = client.getMemoryThread({
+          threadId: 'thread-1',
+        });
+        await thread.get();
+
+        expect(global.fetch).toHaveBeenCalledWith(
+          'http://localhost:4111/api/memory/threads/thread-1',
+          expect.any(Object),
+        );
+      });
+    });
+
+    describe('listThreadMessages', () => {
+      it('should list messages with agentId', async () => {
+        const mockMessages = {
+          messages: [{ id: 'msg-1', content: 'Hello' }],
+        };
+        (global.fetch as any).mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          headers: { get: () => 'application/json' },
+          json: async () => mockMessages,
+        });
+
+        const result = await client.listThreadMessages('thread-1', {
+          agentId: 'agent-1',
+        });
+
+        expect(global.fetch).toHaveBeenCalledWith(
+          'http://localhost:4111/api/memory/threads/thread-1/messages?agentId=agent-1',
+          expect.any(Object),
+        );
+        expect(result).toEqual(mockMessages);
+      });
+
+      it('should list messages without agentId (storage fallback)', async () => {
+        const mockMessages = {
+          messages: [{ id: 'msg-1', content: 'Hello' }],
+        };
+        (global.fetch as any).mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          headers: { get: () => 'application/json' },
+          json: async () => mockMessages,
+        });
+
+        const result = await client.listThreadMessages('thread-1');
+
+        expect(global.fetch).toHaveBeenCalledWith(
+          'http://localhost:4111/api/memory/threads/thread-1/messages',
+          expect.any(Object),
+        );
+        expect(result).toEqual(mockMessages);
+      });
+    });
+  });
 });

client-sdks/client-js/src/client.ts

@@ -111,7 +111,7 @@ export class MastraClient extends BaseResource {
     const queryParams = new URLSearchParams({
       resourceId: params.resourceId,
       resourceid: params.resourceId,
-      agentId: params.agentId,
+      ...(params.agentId && { agentId: params.agentId }),
       ...(params.page !== undefined && { page: params.page.toString() }),
       ...(params.perPage !== undefined && { perPage: params.perPage.toString() }),
       ...(params.orderBy && { orderBy: params.orderBy }),
@@ -162,24 +162,33 @@ export class MastraClient extends BaseResource {
   /**
    * Gets a memory thread instance by ID
    * @param threadId - ID of the memory thread to retrieve
+   * @param agentId - Optional agent ID. When not provided, uses storage directly
    * @returns MemoryThread instance
    */
-  public getMemoryThread({ threadId, agentId }: { threadId: string; agentId: string }) {
+  public getMemoryThread({ threadId, agentId }: { threadId: string; agentId?: string }) {
     return new MemoryThread(this.options, threadId, agentId);
   }
 
+  /**
+   * Lists messages for a thread.
+   * @param threadId - ID of the thread
+   * @param opts - Optional parameters including agentId, networkId, and requestContext
+   *   - When agentId is provided, uses the agent's memory
+   *   - When networkId is provided, uses the network endpoint
+   *   - When neither is provided, uses storage directly
+   * @returns Promise containing the thread messages
+   */
   public listThreadMessages(
     threadId: string,
     opts: { agentId?: string; networkId?: string; requestContext?: RequestContext | Record<string, any> } = {},
   ): Promise<ListMemoryThreadMessagesResponse> {
-    if (!opts.agentId && !opts.networkId) {
-      throw new Error('Either agentId or networkId must be provided');
-    }
     let url = '';
-    if (opts.agentId) {
-      url = `/api/memory/threads/${threadId}/messages?agentId=${opts.agentId}${requestContextQueryString(opts.requestContext, '&')}`;
-    } else if (opts.networkId) {
+    if (opts.networkId) {
       url = `/api/memory/network/threads/${threadId}/messages?networkId=${opts.networkId}${requestContextQueryString(opts.requestContext, '&')}`;
+    } else if (opts.agentId) {
+      url = `/api/memory/threads/${threadId}/messages?agentId=${opts.agentId}${requestContextQueryString(opts.requestContext, '&')}`;
+    } else {
+      url = `/api/memory/threads/${threadId}/messages${requestContextQueryString(opts.requestContext, '?')}`;
     }
     return this.request(url);
   }

client-sdks/client-js/src/resources/memory-thread.test.ts

@@ -282,4 +282,173 @@ describe('MemoryThread', () => {
       await expect(thread.deleteMessages(messageIds)).rejects.toThrow();
     });
   });
+
+  describe('without agentId (storage fallback)', () => {
+    let threadWithoutAgent: MemoryThread;
+
+    beforeEach(() => {
+      vi.clearAllMocks();
+      // Create MemoryThread without agentId - uses storage fallback on server
+      threadWithoutAgent = new MemoryThread(clientOptions, threadId);
+    });
+
+    it('should retrieve thread details without agentId in URL', async () => {
+      const mockThread = {
+        id: threadId,
+        title: 'Test Thread',
+        metadata: { test: true },
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+
+      mockFetchResponse(mockThread);
+
+      const result = await threadWithoutAgent.get();
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `http://localhost:4111/api/memory/threads/${threadId}`,
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: 'Bearer test-key',
+          }),
+        }),
+      );
+      expect(result).toEqual(mockThread);
+    });
+
+    it('should retrieve thread messages without agentId in URL', async () => {
+      const mockMessages = {
+        messages: [
+          { id: 'msg-1', content: 'Hello', role: 'user' },
+          { id: 'msg-2', content: 'Hi there', role: 'assistant' },
+        ],
+        uiMessages: [
+          { id: 'msg-1', content: 'Hello', role: 'user' },
+          { id: 'msg-2', content: 'Hi there', role: 'assistant' },
+        ],
+      };
+
+      mockFetchResponse(mockMessages);
+
+      const result = await threadWithoutAgent.listMessages();
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `http://localhost:4111/api/memory/threads/${threadId}/messages`,
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: 'Bearer test-key',
+          }),
+        }),
+      );
+      expect(result).toEqual(mockMessages);
+    });
+
+    it('should update thread without agentId in URL', async () => {
+      const updateParams = {
+        title: 'Updated Title',
+        metadata: { updated: true },
+        resourceId: 'resource-1',
+      };
+
+      const mockUpdatedThread = {
+        id: threadId,
+        title: updateParams.title,
+        metadata: updateParams.metadata,
+        resourceId: updateParams.resourceId,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+
+      mockFetchResponse(mockUpdatedThread);
+
+      const result = await threadWithoutAgent.update(updateParams);
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `http://localhost:4111/api/memory/threads/${threadId}`,
+        expect.objectContaining({
+          method: 'PATCH',
+          headers: expect.objectContaining({
+            Authorization: 'Bearer test-key',
+          }),
+          body: JSON.stringify(updateParams),
+        }),
+      );
+      expect(result).toEqual(mockUpdatedThread);
+    });
+
+    it('should delete thread without agentId in URL', async () => {
+      const mockResponse = { result: 'Thread deleted' };
+
+      mockFetchResponse(mockResponse);
+
+      const result = await threadWithoutAgent.delete();
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `http://localhost:4111/api/memory/threads/${threadId}`,
+        expect.objectContaining({
+          method: 'DELETE',
+          headers: expect.objectContaining({
+            Authorization: 'Bearer test-key',
+          }),
+        }),
+      );
+      expect(result).toEqual(mockResponse);
+    });
+
+    it('should clone thread without agentId in URL', async () => {
+      const cloneParams = {
+        newThreadId: 'cloned-thread-id',
+        newTitle: 'Cloned Thread',
+        newMetadata: { cloned: true },
+      };
+
+      const mockCloneResponse = {
+        thread: {
+          id: cloneParams.newThreadId,
+          title: cloneParams.newTitle,
+          metadata: cloneParams.newMetadata,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        },
+        messages: [{ id: 'cloned-msg-1', content: 'Hello', role: 'user' }],
+      };
+
+      mockFetchResponse(mockCloneResponse);
+
+      const result = await threadWithoutAgent.clone(cloneParams);
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `http://localhost:4111/api/memory/threads/${threadId}/clone`,
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({
+            Authorization: 'Bearer test-key',
+          }),
+          body: JSON.stringify(cloneParams),
+        }),
+      );
+      expect(result).toEqual(mockCloneResponse);
+    });
+
+    it('should delete messages without agentId in URL', async () => {
+      const messageIds = ['msg-1', 'msg-2'];
+      const mockResponse = { success: true, message: '2 messages deleted successfully' };
+
+      mockFetchResponse(mockResponse);
+
+      const result = await threadWithoutAgent.deleteMessages(messageIds);
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        `http://localhost:4111/api/memory/messages/delete`,
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({
+            Authorization: 'Bearer test-key',
+          }),
+          body: JSON.stringify({ messageIds }),
+        }),
+      );
+      expect(result).toEqual(mockResponse);
+    });
+  });
 });