feat: add Agent Episodic Memory support (recall node, tracing)

- Add MemoryConfig with field_weights, threshold, result_count,
  folder_path, memory_space_name
- Add memory_recall node that queries UiPath Memory service before INIT
- Emit OTel trace spans (Find previous memories, Apply dynamic few shot)
- Extract OTel helpers to _utils/_otel.py for reuse across tools
- Prefix key_path with field type (agent-input) matching backend
- Add definition_system_prompt to memory search request
- Filter empty string values in _build_search_fields

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mjnovice

pyproject.toml

@@ -7,7 +7,7 @@ requires-python = ">=3.11"
 dependencies = [
     "uipath>=2.10.53, <2.11.0",
     "uipath-core>=0.5.2, <0.6.0",
-    "uipath-platform>=0.1.35, <0.2.0",
+    "uipath-platform>=0.1.36, <0.2.0",
     "uipath-runtime>=0.10.0, <0.11.0",
     "langgraph>=1.1.8, <2.0.0",
     "langchain-core>=1.2.11, <2.0.0",

src/uipath_langchain/_utils/__init__.py

@@ -1,4 +1,9 @@
 from ._environment import get_execution_folder_path
+from ._otel import set_span_attribute
 from ._request_mixin import UiPathRequestMixin
 
-__all__ = ["UiPathRequestMixin", "get_execution_folder_path"]
+__all__ = [
+    "UiPathRequestMixin",
+    "get_execution_folder_path",
+    "set_span_attribute",
+]

src/uipath_langchain/_utils/_otel.py

@@ -0,0 +1,15 @@
+"""OpenTelemetry utilities for span and trace context."""
+
+from typing import Any
+
+
+def set_span_attribute(name: str, value: Any) -> None:
+    """Set an attribute on the current OTel span (no-op if unavailable)."""
+    try:
+        from opentelemetry import trace
+
+        span = trace.get_current_span()
+        if span.is_recording():
+            span.set_attribute(name, value)
+    except ImportError:
+        pass

src/uipath_langchain/agent/react/__init__.py

@@ -1,7 +1,7 @@
 """UiPath ReAct Agent implementation"""
 
 from .agent import create_agent
-from .types import AgentGraphConfig, AgentGraphNode, AgentGraphState
+from .types import AgentGraphConfig, AgentGraphNode, AgentGraphState, MemoryConfig
 from .utils import resolve_input_model, resolve_output_model
 
 __all__ = [
@@ -11,4 +11,5 @@
     "AgentGraphNode",
     "AgentGraphState",
     "AgentGraphConfig",
+    "MemoryConfig",
 ]

src/uipath_langchain/agent/react/agent.py

@@ -24,6 +24,7 @@
 from .llm_node import (
     create_llm_node,
 )
+from .memory_node import create_memory_recall_node
 from .router import (
     create_route_agent,
 )
@@ -36,6 +37,7 @@
     AgentGraphConfig,
     AgentGraphNode,
     AgentGraphState,
+    MemoryConfig,
 )
 from .utils import create_state_with_input
 
@@ -53,6 +55,7 @@ def create_agent(
     output_schema: Type[OutputT] | None = None,
     config: AgentGraphConfig | None = None,
     guardrails: Sequence[tuple[BaseGuardrail, GuardrailAction]] | None = None,
+    memory: MemoryConfig | None = None,
 ) -> StateGraph[AgentGraphState, None, InputT, OutputT]:
     """Build agent graph with INIT -> AGENT (subgraph) <-> TOOLS loop, terminated by control flow tools.
 
@@ -122,7 +125,13 @@ def create_agent(
     )
     builder.add_node(AgentGraphNode.TERMINATE, terminate_with_guardrails_subgraph)
 
-    builder.add_edge(START, AgentGraphNode.INIT)
+    if memory:
+        memory_recall = create_memory_recall_node(memory, input_schema=input_schema)
+        builder.add_node(AgentGraphNode.MEMORY_RECALL, memory_recall)
+        builder.add_edge(START, AgentGraphNode.MEMORY_RECALL)
+        builder.add_edge(AgentGraphNode.MEMORY_RECALL, AgentGraphNode.INIT)
+    else:
+        builder.add_edge(START, AgentGraphNode.INIT)
 
     llm_node = create_llm_node(
         model,

src/uipath_langchain/agent/react/init_node.py

@@ -25,6 +25,19 @@ def graph_state_init(state: Any) -> Any:
             resolved_messages = list(messages(state))
         else:
             resolved_messages = list(messages)
+
+        # Append memory injection from the MEMORY_RECALL node (if present)
+        memory_injection = ""
+        if hasattr(state, "inner_state") and hasattr(
+            state.inner_state, "memory_injection"
+        ):
+            memory_injection = state.inner_state.memory_injection or ""
+        if memory_injection and resolved_messages:
+            first = resolved_messages[0]
+            if isinstance(first, SystemMessage):
+                resolved_messages[0] = SystemMessage(
+                    content=str(first.content) + memory_injection
+                )
         if is_conversational:
             # For conversational agents we need to reorder the messages so that the system message is first, followed by
             # the initial user message. When resuming the conversation, the state will have the entire message history,

src/uipath_langchain/agent/react/memory_node.py

@@ -0,0 +1,228 @@
+"""Memory recall node for Agent Episodic Memory.
+
+Queries the UiPath Memory service (via LLMOps) for similar past episodes
+and stores the server-generated systemPromptInjection in graph state so
+the INIT node can append it to the system prompt.
+"""
+
+import logging
+from contextlib import contextmanager
+from typing import Any
+
+from pydantic import BaseModel
+from uipath.platform import UiPath
+from uipath.platform.errors import EnrichedException
+from uipath.platform.memory import (
+    FieldSettings,
+    MemorySearchRequest,
+    SearchField,
+    SearchMode,
+    SearchSettings,
+)
+
+from .types import MemoryConfig
+from .utils import extract_input_data_from_state
+
+logger = logging.getLogger(__name__)
+
+
+@contextmanager
+def _noop_context():
+    """No-op context manager when OTel is unavailable."""
+    yield None
+
+
+def create_memory_recall_node(
+    memory_config: MemoryConfig,
+    input_schema: type[BaseModel] | None = None,
+):
+    """Create an async graph node that retrieves memory injection.
+
+    The node queries ``sdk.memory.search_async()`` and writes the
+    ``systemPromptInjection`` string into ``inner_state.memory_injection``.
+    On failure it logs a warning and continues with an empty injection.
+
+    Args:
+        memory_config: Memory configuration with space ID and search settings.
+
+    Returns:
+        An async callable suitable for ``builder.add_node()``.
+    """
+
+    async def memory_recall_node(state: Any) -> dict[str, Any]:
+        input_model = input_schema if input_schema is not None else BaseModel
+        input_arguments = extract_input_data_from_state(state, input_model)
+        if not input_arguments:
+            logger.debug("Memory recall: no user inputs found in state")
+            return {}
+
+        fields = _build_search_fields(
+            input_arguments, field_weights=memory_config.field_weights or None
+        )
+        if not fields:
+            logger.debug(
+                "Memory recall: no search fields after filtering (inputs=%s, weights=%s)",
+                list(input_arguments.keys()),
+                memory_config.field_weights,
+            )
+            return {}
+
+        request = MemorySearchRequest(
+            fields=fields,
+            settings=SearchSettings(
+                threshold=memory_config.threshold,
+                result_count=memory_config.result_count,
+                search_mode=SearchMode.Hybrid,
+            ),
+            definition_system_prompt="",
+        )
+
+        results_count = 0
+        # Wrap the search in OTel spans so "Find previous memories" and
+        # "Apply dynamic few shot" appear in the Execution Trace with
+        # correct timing. The LlmOpsHttpExporter picks these up.
+        injection = ""
+        try:
+            from opentelemetry import trace as otel_trace
+
+            tracer = otel_trace.get_tracer("uipath_langchain.memory")
+        except ImportError:
+            tracer = None
+            otel_trace = None  # type: ignore[assignment]
+
+        # Span attribute keys matching what the LlmOpsHttpExporter and
+        # Studio UI expect. "openinference.span.kind" sets SpanType.
+        lookup_span_ctx = (
+            tracer.start_as_current_span(
+                "Find previous memories",
+                attributes={
+                    "openinference.span.kind": "agentMemoryLookup",
+                    "type": "agentMemoryLookup",
+                    "span_type": "agentMemoryLookup",
+                    "uipath.custom_instrumentation": True,
+                    "memorySpaceName": memory_config.memory_space_name or "",
+                    "memorySpaceId": memory_config.memory_space_id,
+                    "strategy": "DynamicFewShotPrompt",
+                },
+            )
+            if tracer
+            else _noop_context()
+        )
+
+        with lookup_span_ctx as lookup_span:
+            fewshot_span_ctx = (
+                tracer.start_as_current_span(
+                    "Apply dynamic few shot",
+                    attributes={
+                        "openinference.span.kind": "applyDynamicFewShot",
+                        "type": "applyDynamicFewShot",
+                        "span_type": "applyDynamicFewShot",
+                        "uipath.custom_instrumentation": True,
+                        "memorySpaceName": memory_config.memory_space_name or "",
+                        "memorySpaceId": memory_config.memory_space_id,
+                    },
+                )
+                if tracer
+                else _noop_context()
+            )
+
+            with fewshot_span_ctx as fewshot_span:
+                try:
+                    sdk = UiPath()
+                    folder_key = memory_config.folder_key
+                    if not folder_key and memory_config.folder_path:
+                        folder_key = await sdk.folders.retrieve_folder_key_async(
+                            memory_config.folder_path
+                        )
+                    response = await sdk.memory.search_async(
+                        memory_space_id=memory_config.memory_space_id,
+                        request=request,
+                        folder_key=folder_key,
+                    )
+                    injection = response.system_prompt_injection
+                    results_count = len(response.results)
+                    logger.info(
+                        "Memory recall returned %d results for space '%s'",
+                        results_count,
+                        memory_config.memory_space_id,
+                    )
+                    # Set request/response on fewshot span as JSON strings.
+                    # The exporter parses JSON strings back to objects.
+                    # The UI reads "response" to display matched memory items.
+                    if fewshot_span and hasattr(fewshot_span, "set_attribute"):
+                        import json
+
+                        fewshot_span.set_attribute(
+                            "request",
+                            json.dumps(
+                                request.model_dump(by_alias=True, exclude_none=True)
+                            ),
+                        )
+                        fewshot_span.set_attribute(
+                            "response",
+                            json.dumps(
+                                response.model_dump(by_alias=True, exclude_none=True)
+                            ),
+                        )
+                except Exception as e:
+                    if isinstance(e, EnrichedException):
+                        error_detail = (
+                            f"{e} | status={e.status_code} body={e.response_content}"
+                        )
+                    else:
+                        error_detail = repr(e)
+                    logger.warning(
+                        "Memory recall failed for space '%s': %s",
+                        memory_config.memory_space_id,
+                        error_detail,
+                    )
+                    if otel_trace:
+                        if fewshot_span and hasattr(fewshot_span, "set_status"):
+                            fewshot_span.set_status(
+                                otel_trace.StatusCode.ERROR, error_detail
+                            )
+                        if lookup_span and hasattr(lookup_span, "set_status"):
+                            lookup_span.set_status(
+                                otel_trace.StatusCode.ERROR, error_detail
+                            )
+
+            # Set result attributes after search completes
+            if lookup_span and hasattr(lookup_span, "set_attribute"):
+                lookup_span.set_attribute("memoryItemsMatched", results_count)
+                if injection:
+                    lookup_span.set_attribute("result", injection)
+
+        if not injection:
+            return {}
+
+        return {"inner_state": {"memory_injection": injection}}
+
+    return memory_recall_node
+
+
+def _build_search_fields(
+    input_arguments: dict[str, Any],
+    field_weights: dict[str, float] | None = None,
+    field_type: str = "agent-input",
+) -> list[SearchField]:
+    """Convert agent input arguments to SearchField objects.
+
+    The key_path must be prefixed with the field type:
+      keyPath = [fieldType, fieldName]
+    e.g. ["agent-input", "a"] for episodic memory.
+    """
+    fields: list[SearchField] = []
+    for name, value in input_arguments.items():
+        value_str = str(value) if value is not None else ""
+        if not value_str or name.startswith("uipath__"):
+            continue
+        # When field_weights is specified, only include fields with configured weights
+        if field_weights and name not in field_weights:
+            continue
+        settings = FieldSettings()
+        if field_weights and name in field_weights:
+            settings = FieldSettings(weight=field_weights[name])
+        fields.append(
+            SearchField(key_path=[field_type, name], value=value_str, settings=settings)
+        )
+    return fields

src/uipath_langchain/agent/react/types.py

@@ -3,7 +3,7 @@
 
 from langchain_core.messages import AnyMessage
 from langgraph.graph.message import add_messages
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 from uipath.agent.react import END_EXECUTION_TOOL, RAISE_ERROR_TOOL
 from uipath.platform.attachments import Attachment
 
@@ -19,6 +19,7 @@ class InnerAgentGraphState(BaseModel):
     job_attachments: Annotated[dict[str, Attachment], merge_dicts] = {}
     initial_message_count: int | None = None
     tools_storage: Annotated[dict[Hashable, Any], merge_dicts] = {}
+    memory_injection: str = ""
 
 
 class InnerAgentGuardrailsGraphState(InnerAgentGraphState):
@@ -55,6 +56,43 @@ class AgentGraphNode(StrEnum):
     TOOLS = "tools"
     TERMINATE = "terminate"
     GUARDED_TERMINATE = "guarded-terminate"
+    MEMORY_RECALL = "memory_recall"
+
+
+class MemoryConfig(BaseModel):
+    """Configuration for Agent Episodic Memory.
+
+    When passed to ``create_agent()``, a MEMORY_RECALL node is added before
+    INIT that queries the memory service and stores the server-generated
+    systemPromptInjection in ``inner_state.memory_injection``.
+    """
+
+    memory_space_id: str = Field(description="GUID of the memory space to query.")
+    memory_space_name: str = Field(
+        default="", description="Name of the memory space (for tracing)."
+    )
+    folder_key: str | None = Field(
+        default=None, description="Folder key for the memory resource."
+    )
+    folder_path: str | None = Field(
+        default=None,
+        description="Folder path for the memory resource. Resolved to folder_key at runtime if folder_key is not set.",
+    )
+    # Defaults match FE episodic memory settings (agentEditor.ts:324-328)
+    result_count: int = Field(default=3, ge=1, le=10)
+    threshold: float = Field(default=0.0, ge=0.0, le=1.0)
+    field_weights: dict[str, float] = Field(
+        description=(
+            "Per-field search weights. Keys are input field names, values are "
+            "weights between 0.0 and 1.0. At least one field must be specified."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _validate_field_weights(self) -> "MemoryConfig":
+        if not self.field_weights:
+            raise ValueError("field_weights must contain at least one field")
+        return self
 
 
 class AgentGraphConfig(BaseModel):