Merge branch 'develop' into fk/oci-langchain-nemotron

Author: fede-kamel

docs/source/build-workflows/memory.md

@@ -24,7 +24,7 @@ The memory module is designed to be extensible, allowing developers to create cu
 ## Included Memory Modules
 The NeMo Agent Toolkit includes four memory module providers, all of which are available as plugins:
 * [Mem0](https://mem0.ai/) which is provided by the [`nvidia-nat-mem0ai`](https://pypi.org/project/nvidia-nat-mem0ai/) plugin.
-* [MemMachine](https://memmachine.ai/) which is provided by the [`nvidia-nat-memmachine`](https://pypi.org/project/nvidia-nat-memmachine/) plugin.
+* [MemMachine](https://memmachine.ai/) which is provided by the [`nvidia-nat-memmachine`](https://pypi.org/project/nvidia-nat-memmachine/) plugin (**Experimental; not recommended for production use**).
 * [Redis](https://redis.io/) which is provided by the [`nvidia-nat-redis`](https://pypi.org/project/nvidia-nat-redis/) plugin.
 * [Zep](https://www.getzep.com/) which is provided by the [`nvidia-nat-zep-cloud`](https://pypi.org/project/nvidia-nat-zep-cloud/) plugin ([Zep NVIDIA NeMo documentation](https://help.getzep.com/nvidia-nemo)).
 

docs/source/build-workflows/workflow-configuration.md

@@ -112,7 +112,7 @@ This section contains the evaluation settings for the workflow. Refer to [Evalua
 
 ### `memory`
 
-This section configures long-term memory backends such as [Mem0](https://mem0.ai/) or [MemMachine](https://memmachine.ai/). It follows the same format as the `llms` section. Refer to the [Memory Module](./memory.md) document for supported providers and examples.
+This section configures long-term memory backends such as [Mem0](https://mem0.ai/) or [MemMachine](https://memmachine.ai/) (note: MemMachine is experimental and is not recommended for production use). It follows the same format as the `llms` section. Refer to the [Memory Module](./memory.md) document for supported providers and examples.
 
 ### `retrievers`
 

docs/source/components/agents/auto-memory-wrapper/auto-memory-wrapper.md

@@ -25,7 +25,7 @@ The automatic memory wrapper agent works with any memory backend that implements
 
 - [`nvidia-nat-zep-cloud`](https://pypi.org/project/nvidia-nat-zep-cloud/) - Zep Cloud memory backend ([Zep NVIDIA NeMo documentation](https://help.getzep.com/nvidia-nemo))
 - [`nvidia-nat-mem0ai`](https://pypi.org/project/nvidia-nat-mem0ai/) - Mem0 memory backend
-- [`nvidia-nat-memmachine`](https://pypi.org/project/nvidia-nat-memmachine/) - MemMachine memory backend ([MemMachine documentation](https://docs.memmachine.ai/))
+- [`nvidia-nat-memmachine`](https://pypi.org/project/nvidia-nat-memmachine/) - MemMachine memory backend (**Experimental; not recommended for production use**) ([MemMachine documentation](https://docs.memmachine.ai/))
 - [`nvidia-nat-redis`](https://pypi.org/project/nvidia-nat-redis/) - Redis memory backend
 
 ## Configuration

docs/source/get-started/installation.md

@@ -45,7 +45,7 @@ To install these first-party plugin libraries, you can use the full distribution
 - `nvidia-nat[llama-index]` or `nvidia-nat-llama-index` - [LlamaIndex](https://www.llamaindex.ai/)
 - `nvidia-nat[mcp]` or `nvidia-nat-mcp` - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
 - `nvidia-nat[mem0ai]` or `nvidia-nat-mem0ai` - [Mem0](https://mem0.ai/)
-- `nvidia-nat[memmachine]` or `nvidia-nat-memmachine` - [MemMachine](https://memmachine.ai/)
+- `nvidia-nat[memmachine]` or `nvidia-nat-memmachine` - [MemMachine](https://memmachine.ai/) (**Experimental; not recommended for production use**)
 - `nvidia-nat[mysql]` or `nvidia-nat-mysql` - [MySQL](https://www.mysql.com/)
 - `nvidia-nat[config-optimizer]` or `nvidia-nat-config-optimizer` - Parameter and prompt optimizer (required for `nat optimize`)
 - `nvidia-nat[openpipe-art]` or `nvidia-nat-openpipe-art` - [Agent Reinforcement Trainer](https://art.openpipe.ai/getting-started/about) Conflicts with `nvidia-nat[adk]` and `nvidia-nat[crewai]`.

packages/nvidia_nat_memmachine/README.md

@@ -19,6 +19,9 @@ limitations under the License.
 
 This package provides integration with MemMachine for memory management in NeMo Agent toolkit.
 
+> [!WARNING]
+> **Experimental**: The `nvidia-nat-memmachine` plugin is Experimental and is not recommended for production use. Behavior may change without notice.
+
 ## Overview
 
 MemMachine is a unified memory management system that supports both episodic and semantic memory through a single interface. This integration allows you to use MemMachine as a memory backend for your NeMo Agent toolkit workflows.

packages/nvidia_nat_memmachine/pyproject.toml

@@ -40,6 +40,7 @@ license = { text = "Apache-2.0" }
 authors = [{ name = "NVIDIA Corporation" }]
 maintainers = [{ name = "NVIDIA Corporation" }]
 classifiers = [
+  "Development Status :: 3 - Alpha",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",

packages/nvidia_nat_memmachine/src/nat/meta/pypi.md

@@ -20,5 +20,8 @@ limitations under the License.
 # NVIDIA NeMo Agent toolkit Subpackage
 This is a subpackage for MemMachine memory integration in NeMo Agent toolkit.
 
+> [!WARNING]
+> **Experimental**: The `nvidia-nat-memmachine` plugin is Experimental and is not recommended for production use. Behavior may change without notice.
+
 For more information about the NVIDIA NeMo Agent toolkit, please visit the [NeMo Agent toolkit GitHub Repo](https://github.com/NVIDIA/NeMo-Agent-Toolkit).
 

packages/nvidia_nat_memmachine/src/nat/plugins/memmachine/memmachine_editor.py

@@ -111,11 +111,14 @@ async def add_items(self, items: list[MemoryItem]) -> None:
         Each MemoryItem is translated and uploaded through the MemMachine API.
 
         All memories are added to both episodic and semantic memory types.
+
+        Conversation messages within a single MemoryItem are added sequentially to
+        preserve chronological order. Separate MemoryItems (and non-conversation
+        memories) are still dispatched concurrently via asyncio.gather.
         """
-        # Run synchronous operations in thread pool to make them async
-        tasks = []
 
-        for memory_item in items:
+        async def add_item(memory_item: MemoryItem) -> None:
+            """Upload a single MemoryItem, adding conversation messages sequentially."""
             # Make a copy of metadata to avoid modifying the original
             item_meta = memory_item.metadata.copy() if memory_item.metadata else {}
             conversation = memory_item.conversation
@@ -139,7 +142,9 @@ async def add_items(self, items: list[MemoryItem]) -> None:
             # If we have a conversation, add each message separately
             # Otherwise, use memory_text or skip if no content
             if conversation:
-                # Add each message in the conversation with its role
+                # Add each message sequentially to preserve conversation order.
+                # asyncio.to_thread tasks dispatched via gather() complete in
+                # nondeterministic order, so we await each one before the next.
                 for msg in conversation:
                     msg_role = msg.get('role', 'user')
                     msg_content = msg.get('content', '')
@@ -154,7 +159,6 @@ async def add_items(self, items: list[MemoryItem]) -> None:
                         # Convert list to comma-separated string
                         metadata["tags"] = ", ".join(tags) if isinstance(tags, list) else str(tags)
 
-                    # Capture variables in closure to avoid late binding issues
                     def add_memory(
                         content=msg_content,
                         role=msg_role,
@@ -173,8 +177,7 @@ def add_memory(
                             episode_type=None  # Use default (MESSAGE)
                         )
 
-                    task = asyncio.to_thread(add_memory)
-                    tasks.append(task)
+                    await asyncio.to_thread(add_memory)
             elif memory_text:
                 # Add as a single memory item (direct memory without conversation)
                 # Add tags to metadata if present
@@ -195,11 +198,10 @@ def add_memory(content=memory_text, mem=memory, meta=metadata, mem_types=memory_
                         episode_type=None  # Use default (MESSAGE)
                     )
 
-                task = asyncio.to_thread(add_memory)
-                tasks.append(task)
+                await asyncio.to_thread(add_memory)
 
-        if tasks:
-            await asyncio.gather(*tasks)
+        if items:
+            await asyncio.gather(*(add_item(item) for item in items))
 
     async def search(self, query: str, top_k: int = 5, **kwargs) -> list[MemoryItem]:
         """

packages/nvidia_nat_memmachine/src/nat/plugins/memmachine/memory.py

@@ -20,6 +20,7 @@
 from nat.cli.register_workflow import register_memory
 from nat.data_models.memory import MemoryBaseConfig
 from nat.data_models.retry_mixin import RetryMixin
+from nat.experimental.decorators.experimental_warning_decorator import experimental
 from nat.memory.interfaces import MemoryEditor
 from nat.utils.exception_handlers.automatic_retries import patch_with_retry
 
@@ -45,6 +46,7 @@ class MemMachineMemoryClientConfig(MemoryBaseConfig, RetryMixin, name="memmachin
 
 
 @register_memory(config_type=MemMachineMemoryClientConfig)
+@experimental(feature_name="MemMachine")
 async def memmachine_memory_client(
         config: MemMachineMemoryClientConfig,
         _builder: Builder,  # Required by @register_memory contract