You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by xt...@apache.org on 2025/08/20 09:59:22 UTC

(flink-agents) branch main updated: [API][Runtime]Introduce Memory Reference (#110)

This is an automated email from the ASF dual-hosted git repository.

xtsong pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git


The following commit(s) were added to refs/heads/main by this push:
     new 3d89f23  [API][Runtime]Introduce Memory Reference (#110)
3d89f23 is described below

commit 3d89f23ec441889560313c977173253829a63718
Author: KeGu-069 <gu...@gmail.com>
AuthorDate: Wed Aug 20 17:59:17 2025 +0800

    [API][Runtime]Introduce Memory Reference (#110)
    
    * [api][runtime][python]Introduce MemoryRef in local python runtime
    
    * [api][runtime][java]Add MemoryRef implementation and integrate it into MemoryObject
    
    * [runtime][python]Add MemoryRef to cross language sections and examples
---
 .../flink/agents/api/context/MemoryObject.java     |  13 +-
 .../apache/flink/agents/api/context/MemoryRef.java |  79 ++++++++
 python/flink_agents/api/memory_object.py           |  27 ++-
 python/flink_agents/api/memory_reference.py        |  64 +++++++
 python/flink_agents/api/runner_context.py          |   7 +-
 python/flink_agents/examples/agent_example.py      |  49 +++--
 python/flink_agents/examples/my_agent.py           |  32 ++--
 python/flink_agents/runtime/flink_memory_object.py |  33 ++--
 python/flink_agents/runtime/local_memory_object.py |  44 +++--
 .../runtime/tests/test_memory_reference.py         | 135 ++++++++++++++
 .../agents/runtime/memory/MemoryObjectImpl.java    |  13 +-
 .../flink/agents/runtime/memory/MemoryRefTest.java | 200 +++++++++++++++++++++
 12 files changed, 620 insertions(+), 76 deletions(-)

diff --git a/api/src/main/java/org/apache/flink/agents/api/context/MemoryObject.java b/api/src/main/java/org/apache/flink/agents/api/context/MemoryObject.java
index f37dcf6..6d6af4b 100644
--- a/api/src/main/java/org/apache/flink/agents/api/context/MemoryObject.java
+++ b/api/src/main/java/org/apache/flink/agents/api/context/MemoryObject.java
@@ -39,16 +39,27 @@ public interface MemoryObject {
      */
     MemoryObject get(String path) throws Exception;
 
+    /**
+     * Returns a MemoryObject that represents the path of the given reference.
+     *
+     * @param ref a reference to a data item in the short-term memory
+     * @return a MemoryObject instance pointing to the referenced field. Returns null if the path of
+     *     the reference does not exist.
+     * @throws Exception if an error occurs during state access
+     */
+    MemoryObject get(MemoryRef ref) throws Exception;
+
     /**
      * Sets the value of a direct field in the current object; any missing intermediate objects will
      * be created automatically.
      *
      * @param path relative path from the current object to the target field
      * @param value new value of the field
+     * @return a {@link MemoryRef} instance pointing to the data just set
      * @throws Exception if trying to overwrite a nested object with a primitive value or set a
      *     MemoryObject directly
      */
-    void set(String path, Object value) throws Exception;
+    MemoryRef set(String path, Object value) throws Exception;
 
     /**
      * Creates a new MemoryObject as an indirect field in the current object.
diff --git a/api/src/main/java/org/apache/flink/agents/api/context/MemoryRef.java b/api/src/main/java/org/apache/flink/agents/api/context/MemoryRef.java
new file mode 100644
index 0000000..8f0a133
--- /dev/null
+++ b/api/src/main/java/org/apache/flink/agents/api/context/MemoryRef.java
@@ -0,0 +1,79 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.flink.agents.api.context;
+
+import java.io.Serializable;
+import java.util.Objects;
+
+/**
+ * A serializable, persistent reference to a specific data item in Short-Term Memory. It acts as a
+ * lightweight pointer, containing the path of the data, allowing for efficient passing of large
+ * objects between Actions.
+ */
+public final class MemoryRef implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    private final String path;
+
+    private MemoryRef(String path) {
+        this.path = path;
+    }
+
+    /**
+     * Creates a new MemoryRef instance with the given path.
+     *
+     * @param path The absolute path of the data in Short-Term Memory.
+     * @return A new MemoryRef instance.
+     */
+    public static MemoryRef create(String path) {
+        return new MemoryRef(path);
+    }
+
+    /**
+     * Resolves the reference using the provided RunnerContext to get the actual data.
+     *
+     * @param ctx The current execution context, used to access Short-Term Memory.
+     * @return The deserialized, original data object.
+     * @throws Exception if the memory cannot be accessed or the data cannot be resolved.
+     */
+    public MemoryObject resolve(RunnerContext ctx) throws Exception {
+        return ctx.getShortTermMemory().get(this);
+    }
+
+    public String getPath() {
+        return path;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        MemoryRef memoryRef = (MemoryRef) o;
+        return path.equals(memoryRef.path);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(path);
+    }
+
+    @Override
+    public String toString() {
+        return "MemoryRef{" + "path='" + path + '\'' + '}';
+    }
+}
diff --git a/python/flink_agents/api/memory_object.py b/python/flink_agents/api/memory_object.py
index 8a66e77..a250199 100644
--- a/python/flink_agents/api/memory_object.py
+++ b/python/flink_agents/api/memory_object.py
@@ -16,10 +16,12 @@
 # limitations under the License.
 #################################################################################
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List
+from typing import TYPE_CHECKING, Any, Dict, List, Union
 
 from pydantic import BaseModel
 
+if TYPE_CHECKING:
+    from flink_agents.api.memory_reference import MemoryRef
 
 class MemoryObject(BaseModel, ABC):
     """Representation of an object in the short-term memory.
@@ -30,25 +32,27 @@ class MemoryObject(BaseModel, ABC):
     """
 
     @abstractmethod
-    def get(self, path: str) -> Any:
-        """Get the value of a (direct or indirect) field in the object.
+    def get(self, path_or_ref: Union[str,"MemoryRef"] ) -> Any:
+        """Get the value of a (direct or indirect) field or a MemoryRef in the object.
 
         Parameters
         ----------
-        path: str
-          Relative path from the current object to the target field.
+        path_or_ref: Union[str,MemoryRef]
+          Relative path from the current object to the target field or
+          a MemoryRef instance.
 
         Returns:
         -------
         Any
-          If the field is a direct field, returns the concrete data stored.
+          If the input is a MemoryRef, resolve the reference and returns the data.
+          If the field is a direct field, return the concrete data stored.
           If the field is an indirect field, another MemoryObject will be returned.
-          If the field doesn't exist, returns None.
+          If the field doesn't exist, return None.
         """
 
     @abstractmethod
-    def set(self, path: str, value: Any) -> None:
-        """Set the value of an indirect field in the object.
+    def set(self, path: str, value: Any) -> "MemoryRef":
+        """Set the value of a direct field in the object and return a reference to it.
         This will also create the intermediate objects if not exist.
 
         Parameters
@@ -57,6 +61,11 @@ class MemoryObject(BaseModel, ABC):
           Relative path from the current object to the target field.
         value: Any
           New value of the field. The type of the value must be a primary type.
+
+        Returns:
+        -------
+        MemoryRef
+          A newly created reference to the data just set.
         """
 
     @abstractmethod
diff --git a/python/flink_agents/api/memory_reference.py b/python/flink_agents/api/memory_reference.py
new file mode 100644
index 0000000..0b9d403
--- /dev/null
+++ b/python/flink_agents/api/memory_reference.py
@@ -0,0 +1,64 @@
+################################################################################
+#  Licensed to the Apache Software Foundation (ASF) under one
+#  or more contributor license agreements.  See the NOTICE file
+#  distributed with this work for additional information
+#  regarding copyright ownership.  The ASF licenses this file
+#  to you under the Apache License, Version 2.0 (the
+#  "License"); you may not use this file except in compliance
+#  with the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+# limitations under the License.
+#################################################################################
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    from flink_agents.api.runner_context import RunnerContext
+
+
+class MemoryRef(BaseModel):
+    """Reference to a specific data item in the Short-Term Memory."""
+
+    path: str
+
+    model_config = ConfigDict(frozen=True)
+
+    @staticmethod
+    def create(path: str) -> MemoryRef:
+        """Create a new MemoryRef instance based on the given path.
+
+        Parameters
+        ----------
+        path: str
+            The absolute path of the data in the Short-Term Memory.
+
+        Returns:
+        -------
+        MemoryRef
+            A new MemoryRef instance.
+        """
+        return MemoryRef(path=path)
+
+    def resolve(self, ctx: RunnerContext) -> Any:
+        """Resolve the reference to get the actual data.
+
+        Parameters
+        ----------
+        ctx: RunnerContext
+            The current execution context, used to access Short-Term Memory.
+
+        Returns:
+        -------
+        Any
+            The deserialized, original data object.
+        """
+        return ctx.get_short_term_memory().get(self)
diff --git a/python/flink_agents/api/runner_context.py b/python/flink_agents/api/runner_context.py
index 7f938f9..03e7954 100644
--- a/python/flink_agents/api/runner_context.py
+++ b/python/flink_agents/api/runner_context.py
@@ -16,13 +16,14 @@
 # limitations under the License.
 #################################################################################
 from abc import ABC, abstractmethod
-from typing import Any, Callable, Dict, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Dict, Tuple
 
 from flink_agents.api.events.event import Event
-from flink_agents.api.memory_object import MemoryObject
 from flink_agents.api.metric_group import MetricGroup
 from flink_agents.api.resource import Resource, ResourceType
 
+if TYPE_CHECKING:
+    from flink_agents.api.memory_object import MemoryObject
 
 class RunnerContext(ABC):
     """Abstract base class providing context for agent execution.
@@ -53,7 +54,7 @@ class RunnerContext(ABC):
         """
 
     @abstractmethod
-    def get_short_term_memory(self) -> MemoryObject:
+    def get_short_term_memory(self) -> "MemoryObject":
         """Get the short-term memory.
 
         Returns:
diff --git a/python/flink_agents/examples/agent_example.py b/python/flink_agents/examples/agent_example.py
index 56487cb..613c6bb 100644
--- a/python/flink_agents/examples/agent_example.py
+++ b/python/flink_agents/examples/agent_example.py
@@ -15,7 +15,9 @@
 #  See the License for the specific language governing permissions and
 # limitations under the License.
 #################################################################################
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
 
 from flink_agents.api.agent import Agent
 from flink_agents.api.decorators import action
@@ -23,6 +25,13 @@ from flink_agents.api.events.event import Event, InputEvent, OutputEvent
 from flink_agents.api.execution_environment import AgentsExecutionEnvironment
 from flink_agents.api.runner_context import RunnerContext
 
+if TYPE_CHECKING:
+    from flink_agents.api.memory_reference import MemoryRef
+
+
+class ProcessedData(BaseModel):  # noqa D101
+    content: str
+    visit_count: int
 
 class MyEvent(Event):  # noqa D101
     value: Any
@@ -39,33 +48,43 @@ class MyAgent(Agent):
     @action(InputEvent)
     @staticmethod
     def first_action(event: Event, ctx: RunnerContext):  # noqa D102
-        input = event.input
+        key = ctx.key
+        input_message = event.input
         memory = ctx.get_short_term_memory()
 
-        current_count = memory.get("action_counter") or 0
+        data_path = f"user_data.{key}"
+        previous_data: ProcessedData = memory.get(data_path)
+        current_count = previous_data.visit_count if previous_data else 0
         new_count = current_count + 1
-        memory.set("action_counter", new_count)
 
-        content = input + " -> first_action"
-        key_with_count = f"(seen {new_count} times)"
+        data_to_store = ProcessedData(content=input_message,visit_count=new_count)
+        data_ref = memory.set(data_path, data_to_store)
+
+        ctx.send_event(MyEvent(value=data_ref))
+
+        processed_content = f"{input_message} -> processed_by_first_action"
+        key_with_count = f"(visit {new_count} times)"
+        ctx.send_event(OutputEvent(output={key_with_count:processed_content}))
 
-        ctx.send_event(MyEvent(value=content))
-        ctx.send_event(OutputEvent(output={key_with_count: content}))
 
     @action(MyEvent)
     @staticmethod
     def second_action(event: Event, ctx: RunnerContext):  # noqa D102
-        input = event.value
+        content_ref: MemoryRef = event.value
         memory = ctx.get_short_term_memory()
 
-        current_count = memory.get("action_counter")
+        processed_data: ProcessedData = memory.get(content_ref)
+
+        base_message = processed_data.content
+        current_count = processed_data.visit_count
         new_count = current_count + 1
-        memory.set("action_counter", new_count)
 
-        base_message = input.split("->")[0].strip()
-        content = base_message + " -> second_action"
-        key_with_count = f"(seen {new_count} times)"
-        ctx.send_event(OutputEvent(output={key_with_count: content}))
+        updated_data_to_store = ProcessedData(content=base_message, visit_count=new_count)
+        memory.set(content_ref.path, updated_data_to_store)
+
+        final_content = f"{base_message} -> processed by second_action"
+        key_with_count = f"(visit {new_count} times)"
+        ctx.send_event(OutputEvent(output={key_with_count: final_content}))
 
 
 if __name__ == "__main__":
diff --git a/python/flink_agents/examples/my_agent.py b/python/flink_agents/examples/my_agent.py
index ff90788..f13a739 100644
--- a/python/flink_agents/examples/my_agent.py
+++ b/python/flink_agents/examples/my_agent.py
@@ -51,7 +51,6 @@ class ItemData(BaseModel):
 class MyEvent(Event):  # noqa D101
     value: Any
 
-
 class DataStreamAgent(Agent):
     """Agent used for explaining integrating agents with DataStream.
 
@@ -86,38 +85,33 @@ class DataStreamAgent(Agent):
             print(f"[log_to_stdout] Logging input={input}, total reviews now={total}")
             return True
 
-        input = event.input
-
+        input_data = event.input
         stm = ctx.get_short_term_memory()
-        status = stm.new_object("status", overwrite=True)
 
-        total = 0
-        if stm.is_exist("status.total_reviews"):
-            total = status.get("total_reviews")
-        total += 1
-        status.set("total_reviews", total)
+        current_total = stm.get("status.total_reviews") or 0
+        total = current_total + 1
+        stm.set("status.total_reviews", total)
 
-        log_success = yield from ctx.execute_async(log_to_stdout, input, total)
+        log_success = yield from ctx.execute_async(log_to_stdout, input_data, total)
 
-        content = copy.deepcopy(input)
+        content = copy.deepcopy(input_data)
         content.review += " first action, log success=" + str(log_success) + ","
-        ctx.send_event(MyEvent(value=content))
+        content.memory_info = {"total_reviews": total}
+
+        data_ref = stm.set(f"processed_items.item_{content.id}", content)
+        ctx.send_event(MyEvent(value=data_ref.model_dump()))
 
     @action(MyEvent)
     @staticmethod
     def second_action(event: Event, ctx: RunnerContext):  # noqa D102
-        input = event.value
-
+        input_data = event.value
         stm = ctx.get_short_term_memory()
-        memory_info = {
-            "total_reviews": stm.get("status.total_reviews"),
-        }
+        resolved_data: ItemData = stm.get(input_data)
 
-        content = copy.deepcopy(input)
+        content = copy.deepcopy(resolved_data)
         content.review += " second action"
         tool = ctx.get_resource("my_tool", ResourceType.TOOL)
         content.review = tool.call(content.review)
-        content.memory_info = memory_info
         ctx.send_event(OutputEvent(output=content))
 
 
diff --git a/python/flink_agents/runtime/flink_memory_object.py b/python/flink_agents/runtime/flink_memory_object.py
index afd5d95..c125648 100644
--- a/python/flink_agents/runtime/flink_memory_object.py
+++ b/python/flink_agents/runtime/flink_memory_object.py
@@ -15,7 +15,9 @@
 #  See the License for the specific language governing permissions and
 # limitations under the License.
 #################################################################################
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Union
+
+from python.flink_agents.api.memory_reference import MemoryRef
 
 from flink_agents.api.memory_object import MemoryObject
 
@@ -32,27 +34,36 @@ class FlinkMemoryObject(MemoryObject):
         """Initialize with a Java MemoryObject instance."""
         self._j_memory_object = j_memory_object
 
-    def get(self, path: str) -> Any:
-        """Get a nested object or value by path.
+    def get(self, path_or_ref: Union[str, MemoryRef]) -> Any:
+        """Get a nested object or value by path or MemoryRef.
 
-        If the field is an object, returns a new FlinkMemoryObject.
-        Returns None if the field does not exist.
+        If the input is a MemoryRef, resolve the reference and return the data.
+        If the field is a direct field, return the concrete data stored.
+        If the field is an indirect object, return a new FlinkMemoryObject.
+        Return None if the field does not exist.
         """
         try:
-            j_result = self._j_memory_object.get(path)
+            path_to_get: str
+            if isinstance(path_or_ref, dict) and 'path' in path_or_ref:
+                path_to_get = path_or_ref['path']
+            elif isinstance(path_or_ref, str):
+                path_to_get = path_or_ref
+            j_result = self._j_memory_object.get(path_to_get)
             if j_result is None:
                 return None
-            if not j_result.isNestedObject():
+            if j_result.isNestedObject():
+                return FlinkMemoryObject(j_result)
+            else:
                 return j_result.getValue()
-            return FlinkMemoryObject(j_result)
         except Exception as e:
-            msg = f"Failed to get field '{path}' from short-term memory"
+            msg = f"Failed to get field '{path_or_ref}' from short-term memory"
             raise MemoryObjectError(msg) from e
 
-    def set(self, path: str, value: Any) -> None:
+    def set(self, path: str, value: Any) -> MemoryRef:
         """Set a value at the given path. Creates intermediate objects if needed."""
         try:
-            self._j_memory_object.set(path, value)
+            j_ref = self._j_memory_object.set(path, value)
+            return MemoryRef(path=j_ref.getPath())
         except Exception as e:
             msg = f"Failed to set value at path '{path}'"
             raise MemoryObjectError(msg) from e
diff --git a/python/flink_agents/runtime/local_memory_object.py b/python/flink_agents/runtime/local_memory_object.py
index 2925468..2b145df 100644
--- a/python/flink_agents/runtime/local_memory_object.py
+++ b/python/flink_agents/runtime/local_memory_object.py
@@ -15,9 +15,10 @@
 #  See the License for the specific language governing permissions and
 # limitations under the License.
 #################################################################################
-from typing import Any, ClassVar, Dict, List
+from typing import Any, ClassVar, Dict, List, Union
 
 from flink_agents.api.memory_object import MemoryObject
+from flink_agents.api.memory_reference import MemoryRef
 
 
 class LocalMemoryObject(MemoryObject):
@@ -53,22 +54,28 @@ class LocalMemoryObject(MemoryObject):
         if self.ROOT_KEY not in self.__store:
             self.__store[self.ROOT_KEY] = _ObjMarker()
 
-    def get(self, path: str) -> Any:
-        """Get the value of a (direct or indirect) field in the object.
+    def get(self, path_or_ref: Union[str,MemoryRef]) -> Any:
+        """Get the value of a (direct or indirect) field or a MemoryRef in the object.
 
         Parameters
         ----------
-        path: str
-          Relative path from the current object to the target field.
+        path_or_ref: Union[str,MemoryRef]
+          Relative path from the current object to the target field or
+          a MemoryRef instance.
 
         Returns:
         -------
         Any
-          If the field is a direct field, returns the concrete data stored.
+          If the input is a MemoryRef, resolve the reference and return the data.
+          If the field is a direct field, return the concrete data stored.
           If the field is an indirect field, another MemoryObject will be returned.
-          If the field doesn't exist, returns None.
+          If the field doesn't exist, return None.
         """
-        abs_path = self._full_path(path)
+        if isinstance(path_or_ref, MemoryRef):
+            abs_path = path_or_ref.path
+        else:
+            abs_path = self._full_path(path_or_ref)
+
         if abs_path in self.__store:
             value = self.__store[abs_path]
             if self._is_nested_object(value):
@@ -76,8 +83,8 @@ class LocalMemoryObject(MemoryObject):
             return value
         return None
 
-    def set(self, path: str, value: Any) -> None:
-        """Set the value of a direct field in the object.
+    def set(self, path: str, value: Any) -> MemoryRef:
+        """Set the value of a direct field in the object and return a reference to it.
         This will also create the intermediate objects if not exist.
 
         Parameters
@@ -86,24 +93,29 @@ class LocalMemoryObject(MemoryObject):
           Relative path from the current object to the target field.
         value: Any
           New value of the field. The type of the value must be a primary type.
+
+        Returns:
+        -------
+        MemoryRef
+          A newly created reference to the data just set.
         """
         if isinstance(value, LocalMemoryObject):
             msg = "Do not set a MemoryObject instance directly; use new_object()."
             raise TypeError(msg)
 
         abs_path = self._full_path(path)
-        parts = abs_path.split(self.__SEPARATOR)
-
-        self._fill_parents(parts)
-
-        parent_path = self._parent_of(parts)
-        self._add_subfield(parent_path, parts[-1])
 
         if abs_path in self.__store and self._is_nested_object(self.__store[abs_path]):
             msg = f"Cannot overwrite object field '{abs_path}' with primitive."
             raise ValueError(msg)
 
+        parts = abs_path.split(self.__SEPARATOR)
+        self._fill_parents(parts)
+        parent_path = self._parent_of(parts)
+        self._add_subfield(parent_path, parts[-1])
+
         self.__store[abs_path] = value
+        return MemoryRef(path=abs_path)
 
     def new_object(self, path: str, *, overwrite: bool = False) -> "LocalMemoryObject":
         """Create a new object as the value of an indirect field in the object.
diff --git a/python/flink_agents/runtime/tests/test_memory_reference.py b/python/flink_agents/runtime/tests/test_memory_reference.py
new file mode 100644
index 0000000..8c5e395
--- /dev/null
+++ b/python/flink_agents/runtime/tests/test_memory_reference.py
@@ -0,0 +1,135 @@
+################################################################################
+#  Licensed to the Apache Software Foundation (ASF) under one
+#  or more contributor license agreements.  See the NOTICE file
+#  distributed with this work for additional information
+#  regarding copyright ownership.  The ASF licenses this file
+#  to you under the Apache License, Version 2.0 (the
+#  "License"); you may not use this file except in compliance
+#  with the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+# limitations under the License.
+#################################################################################
+from flink_agents.api.memory_reference import MemoryRef
+from flink_agents.runtime.local_memory_object import LocalMemoryObject
+
+
+class MockRunnerContext:  # noqa D101
+    def __init__(self, memory: LocalMemoryObject) -> None:
+        """Mock RunnerContext for testing resolve() method."""
+        self._memory = memory
+
+    def get_short_term_memory(self) -> LocalMemoryObject:  # noqa D102
+        return self._memory
+
+
+def create_memory() -> LocalMemoryObject:
+    """Return a MemoryObject for every test case."""
+    return LocalMemoryObject({})
+
+
+class User:  # noqa: D101
+    def __init__(self, name: str, age: int) -> None:
+        """Store for later comparison."""
+        self.name = name
+        self.age = age
+
+    def __eq__(self, other: object) -> bool:
+        return (
+                isinstance(other, User)
+                and other.name == self.name
+                and other.age == self.age
+        )
+
+
+def test_set_get_involved_ref() -> None:  # noqa: D103
+    mem = create_memory()
+
+    # Test cases: (path, value, type_name)
+    test_cases = [
+        ("my_int", 1, "int"),
+        ("my_float", 3.14, "float"),
+        ("my_str", "hello", "str"),
+        ("my_list", ["a", "b"], "list"),
+        ("my_dict", {"x": 10}, "dict"),
+        ("my_set", {1, 2, 3}, "set"),
+        ("my_user", User("Alice", 30), "User"),
+    ]
+
+    for path, value, _expected_type_name in test_cases:
+        ref = mem.set(path, value)
+        assert isinstance(ref, MemoryRef)
+        assert ref.path == path
+
+        retrieved_value = mem.get(ref)
+        assert retrieved_value == value
+
+
+def test_memory_ref_create() -> None:  # noqa: D103
+    path = "a.b.c"
+    ref = MemoryRef.create(path)
+
+    assert isinstance(ref, MemoryRef)
+    assert ref.path == path
+
+
+def test_memory_ref_resolve() -> None:  # noqa: D103
+    mem = create_memory()
+    ctx = MockRunnerContext(mem)
+
+    test_data = {
+        "my_int": 1,
+        "my_float": 3.14,
+        "my_str": "hello",
+        "my_list": ["a", "b"],
+        "my_dict": {"x": 10},
+        "my_set": {1, 2, 3},
+        "my_user": User("Charlie", 50),
+    }
+
+    for path, value in test_data.items():
+        ref = mem.set(path, value)
+        resolved_value = ref.resolve(ctx)
+        assert resolved_value == value
+
+
+def test_get_with_ref_to_nested_object() -> None:  # noqa: D103
+    mem = create_memory()
+    obj = mem.new_object("a.b")
+    obj.set("c", 10)
+
+    ref = MemoryRef.create("a")
+
+    resolved_obj = mem.get(ref)
+    assert isinstance(resolved_obj, LocalMemoryObject)
+    assert resolved_obj.get("b.c") == 10
+
+
+def test_get_with_non_existent_ref() -> None:  # noqa: D103
+    mem = create_memory()
+
+    non_existent_ref = MemoryRef.create("this.path.does.not.exist")
+
+    assert mem.get(non_existent_ref) is None
+
+
+def test_ref_equality_and_hashing() -> None:  # noqa: D103
+    ref1 = MemoryRef(path="a.b")
+    ref2 = MemoryRef(path="a.b")
+    ref3 = MemoryRef(path="a.c")
+
+    assert ref1 == ref2
+    assert ref1 != ref3
+
+    assert hash(ref1) == hash(ref2)
+    assert hash(ref1) != hash(ref3)
+
+    ref_set = {ref1, ref2, ref3}
+    assert len(ref_set) == 2
+    assert ref1 in ref_set
+    assert ref3 in ref_set
diff --git a/runtime/src/main/java/org/apache/flink/agents/runtime/memory/MemoryObjectImpl.java b/runtime/src/main/java/org/apache/flink/agents/runtime/memory/MemoryObjectImpl.java
index dfedf1f..6999e07 100644
--- a/runtime/src/main/java/org/apache/flink/agents/runtime/memory/MemoryObjectImpl.java
+++ b/runtime/src/main/java/org/apache/flink/agents/runtime/memory/MemoryObjectImpl.java
@@ -18,8 +18,10 @@
 package org.apache.flink.agents.runtime.memory;
 
 import org.apache.flink.agents.api.context.MemoryObject;
+import org.apache.flink.agents.api.context.MemoryRef;
 import org.apache.flink.api.common.state.MapState;
 
+import java.io.Serializable;
 import java.util.*;
 
 public class MemoryObjectImpl implements MemoryObject {
@@ -62,7 +64,12 @@ public class MemoryObjectImpl implements MemoryObject {
     }
 
     @Override
-    public void set(String path, Object value) throws Exception {
+    public MemoryObject get(MemoryRef ref) throws Exception {
+        return get(ref.getPath());
+    }
+
+    @Override
+    public MemoryRef set(String path, Object value) throws Exception {
         mailboxThreadChecker.run();
         String absPath = fullPath(path);
         String[] parts = absPath.split("\\.");
@@ -83,6 +90,8 @@ public class MemoryObjectImpl implements MemoryObject {
 
         MemoryItem val = new MemoryItem(value);
         store.put(absPath, val);
+
+        return MemoryRef.create(absPath);
     }
 
     @Override
@@ -197,7 +206,7 @@ public class MemoryObjectImpl implements MemoryObject {
     }
 
     /** Represents an item (nested object or primitive value) stored in the short-term memory. */
-    public static final class MemoryItem {
+    public static final class MemoryItem implements Serializable {
         private final ItemType type;
         private final Object value;
         private final Set<String> subKeys;
diff --git a/runtime/src/test/java/org/apache/flink/agents/runtime/memory/MemoryRefTest.java b/runtime/src/test/java/org/apache/flink/agents/runtime/memory/MemoryRefTest.java
new file mode 100644
index 0000000..2b95f37
--- /dev/null
+++ b/runtime/src/test/java/org/apache/flink/agents/runtime/memory/MemoryRefTest.java
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.flink.agents.runtime.memory;
+
+import org.apache.flink.agents.api.context.MemoryObject;
+import org.apache.flink.agents.api.context.MemoryRef;
+import org.apache.flink.agents.api.context.RunnerContext;
+import org.apache.flink.agents.api.metrics.FlinkAgentsMetricGroup;
+import org.apache.flink.agents.api.resource.Resource;
+import org.apache.flink.agents.api.resource.ResourceType;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/** Tests for {@link MemoryRef} and its integration with {@link MemoryObject}. */
+public class MemoryRefTest {
+
+    private MemoryObjectImpl memory;
+
+    /** Simple POJO example. */
+    static class Person {
+        String name;
+        int age;
+
+        Person(String n, int a) {
+            this.name = n;
+            this.age = a;
+        }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) return true;
+            if (!(o instanceof Person)) return false;
+            Person p = (Person) o;
+            return age == p.age && Objects.equals(name, p.name);
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(name, age);
+        }
+    }
+
+    /** Mock RunnerContext for testing resolve(). */
+    static class MockRunnerContext implements RunnerContext {
+        private final MemoryObject memoryObject;
+
+        MockRunnerContext(MemoryObject memoryObject) {
+            this.memoryObject = memoryObject;
+        }
+
+        @Override
+        public MemoryObject getShortTermMemory() {
+            return memoryObject;
+        }
+
+        @Override
+        public void sendEvent(org.apache.flink.agents.api.Event event) {}
+
+        @Override
+        public FlinkAgentsMetricGroup getAgentMetricGroup() {
+            return null;
+        }
+
+        @Override
+        public FlinkAgentsMetricGroup getActionMetricGroup() {
+            return null;
+        }
+
+        @Override
+        public Resource getResource(String name, ResourceType type) throws Exception {
+            return null;
+        }
+    }
+
+    @BeforeEach
+    void setUp() throws Exception {
+        ForTestMemoryMapState<MemoryObjectImpl.MemoryItem> mapState = new ForTestMemoryMapState<>();
+        memory = new MemoryObjectImpl(mapState, MemoryObjectImpl.ROOT_KEY);
+    }
+
+    @Test
+    void testSetAndGetInvolvedRef() throws Exception {
+        MemoryRef intRef = memory.set("my_int", 123);
+        assertEquals("my_int", intRef.getPath());
+        assertEquals(123, memory.get(intRef).getValue());
+
+        MemoryRef strRef = memory.set("my_str", "hello");
+        assertEquals("my_str", strRef.getPath());
+        assertEquals("hello", memory.get(strRef).getValue());
+
+        // List
+        List<String> list = Arrays.asList("a", "b");
+        MemoryRef listRef = memory.set("my_list", list);
+        assertEquals("my_list", listRef.getPath());
+        assertEquals(list, memory.get(listRef).getValue());
+
+        // Map
+        Map<String, Integer> map = new HashMap<>();
+        map.put("x", 10);
+        MemoryRef mapRef = memory.set("my_map", map);
+        assertEquals("my_map", mapRef.getPath());
+        assertEquals(map, memory.get(mapRef).getValue());
+
+        // Set
+        Set<Integer> set = new HashSet<>(Arrays.asList(1, 2, 3));
+        MemoryRef setRef = memory.set("my_set", set);
+        assertEquals("my_set", setRef.getPath());
+        assertEquals(set, memory.get(setRef).getValue());
+
+        // Custom POJO
+        Person alice = new Person("Alice", 23);
+        MemoryRef personRef = memory.set("pojo", alice);
+        assertEquals("pojo", personRef.getPath());
+        assertEquals(alice, memory.get(personRef).getValue());
+    }
+
+    @Test
+    void testMemoryRefCreate() {
+        String path = "a.b.c";
+        String typeName = "String";
+        MemoryRef ref = MemoryRef.create(path);
+
+        assertNotNull(ref);
+        assertEquals(path, ref.getPath());
+    }
+
+    @Test
+    void testMemoryRefResolve() throws Exception {
+        MockRunnerContext ctx = new MockRunnerContext(memory);
+
+        Map<String, Object> testData = new HashMap<>();
+        testData.put("my_int", 1);
+        testData.put("my_str", "resolve_test");
+        testData.put("my_list", Arrays.asList("x", "y", "z"));
+        testData.put("my_person", new Person("Resolver", 42));
+
+        for (Map.Entry<String, Object> entry : testData.entrySet()) {
+            MemoryRef ref = memory.set(entry.getKey(), entry.getValue());
+
+            Object resolvedValue = ref.resolve(ctx).getValue();
+            assertEquals(entry.getValue(), resolvedValue);
+        }
+    }
+
+    @Test
+    void testGetWithRefToNestedObject() throws Exception {
+        MemoryObject obj = memory.newObject("a.b", false);
+        obj.set("c", 10);
+
+        MemoryRef ref = MemoryRef.create("a");
+
+        MemoryObject resolvedObj = memory.get(ref);
+        assertNotNull(resolvedObj);
+        assertTrue(resolvedObj.isNestedObject());
+        assertEquals(10, resolvedObj.get("b.c").getValue());
+    }
+
+    @Test
+    void testGetWithNonExistentRef() throws Exception {
+        MemoryRef nonExistentRef = MemoryRef.create("this.path.does.not.exist");
+        assertNull(memory.get(nonExistentRef));
+    }
+
+    @Test
+    void testRefEqualityAndHashing() {
+        MemoryRef ref1 = MemoryRef.create("a.b");
+        MemoryRef ref2 = MemoryRef.create("a.b");
+        MemoryRef ref3 = MemoryRef.create("a.c");
+
+        assertEquals(ref1, ref2);
+        assertNotEquals(ref1, ref3);
+
+        assertEquals(ref1.hashCode(), ref2.hashCode());
+        assertNotEquals(ref1.hashCode(), ref3.hashCode());
+
+        Set<MemoryRef> refSet = new HashSet<>(Arrays.asList(ref1, ref2, ref3));
+        assertEquals(2, refSet.size());
+        assertTrue(refSet.contains(ref1));
+        assertTrue(refSet.contains(ref3));
+    }
+}