chore: update namespace design for data plane

src/cli/commands/dev/browser-mode.ts

@@ -60,26 +60,26 @@ async function resolveDeployedHandlers(
         `Memory browsing enabled for ${memories.length} deployed memory(ies): ${memories.map(m => m.name).join(', ')}`
       );
 
-      result.onListMemoryRecords = async (memoryName, namespace, strategyId) => {
-        const memory = memories.find(m => m.name === memoryName);
-        if (!memory) return { success: false, error: `Memory "${memoryName}" not found in deployed state` };
+      result.onListMemoryRecords = async args => {
+        const memory = memories.find(m => m.name === args.memoryName);
+        if (!memory) return { success: false, error: `Memory "${args.memoryName}" not found in deployed state` };
         return listMemoryRecords({
           region: memory.region,
           memoryId: memory.memoryId,
-          namespace,
-          memoryStrategyId: strategyId,
+          memoryStrategyId: args.strategyId,
+          ...(args.namespace !== undefined ? { namespace: args.namespace } : { namespacePath: args.namespacePath }),
         });
       };
 
-      result.onRetrieveMemoryRecords = async (memoryName, namespace, searchQuery, strategyId) => {
-        const memory = memories.find(m => m.name === memoryName);
-        if (!memory) return { success: false, error: `Memory "${memoryName}" not found in deployed state` };
+      result.onRetrieveMemoryRecords = async args => {
+        const memory = memories.find(m => m.name === args.memoryName);
+        if (!memory) return { success: false, error: `Memory "${args.memoryName}" not found in deployed state` };
         return retrieveMemoryRecords({
           region: memory.region,
           memoryId: memory.memoryId,
-          namespace,
-          searchQuery,
-          memoryStrategyId: strategyId,
+          searchQuery: args.searchQuery,
+          memoryStrategyId: args.strategyId,
+          ...(args.namespace !== undefined ? { namespace: args.namespace } : { namespacePath: args.namespacePath }),
         });
       };
     }
@@ -235,15 +235,15 @@ export async function runBrowserMode(opts: BrowserModeOptions): Promise<void> {
           };
         }
       },
-      onListMemoryRecords: async (memoryName, namespace, strategyId) => {
+      onListMemoryRecords: async args => {
         const deployed = await resolveDeployedHandlers(baseDir, onLog);
         if (!deployed.onListMemoryRecords) return { success: false, error: 'No deployed AgentCore Memory found' };
-        return deployed.onListMemoryRecords(memoryName, namespace, strategyId);
+        return deployed.onListMemoryRecords(args);
       },
-      onRetrieveMemoryRecords: async (memoryName, namespace, searchQuery, strategyId) => {
+      onRetrieveMemoryRecords: async args => {
         const deployed = await resolveDeployedHandlers(baseDir, onLog);
         if (!deployed.onRetrieveMemoryRecords) return { success: false, error: 'No deployed AgentCore Memory found' };
-        return deployed.onRetrieveMemoryRecords(memoryName, namespace, searchQuery, strategyId);
+        return deployed.onRetrieveMemoryRecords(args);
       },
     },
   });

src/cli/operations/agent/import/__tests__/translator.test.ts

@@ -81,6 +81,29 @@ describe('StrandsTranslator', () => {
     expect(result.features.hasMemory).toBe(true);
   });
 
+  it('emits namespace_path (not namespace) in retrieve_memories calls for longAndShortTerm memory', () => {
+    const config = makeSimpleAgentConfig({
+      agent: {
+        ...makeSimpleAgentConfig().agent,
+        memoryConfiguration: { enabledMemoryTypes: ['SESSION_SUMMARY'] },
+      },
+    });
+    const translator = new StrandsTranslator(config, {
+      agentConfig: config,
+      enableMemory: true,
+      memoryOption: 'longAndShortTerm',
+      enableObservability: false,
+    });
+    const result = translator.translate();
+
+    // All three retrieval calls should use the new namespace_path kwarg
+    expect(result.mainPyContent).toContain("namespace_path=f'/users/{user_id}/facts'");
+    expect(result.mainPyContent).toContain("namespace_path=f'/users/{user_id}/preferences'");
+    expect(result.mainPyContent).toContain("namespace_path=f'/summaries/{user_id}/'");
+    // The deprecated kwarg form must not appear for longAndShortTerm retrievals
+    expect(result.mainPyContent).not.toMatch(/retrieve_memories\([^)]*\bnamespace=/);
+  });
+
   it('generates action group tools for function-schema action groups', () => {
     const config = makeSimpleAgentConfig({
       action_groups: [
@@ -221,6 +244,29 @@ describe('LangGraphTranslator', () => {
     expect(result.mainPyContent).toContain('gr-123');
     expect(result.features.hasGuardrails).toBe(true);
   });
+
+  it('emits namespace_path (not namespace) in retrieve_memories calls for longAndShortTerm memory', () => {
+    const config = makeSimpleAgentConfig({
+      agent: {
+        ...makeSimpleAgentConfig().agent,
+        memoryConfiguration: { enabledMemoryTypes: ['SESSION_SUMMARY'] },
+      },
+    });
+    const translator = new LangGraphTranslator(config, {
+      agentConfig: config,
+      enableMemory: true,
+      memoryOption: 'longAndShortTerm',
+      enableObservability: false,
+    });
+    const result = translator.translate();
+
+    // All three retrieval calls should use the new namespace_path kwarg
+    expect(result.mainPyContent).toContain("namespace_path=f'/users/{user_id}/facts'");
+    expect(result.mainPyContent).toContain("namespace_path=f'/users/{user_id}/preferences'");
+    expect(result.mainPyContent).toContain("namespace_path=f'/summaries/{user_id}/'");
+    // The deprecated kwarg form must not appear for longAndShortTerm retrievals
+    expect(result.mainPyContent).not.toMatch(/retrieve_memories\([^)]*\bnamespace=/);
+  });
 });
 
 describe('generatePyprojectToml', () => {

src/cli/operations/agent/import/langgraph-translator.ts

@@ -209,9 +209,9 @@ def invoke_${collabName}(query: str, state: Annotated[dict, InjectedState]) -> s
     const memoryRetrieveCode =
       this.agentcoreMemoryEnabled && this.hasLongTermStrategies
         ? `
-            semantic_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace=f'/users/{user_id}/facts', query="Retrieve relevant facts.", actor_id=user_id, top_k=3)
-            pref_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace=f'/users/{user_id}/preferences', query="Retrieve user preferences.", actor_id=user_id, top_k=3)
-            summary_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace=f'/summaries/{user_id}/', query="Retrieve the most recent session summaries.", actor_id=user_id, top_k=3)
+            semantic_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace_path=f'/users/{user_id}/facts', query="Retrieve relevant facts.", actor_id=user_id, top_k=3)
+            pref_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace_path=f'/users/{user_id}/preferences', query="Retrieve user preferences.", actor_id=user_id, top_k=3)
+            summary_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace_path=f'/summaries/{user_id}/', query="Retrieve the most recent session summaries.", actor_id=user_id, top_k=3)
             all_memories = semantic_memories + pref_memories + summary_memories
             memory_synopsis = "\\n".join([m.get("content", {}).get("text", "") for m in all_memories])`
         : this.memoryEnabled

src/cli/operations/agent/import/strands-translator.ts

@@ -185,9 +185,9 @@ def invoke_${collabName}(query: str) -> str:
     const memoryRetrieveLines =
       this.agentcoreMemoryEnabled && this.hasLongTermStrategies
         ? [
-            '        semantic_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace=f\'/users/{user_id}/facts\', query="Retrieve relevant facts.", actor_id=user_id, top_k=3)',
-            '        pref_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace=f\'/users/{user_id}/preferences\', query="Retrieve user preferences.", actor_id=user_id, top_k=3)',
-            '        summary_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace=f\'/summaries/{user_id}/\', query="Retrieve the most recent session summaries.", actor_id=user_id, top_k=3)',
+            '        semantic_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace_path=f\'/users/{user_id}/facts\', query="Retrieve relevant facts.", actor_id=user_id, top_k=3)',
+            '        pref_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace_path=f\'/users/{user_id}/preferences\', query="Retrieve user preferences.", actor_id=user_id, top_k=3)',
+            '        summary_memories = memory_client.retrieve_memories(memory_id=memory_id, namespace_path=f\'/summaries/{user_id}/\', query="Retrieve the most recent session summaries.", actor_id=user_id, top_k=3)',
             '        all_memories = semantic_memories + pref_memories + summary_memories',
             '        memory_synopsis = "\\n".join([m.get("content", {}).get("text", "") for m in all_memories])',
           ]

src/cli/operations/dev/web-ui/README.md

@@ -209,10 +209,13 @@ Response:
 { "success": true, "spans": [...] }
 ```
 
-### `GET /api/memory?memoryName=xxx&namespace=yyy[&strategyId=zzz]`
+### `GET /api/memory?memoryName=xxx&(namespace=yyy|namespacePath=yyy)[&strategyId=zzz]`
 
 Lists memory records for a given memory and namespace. Requires a deployed memory with `onListMemoryRecords` handler.
 
+Exactly one of `namespace` (exact match) or `namespacePath` (hierarchical path prefix) must be provided. Supplying both
+returns HTTP 400.
+
 Response:
 
 ```json
@@ -223,10 +226,18 @@ Response:
 
 Performs semantic search across memory records. Requires a deployed memory with `onRetrieveMemoryRecords` handler.
 
+Exactly one of `namespace` or `namespacePath` must be provided in the request body.
+
 Request:
 
 ```json
-{ "memoryName": "MyMemory", "namespace": "/users/123/facts", "searchQuery": "preferences", "strategyId": "optional" }
+{ "memoryName": "MyMemory", "namespacePath": "/users/123/", "searchQuery": "preferences", "strategyId": "optional" }
+```
+
+Or with exact-match semantics:
+
+```json
+{ "memoryName": "MyMemory", "namespace": "/users/123/facts", "searchQuery": "preferences" }
 ```
 
 Response: