feat: add Agent Episodic Memory support (recall node + escalation memory)

Hybrid architecture for memory spaces with two integration points:

1. Pre-execution injection (graph node):
   - New MEMORY_RECALL node added before INIT when MemoryConfig is provided
   - Queries sdk.memory.search_async() and stores the server-generated
     systemPromptInjection in inner_state.memory_injection
   - INIT node reads memory_injection from state and appends to system prompt
   - Visible in LangGraph traces, resume-safe (node already ran)
   - Graph: START → MEMORY_RECALL → INIT → AGENT ↔ TOOLS → TERMINATE → END

2. Escalation memory (tool-level):
   - Before creating HITL task: escalation_search_async() checks for cached answer
   - Cache hit → returns cached result immediately, skips human escalation
   - After human resolution: escalation_ingest_async() persists outcome
   - Gated by isAgentMemoryEnabled + memorySpaceId on the escalation resource

New types:
- MemoryConfig: configuration dataclass (memory_space_id, folder_key, etc.)
- AgentGraphNode.MEMORY_RECALL: new graph node enum value
- InnerAgentGraphState.memory_injection: carries injection through state

Dependency: bumps uipath-platform >= 0.1.31 for MemoryService types (PR #1467)

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.49, <2.11.0",
     "uipath-core>=0.5.2, <0.6.0",
-    "uipath-platform>=0.1.30, <0.2.0",
+    "uipath-platform>=0.1.31, <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/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)
+        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

@@ -24,6 +24,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,113 @@
+"""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 typing import Any
+
+from uipath.platform import UiPath
+from uipath.platform.memory import (
+    FieldSettings,
+    MemorySearchRequest,
+    SearchField,
+    SearchMode,
+    SearchSettings,
+)
+
+from .types import AgentGraphState, MemoryConfig
+
+logger = logging.getLogger(__name__)
+
+
+def create_memory_recall_node(
+    memory_config: MemoryConfig,
+):
+    """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: AgentGraphState) -> dict[str, Any]:
+        input_arguments = _extract_user_inputs(state)
+        if not input_arguments:
+            return {}
+
+        fields = _build_search_fields(input_arguments)
+        if not fields:
+            return {}
+
+        request = MemorySearchRequest(
+            fields=fields,
+            settings=SearchSettings(
+                threshold=memory_config.threshold,
+                result_count=memory_config.result_count,
+                search_mode=SearchMode.Hybrid,
+            ),
+        )
+
+        try:
+            sdk = UiPath()
+            response = await sdk.memory.search_async(
+                memory_space_id=memory_config.memory_space_id,
+                request=request,
+                folder_key=memory_config.folder_key,
+            )
+            injection = response.system_prompt_injection
+            logger.info(
+                "Memory recall returned %d results for space '%s'",
+                len(response.results),
+                memory_config.memory_space_id,
+            )
+        except Exception:
+            logger.warning(
+                "Memory recall failed for space '%s', continuing without injection",
+                memory_config.memory_space_id,
+                exc_info=True,
+            )
+            injection = ""
+
+        if not injection:
+            return {}
+
+        return {"inner_state": {"memory_injection": injection}}
+
+    return memory_recall_node
+
+
+def _extract_user_inputs(state: AgentGraphState) -> dict[str, Any]:
+    """Extract user-defined input fields from graph state, excluding internal fields."""
+    internal_fields = set(AgentGraphState.model_fields.keys())
+    if isinstance(state, dict):
+        return {k: v for k, v in state.items() if k not in internal_fields}
+    return {
+        k: v
+        for k, v in state.model_dump().items()
+        if k not in internal_fields and v is not None
+    }
+
+
+def _build_search_fields(
+    input_arguments: dict[str, Any],
+    field_weights: dict[str, float] | None = None,
+) -> list[SearchField]:
+    """Convert agent input arguments to SearchField objects."""
+    fields: list[SearchField] = []
+    for name, value in input_arguments.items():
+        if value is None or name.startswith("uipath__"):
+            continue
+        settings = FieldSettings()
+        if field_weights and name in field_weights:
+            settings = FieldSettings(weight=field_weights[name])
+        fields.append(SearchField(key_path=[name], value=str(value), settings=settings))
+    return fields

src/uipath_langchain/agent/react/types.py

@@ -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,23 @@ 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.")
+    folder_key: str | None = Field(
+        default=None, description="Folder key for the memory resource."
+    )
+    result_count: int = Field(default=5, ge=1, le=10)
+    threshold: float = Field(default=0.0, ge=0.0, le=1.0)
 
 
 class AgentGraphConfig(BaseModel):

src/uipath_langchain/agent/tools/escalation_tool.py

@@ -1,5 +1,7 @@
 """Escalation tool creation for Action Center integration."""
 
+import json
+import logging
 from enum import Enum
 from typing import Any, Literal
 
@@ -39,6 +41,8 @@
     sanitize_tool_name,
 )
 
+_escalation_logger = logging.getLogger(__name__)
+
 
 class EscalationAction(str, Enum):
     """Actions that can be taken after an escalation completes."""
@@ -161,6 +165,17 @@ def _parse_task_data(
     return filtered_fields
 
 
+def _get_escalation_memory_space_id(
+    resource: AgentEscalationResourceConfig,
+) -> str | None:
+    """Resolve memory space ID from escalation resource extra fields."""
+    if not resource.is_agent_memory_enabled:
+        return None
+    return getattr(resource, "memorySpaceId", None) or getattr(
+        resource, "memory_space_id", None
+    )
+
+
 def create_escalation_tool(
     resource: AgentEscalationResourceConfig,
 ) -> StructuredTool:
@@ -178,6 +193,7 @@ class EscalationToolOutput(BaseModel):
         is_deleted: bool = False
 
     _bts_context: dict[str, Any] = {}
+    _memory_space_id: str | None = _get_escalation_memory_space_id(resource)
 
     async def escalation_tool_fn(**kwargs: Any) -> dict[str, Any]:
         agent_input: dict[str, Any] = (
@@ -198,6 +214,13 @@ async def escalation_tool_fn(**kwargs: Any) -> dict[str, Any]:
 
         serialized_data = input_model.model_validate(kwargs).model_dump(mode="json")
 
+        # --- Escalation memory: check cache before creating HITL task ---
+        cached_result = await _check_escalation_memory_cache(
+            _memory_space_id, serialized_data
+        )
+        if cached_result is not None:
+            return cached_result
+
         @mockable(
             name=tool_name.lower(),
             description=resource.description,
@@ -262,6 +285,13 @@ async def create_escalation_task():
             EscalationAction(outcome_str) if outcome_str else EscalationAction.CONTINUE
         )
 
+        # --- Escalation memory: persist outcome for future recall ---
+        await _ingest_escalation_memory(
+            _memory_space_id,
+            answer=json.dumps(escalation_output),
+            attributes=json.dumps(serialized_data),
+        )
+
         return {
             "action": escalation_action,
             "output": escalation_output,
@@ -333,3 +363,98 @@ async def escalation_wrapper(
     tool.set_tool_wrappers(awrapper=escalation_wrapper)
 
     return tool
+
+
+# --- Escalation memory helpers ---
+
+
+async def _check_escalation_memory_cache(
+    memory_space_id: str | None,
+    serialized_input: dict[str, Any],
+) -> dict[str, Any] | None:
+    """Check escalation memory for a cached answer.
+
+    Returns the cached result dict if found, None otherwise.
+    """
+    if not memory_space_id:
+        return None
+
+    try:
+        from uipath.platform.memory import (
+            MemorySearchRequest,
+            SearchField,
+            SearchMode,
+            SearchSettings,
+        )
+
+        fields = [
+            SearchField(key_path=[k], value=str(v))
+            for k, v in serialized_input.items()
+            if v is not None
+        ]
+        if not fields:
+            return None
+
+        request = MemorySearchRequest(
+            fields=fields,
+            settings=SearchSettings(
+                threshold=0.0, result_count=1, search_mode=SearchMode.Hybrid
+            ),
+        )
+        sdk = UiPath()
+        response = await sdk.memory.escalation_search_async(
+            memory_space_id=memory_space_id, request=request
+        )
+        if response.results and response.results[0].answer:
+            cached = response.results[0].answer
+            _escalation_logger.info(
+                "Escalation memory cache hit for space '%s'", memory_space_id
+            )
+            return {
+                "action": EscalationAction.CONTINUE,
+                "output": cached.output,
+                "outcome": cached.outcome or "cached",
+            }
+    except Exception:
+        _escalation_logger.warning(
+            "Escalation memory search failed for space '%s'",
+            memory_space_id,
+            exc_info=True,
+        )
+
+    return None
+
+
+async def _ingest_escalation_memory(
+    memory_space_id: str | None,
+    answer: str,
+    attributes: str,
+    span_id: str = "",
+    trace_id: str = "",
+) -> None:
+    """Persist a resolved escalation outcome into memory."""
+    if not memory_space_id:
+        return
+
+    try:
+        from uipath.platform.memory import EscalationMemoryIngestRequest
+
+        request = EscalationMemoryIngestRequest(
+            span_id=span_id or "unknown",
+            trace_id=trace_id or "unknown",
+            answer=answer,
+            attributes=attributes,
+        )
+        sdk = UiPath()
+        await sdk.memory.escalation_ingest_async(
+            memory_space_id=memory_space_id, request=request
+        )
+        _escalation_logger.info(
+            "Ingested escalation outcome into memory space '%s'", memory_space_id
+        )
+    except Exception:
+        _escalation_logger.warning(
+            "Failed to ingest escalation outcome into memory space '%s'",
+            memory_space_id,
+            exc_info=True,
+        )