Update DP APIs to support namespace re-design (#449)

* chore: update DP APIs to support namespace re-design

* fix: deprecate namespace_prefix

---------

Signed-off-by: Nicolas <nickdb@amazon.com>

Author: nborges-aws

src/bedrock_agentcore/_utils/namespace.py

@@ -73,3 +73,37 @@ def resolve_namespace_templates(
         return namespaces
 
     return namespace_templates
+
+
+def resolve_namespace_prefix_deprecation(
+    namespace_prefix: Optional[str] = None,
+    namespace: Optional[str] = None,
+) -> Optional[str]:
+    """Collapse the deprecated ``namespace_prefix`` kwarg into ``namespace``.
+
+    Used by high-level session-manager retrieval helpers that historically took a
+    ``namespace_prefix`` parameter. During the service redesign's grace period,
+    ``namespace`` preserves the pre-redesign string-prefix behavior, so migrating
+    ``namespace_prefix`` callers to ``namespace`` keeps results identical until
+    allowlisting is removed.
+
+    Returns the effective ``namespace`` value (or ``None`` if neither was provided
+    and the caller supplied ``namespace_path`` instead). When ``namespace_prefix``
+    is used, emits a ``DeprecationWarning``.
+
+    Raises:
+        ValueError: if both ``namespace_prefix`` and ``namespace`` are provided.
+    """
+    if namespace_prefix is not None and namespace is not None:
+        raise ValueError("'namespace' and 'namespace_prefix' (deprecated) are mutually exclusive.")
+    if namespace_prefix is not None:
+        warnings.warn(
+            "The 'namespace_prefix' parameter is deprecated and will be removed in a future "
+            "release. Use 'namespace' for exact-match retrieval (current pre-redesign behavior "
+            "during the service grace period) or 'namespace_path' for hierarchical path-prefix "
+            "retrieval.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return namespace_prefix
+    return namespace

src/bedrock_agentcore/memory/README.md

@@ -186,14 +186,14 @@ session.add_turns([
 # Search long-term memories (after memory extraction has occurred)
 memories = session.search_long_term_memories(
     query="what food does the user like",
-    namespace_prefix="/food/user-123/",
+    namespace_path="/food/user-123/",
     top_k=5
 )
 
 # Or search across multiple users
 memories = manager.search_long_term_memories(
     query="Food preferences",
-    namespace_prefix="/food/",  # Search all food-related memories
+    namespace_path="/food/",  # Search all food-related memories
     top_k=10
 )
 ```
@@ -301,7 +301,7 @@ session2 = manager.create_memory_session(
 ```python
 # List all memory records in a namespace
 records = session.list_long_term_memory_records(
-    namespace_prefix="/user/preferences/user-123/",
+    namespace_path="/user/preferences/user-123/",
     max_results=20
 )
 
@@ -327,7 +327,7 @@ Learn more here!: [Working example](metadata-workflow.ipynb)
 # Step 1: Retrieve relevant memories
 memories = session.search_long_term_memories(
     query="previous discussion",
-    namespace_prefix="support/facts/session-456/",
+    namespace_path="support/facts/session-456/",
     top_k=5
 )
 

src/bedrock_agentcore/memory/client.py

@@ -20,7 +20,7 @@
 from botocore.config import Config
 from botocore.exceptions import ClientError
 
-from bedrock_agentcore._utils.namespace import resolve_namespace_templates
+from bedrock_agentcore._utils.namespace import build_namespace_params, resolve_namespace_templates
 from bedrock_agentcore._utils.snake_case import accept_snake_case_kwargs
 from bedrock_agentcore._utils.user_agent import build_user_agent_suffix
 
@@ -127,8 +127,11 @@ def __getattr__(self, name: str):
             # Access any boto3 method directly
             client = MemoryClient()
 
-            # These calls are forwarded to the appropriate boto3 client
-            response = client.list_memory_records(memoryId="mem-123", namespace="test/")
+            # These calls are forwarded to the appropriate boto3 client.
+            # Use `namespace` for exact match, or `namespace_path` for
+            # hierarchical path-prefix retrieval.
+            response = client.list_memory_records(memoryId="mem-123", namespace="/actor/Jane/")
+            response = client.list_memory_records(memoryId="mem-123", namespace_path="/org/MyOrg/")
             metadata = client.get_memory_metadata(memoryId="mem-123")
         """
         if name in self._ALLOWED_GMDP_METHODS and hasattr(self.gmdp_client, name):
@@ -308,46 +311,48 @@ def create_memory_and_wait(
         raise TimeoutError("Memory %s did not become ACTIVE within %d seconds" % (memory_id, max_wait))
 
     def retrieve_memories(
-        self, memory_id: str, namespace: str, query: str, actor_id: Optional[str] = None, top_k: int = 3
+        self,
+        memory_id: str,
+        namespace: Optional[str] = None,
+        query: str = None,
+        actor_id: Optional[str] = None,
+        top_k: int = 3,
+        namespace_path: Optional[str] = None,
     ) -> List[Dict[str, Any]]:
-        """Retrieve relevant memories from a namespace.
+        """Retrieve relevant memories using exact match or hierarchical path prefix.
 
-        Note: Wildcards (*) are NOT supported in namespaces. You must provide the
-        exact namespace path with all variables resolved.
+        Exactly one of ``namespace`` or ``namespace_path`` must be provided.
 
         Args:
             memory_id: Memory resource ID
-            namespace: Exact namespace path (no wildcards)
-            query: Search query
+            namespace: Exact namespace to match (e.g., "/actor/Jane/")
+            query: Search query (required)
             actor_id: Optional actor ID (deprecated, use namespace)
             top_k: Number of results to return
+            namespace_path: Hierarchical path prefix (e.g., "/org/team/")
 
         Returns:
-            List of memory records
-
-        Example:
-            # Correct - exact namespace
-            memories = client.retrieve_memories(
-                memory_id="mem-123",
-                namespace="support/facts/session-456/",
-                query="customer preferences"
-            )
-
-            # Incorrect - wildcards not supported
-            # memories = client.retrieve_memories(..., namespace="support/facts/*/", ...)
+            List of memory records. Returns an empty list if the namespace
+            arguments are invalid (both provided, neither provided, or contain
+            wildcards) or if the service call fails.
         """
-        if "*" in namespace:
-            logger.error("Wildcards are not supported in namespaces. Please provide exact namespace.")
+        if query is None:
+            raise TypeError("retrieve_memories() missing required argument: 'query'")
+
+        try:
+            ns_params = build_namespace_params(namespace, namespace_path)
+        except ValueError as e:
+            logger.error(str(e))
             return []
 
+        ns_value = namespace or namespace_path
+
         try:
-            # Let service handle all namespace validation
             response = self.gmdp_client.retrieve_memory_records(
-                memoryId=memory_id, namespace=namespace, searchCriteria={"searchQuery": query, "topK": top_k}
+                memoryId=memory_id, searchCriteria={"searchQuery": query, "topK": top_k}, **ns_params
             )
-
             memories = response.get("memoryRecordSummaries", [])
-            logger.info("Retrieved %d memories from namespace: %s", len(memories), namespace)
+            logger.info("Retrieved %d memories from namespace: %s", len(memories), ns_value)
             return memories
 
         except ClientError as e:
@@ -358,7 +363,7 @@ def retrieve_memories(
                 logger.warning(
                     "Memory or namespace not found. Ensure memory %s exists and namespace '%s' is configured",
                     memory_id,
-                    namespace,
+                    ns_value,
                 )
             elif error_code == "ValidationException":
                 logger.warning("Invalid search parameters: %s", error_msg)
@@ -663,6 +668,7 @@ def process_turn_with_llm(
         retrieval_query: Optional[str] = None,
         top_k: int = 3,
         event_timestamp: Optional[datetime] = None,
+        retrieval_namespace_path: Optional[str] = None,
     ) -> Tuple[List[Dict[str, Any]], str, Dict[str, Any]]:
         r"""Complete conversation turn with LLM callback integration.
 
@@ -677,10 +683,11 @@ def process_turn_with_llm(
             llm_callback: Function that takes (user_input, memories) and returns agent_response
                          The callback receives the user input and retrieved memories,
                          and should return the agent's response string
-            retrieval_namespace: Namespace to search for memories (optional)
+            retrieval_namespace: Namespace for exact match retrieval (optional)
             retrieval_query: Custom search query (defaults to user_input)
             top_k: Number of memories to retrieve
             event_timestamp: Optional timestamp for the event
+            retrieval_namespace_path: Namespace path for hierarchical prefix retrieval (optional)
 
         Returns:
             Tuple of (retrieved_memories, agent_response, created_event)
@@ -710,10 +717,14 @@ def my_llm(user_input: str, memories: List[Dict]) -> str:
         """
         # Step 1: Retrieve relevant memories
         retrieved_memories = []
-        if retrieval_namespace:
+        if retrieval_namespace or retrieval_namespace_path:
             search_query = retrieval_query or user_input
             retrieved_memories = self.retrieve_memories(
-                memory_id=memory_id, namespace=retrieval_namespace, query=search_query, top_k=top_k
+                memory_id=memory_id,
+                namespace=retrieval_namespace,
+                namespace_path=retrieval_namespace_path,
+                query=search_query,
+                top_k=top_k,
             )
             logger.info("Retrieved %d memories for LLM context", len(retrieved_memories))
 

src/bedrock_agentcore/memory/integrations/strands/session_manager.py

@@ -854,7 +854,7 @@ def retrieve_for_namespace(namespace: str, retrieval_config: RetrievalConfig):
 
             memories = self.memory_client.retrieve_memories(
                 memory_id=self.config.memory_id,
-                namespace=resolved_namespace,
+                namespace_path=resolved_namespace,
                 query=user_query,
                 top_k=retrieval_config.top_k,
             )

src/bedrock_agentcore/memory/session.py

@@ -10,6 +10,7 @@
 from botocore.config import Config as BotocoreConfig
 from botocore.exceptions import ClientError
 
+from bedrock_agentcore._utils.namespace import build_namespace_params, resolve_namespace_prefix_deprecation
 from bedrock_agentcore._utils.snake_case import accept_snake_case_kwargs
 
 from .constants import BlobMessage, ConversationalMessage, MessageRole, RetrievalConfig
@@ -398,8 +399,9 @@ def _retrieve_memories_for_llm(
                     strategyId=config.strategy_id or "",
                 )
                 search_query = f"{config.retrieval_query} {user_input}" if config.retrieval_query else user_input
+                # TODO: revisit after full deprecation of namespace fields
                 memory_records = self.search_long_term_memories(
-                    query=search_query, namespace_prefix=resolved_namespace, top_k=config.top_k
+                    query=search_query, namespace=resolved_namespace, top_k=config.top_k
                 )
                 # Filter memory records with a relevance score which is lower than config.relevance_score
                 if config.relevance_score:
@@ -895,26 +897,45 @@ def delete_event(self, actor_id: str, session_id: str, event_id: str):
     def search_long_term_memories(
         self,
         query: str,
-        namespace_prefix: str,
+        namespace_prefix: Optional[str] = None,
         top_k: int = 3,
         strategy_id: str = None,
         max_results: int = 20,
+        namespace: Optional[str] = None,
+        namespace_path: Optional[str] = None,
     ) -> List[MemoryRecord]:
         """Performs a semantic search against the long-term memory for this actor.
 
         Maps to: bedrock-agentcore.retrieve_memory_records.
+
+        Exactly one of ``namespace`` (exact match), ``namespace_path`` (hierarchical
+        path prefix), or ``namespace_prefix`` (DEPRECATED alias for ``namespace``)
+        must be provided.
+
+        Args:
+            query: Search query
+            namespace_prefix: DEPRECATED. Use ``namespace`` or ``namespace_path`` instead.
+            top_k: Number of top-scoring records to return
+            strategy_id: Optional strategy filter
+            max_results: Maximum records to return
+            namespace: Exact-match namespace (preserves pre-redesign behavior during the
+                service grace period)
+            namespace_path: Hierarchical path-prefix namespace
         """
-        logger.info("  -> Querying long-term memory in namespace '%s' with query: '%s'...", namespace_prefix, query)
+        resolved_namespace = resolve_namespace_prefix_deprecation(namespace_prefix, namespace)
+        ns_params = build_namespace_params(resolved_namespace, namespace_path)
+        ns_value = resolved_namespace or namespace_path
+
+        logger.info("  -> Querying long-term memory in namespace '%s' with query: '%s'...", ns_value, query)
         search_criteria = {"searchQuery": query, "topK": top_k}
         if strategy_id:
             search_criteria["memoryStrategyId"] = strategy_id
 
-        namespace = namespace_prefix
         params = {
             "memoryId": self._memory_id,
             "searchCriteria": search_criteria,
-            "namespace": namespace,
             "maxResults": max_results,
+            **ns_params,
         }
 
         try:
@@ -927,20 +948,41 @@ def search_long_term_memories(
             raise
 
     def list_long_term_memory_records(
-        self, namespace_prefix: str, strategy_id: Optional[str] = None, max_results: int = 10
+        self,
+        namespace_prefix: Optional[str] = None,
+        strategy_id: Optional[str] = None,
+        max_results: int = 10,
+        namespace: Optional[str] = None,
+        namespace_path: Optional[str] = None,
     ) -> List[MemoryRecord]:
         """Lists all long-term memory records for this actor without a semantic query.
 
         Maps to: bedrock-agentcore.list_memory_records.
+
+        Exactly one of ``namespace`` (exact match), ``namespace_path`` (hierarchical
+        path prefix), or ``namespace_prefix`` (DEPRECATED alias for ``namespace``)
+        must be provided.
+
+        Args:
+            namespace_prefix: DEPRECATED. Use ``namespace`` or ``namespace_path`` instead.
+            strategy_id: Optional strategy filter
+            max_results: Maximum records to return
+            namespace: Exact-match namespace (preserves pre-redesign behavior during the
+                service grace period)
+            namespace_path: Hierarchical path-prefix namespace
         """
-        logger.info("  -> Listing all long-term records in namespace '%s'...", namespace_prefix)
+        resolved_namespace = resolve_namespace_prefix_deprecation(namespace_prefix, namespace)
+        ns_params = build_namespace_params(resolved_namespace, namespace_path)
+        ns_value = resolved_namespace or namespace_path
+
+        logger.info("  -> Listing all long-term records in namespace '%s'...", ns_value)
 
         try:
             paginator = self._data_plane_client.get_paginator("list_memory_records")
 
             params = {
                 "memoryId": self._memory_id,
-                "namespace": namespace_prefix,
+                **ns_params,
             }
 
             if strategy_id:
@@ -1049,7 +1091,8 @@ def delete_all_long_term_memories_in_namespace(self, namespace: str) -> Dict[str
         logger.info("🗑️ Deleting all long-term memories in namespace '%s'...", namespace)
 
         # Retrieve all memory records in the specified namespace
-        memory_records = self.list_long_term_memory_records(namespace_prefix=namespace)
+        # TODO: revisit after full deprecation of namespace fields
+        memory_records = self.list_long_term_memory_records(namespace=namespace)
         logger.info("  -> Found %d memory records to delete", len(memory_records))
 
         if not memory_records:
@@ -1203,19 +1246,40 @@ def delete_memory_record(self, record_id: str):
     def search_long_term_memories(
         self,
         query: str,
-        namespace_prefix: str,
+        namespace_prefix: Optional[str] = None,
         top_k: int = 3,
         strategy_id: Optional[str] = None,
         max_results: int = 20,
+        namespace: Optional[str] = None,
+        namespace_path: Optional[str] = None,
     ) -> List[MemoryRecord]:
         """Delegates to manager.search_long_term_memories."""
-        return self._manager.search_long_term_memories(query, namespace_prefix, top_k, strategy_id, max_results)
+        return self._manager.search_long_term_memories(
+            query,
+            namespace_prefix,
+            top_k,
+            strategy_id,
+            max_results,
+            namespace=namespace,
+            namespace_path=namespace_path,
+        )
 
     def list_long_term_memory_records(
-        self, namespace_prefix: str, strategy_id: Optional[str] = None, max_results: int = 10
+        self,
+        namespace_prefix: Optional[str] = None,
+        strategy_id: Optional[str] = None,
+        max_results: int = 10,
+        namespace: Optional[str] = None,
+        namespace_path: Optional[str] = None,
     ) -> List[MemoryRecord]:
         """Delegates to manager.list_long_term_memory_records."""
-        return self._manager.list_long_term_memory_records(namespace_prefix, strategy_id, max_results)
+        return self._manager.list_long_term_memory_records(
+            namespace_prefix,
+            strategy_id,
+            max_results,
+            namespace=namespace,
+            namespace_path=namespace_path,
+        )
 
     def list_actors(self) -> List[ActorSummary]:
         """Delegates to manager.list_actors."""