xpander-sdk 2.0.415__tar.gz → 2.0.417__tar.gz

{xpander_sdk-2.0.415/src/xpander_sdk.egg-info → xpander_sdk-2.0.417}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.415
+Version: 2.0.417
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.415 → xpander_sdk-2.0.417}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.415",
+    version="2.0.417",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",

{xpander_sdk-2.0.415 → xpander_sdk-2.0.417}/src/xpander_sdk/__init__.py

@@ -15,7 +15,7 @@ Main Components:
 For more information, visit: https://xpander.ai
 """
 
-__version__ = "2.0.415"
+__version__ = "2.0.417"
 
 # Backend-related imports
 from .modules.backend.backend_module import Backend

{xpander_sdk-2.0.415 → xpander_sdk-2.0.417}/src/xpander_sdk/consts/api_routes.py

@@ -72,6 +72,9 @@ class APIRoute(str, Enum):
     # Agentic context
     GetOrSetAgenticContext = "/agentic_context/{agent_id}"
 
+    # User/agent memories
+    UserMemories = "/memories/{agent_id}"
+
     # Workspace
     WorkspaceToolInvoke = "/workspace/{agent_id}/tools/{tool_name}"
 

{xpander_sdk-2.0.415 → xpander_sdk-2.0.417}/src/xpander_sdk/core/context_optimizer/finalize_mode.py

@@ -177,9 +177,7 @@ def build_finalize_tool(task: Any) -> Any:
     async def _entrypoint(
         payload: Optional[Union[Dict[str, Any], str]] = None,
     ) -> str:
-        # LLMs sometimes emit the payload as a JSON string; validate_call
-        # accepts it via the Union, we parse here. An unparseable string is
-        # kept as the final answer — finalize must terminate, never bounce.
+        """Finalize the task; string payloads are parsed, unparseable ones become the final answer (finalize must terminate, never bounce)."""
         if isinstance(payload, str):
             parsed = parse_structured_string(payload)
             payload = parsed if isinstance(parsed, dict) else {"final_answer": payload}
@@ -276,11 +274,7 @@ async def _run_finalize(
             and getattr(task, "deep_planning", None)
             and task.deep_planning.tasks
         ):
-            # Soft evidence gate: when the ledger recorded tool calls and every
-            # single one failed, the LLM's completed_items claim is fabricated —
-            # keep the items open and say so instead of rendering a green plan.
-            # An absent/empty ledger can't distinguish "no tools needed" from
-            # "ledger disabled", so it never blocks.
+            # Soft gate: every recorded call failed -> the completion claim is fabricated; an absent/empty ledger never blocks.
             ledger = get_attached_ledger(task)
             all_calls_failed = bool(
                 ledger

{xpander_sdk-2.0.415 → xpander_sdk-2.0.417}/src/xpander_sdk/models/frameworks.py

@@ -43,9 +43,9 @@ class AgnoSettings(BaseModel):
 
     learning: Optional[bool] = False
 
+    # deprecated: agno memory machinery replaced by the xpander memory layer; kept for wire compat, ignored at runtime
     user_memories: Optional[bool] = False
     agentic_memory: Optional[bool] = False
-
     agent_memories: Optional[bool] = False
     agentic_culture: Optional[bool] = False
 

{xpander_sdk-2.0.415 → xpander_sdk-2.0.417}/src/xpander_sdk/modules/backend/frameworks/agno.py

@@ -1,6 +1,7 @@
 import asyncio
 import hashlib
 import json
+import re
 import shlex
 import uuid
 from collections import deque
@@ -123,7 +124,6 @@ from xpander_sdk.modules.tools_repository.utils.workspace_payload import (
 )
 from agno.agent import Agent as AgnoAgent
 from agno.team import Team as AgnoTeam
-from agno.memory import MemoryManager
 from agno.guardrails import PIIDetectionGuardrail
 from agno.guardrails import PromptInjectionGuardrail
 from agno.guardrails import OpenAIModerationGuardrail
@@ -549,8 +549,7 @@ def _build_compact_tool():
     from agno.tools.function import Function
 
     def _entrypoint(payload: Optional[Union[Dict[str, Any], str]] = None) -> str:
-        # Stringified payloads are accepted (Union) and parsed here so a
-        # malformed emission never fails the compaction request itself.
+        """Schedule compaction; stringified payloads are parsed so a malformed emission never fails the request."""
         if isinstance(payload, str):
             parsed = parse_structured_string(payload)
             payload = parsed if isinstance(parsed, dict) else {}
@@ -624,7 +623,10 @@ def reenvelope_sibling_args(arguments: Dict[str, Any]) -> bool:
         return False
     envelope = dict(payload_val) if isinstance(payload_val, dict) else {}
     for key in [k for k in list(arguments) if k != "payload"]:
-        envelope.setdefault(key, arguments.pop(key))
+        sibling = arguments.pop(key)
+        # A real payload value wins; an empty placeholder ({}/None/"") loses to a non-empty sibling.
+        if key not in envelope or (not envelope.get(key) and sibling):
+            envelope[key] = sibling
     arguments["payload"] = envelope
     return True
 
@@ -992,13 +994,13 @@ async def build_agent_args(
 
     _configure_output(args=args, agent=xpander_agent, task=task)
     _configure_session_storage(args=args, agent=xpander_agent, task=task)
-    _configure_agentic_memory(args=args, agent=xpander_agent, task=task)
     _configure_context_optimizer(args=args, agent=xpander_agent, task=task, model=model)
 
     # The deps leg (DB fetch + the sync configures that override its args keys —
     # order preserved) is independent of tool/MCP resolution, so overlap them: on a
     # cold agent this runs the conn-string fetch concurrently with the MCP probes.
     async def _attach_deps_leg() -> None:
+        await _configure_user_memories(args=args, agent=xpander_agent, task=task)
         await _attach_async_dependencies(
             args=args, agent=xpander_agent, task=task, model=model, is_async=is_async
         )
@@ -1040,6 +1042,11 @@ async def build_agent_args(
     if tools and len(tools) != 0:
         args["tools"].extend(tools)
 
+    _mem_user = task.input.user if task and task.input else None
+    _mem_enabled = args.pop("_xpander_memory_enabled", True)
+    if task and _mem_user and _mem_user.id and not xpander_agent.is_a_team and _mem_enabled:
+        args["tools"].append(_build_memory_tool(xpander_agent, task))
+
     # Inline agent-gateway children (and any non-DP task) must not see the planning
     # tool family — hide it so the agent can't call it.
     _strip_planning_tools_if_inactive(args=args, agent=xpander_agent, task=task)
@@ -3220,42 +3227,229 @@ def _configure_session_storage(
         args["max_tool_calls_from_history"] = max_tool_calls
 
 
-def _configure_agentic_memory(
-    args: Dict[str, Any], agent: Agent, task: Optional[Task]
-) -> None:
-    learning_enabled = True if agent.agno_settings.learning else False
-    user = task.input.user if task and task.input and task.input.user else None
-    # omni and autonomous agents get user memories automatically, no explicit opt-in needed
-    memories_requested = (
-        agent.agno_settings.user_memories or agent.is_omni or agent.is_autonomous
-    )
-    user_memories_enabled = True if memories_requested and user and user.id else False
-    agent_memories_enabled = True if agent.agno_settings.agent_memories else False
+MEMORY_MAX_CHARS = 300
+_MEMORY_FETCH_TIMEOUT_S = 1.5
+_MEMORY_PERSIST_TIMEOUT_S = 10
+_MEMORY_SCOPES = {"user", "agent"}
+_MEMORY_ACTIONS = {"save": "Saved.", "update": "Updated.", "delete": "Deleted."}
 
-    if learning_enabled:
-        args["learning"] = True
 
-    # fully agentic: the LLM manages memories via the agno memory tool; no automatic
-    # post-run extraction (enable_user_memories / update_memory_on_run is intentionally off)
-    if user_memories_enabled:
-        args["memory_manager"] = MemoryManager(
-            delete_memories=True, clear_memories=True
-        )
+def _sanitize_memory(text: Any) -> str:
+    """One-line, tag-free memory text: a stored `</memories>` would otherwise close the
+    context block and turn a memory into free-standing instructions for every later run."""
+    cleaned = re.sub(r"[<>]", "", str(text or ""))
+    return re.sub(r"\s+", " ", cleaned).strip()[:MEMORY_MAX_CHARS]
 
-    if (user_memories_enabled or agent_memories_enabled) and not agent.is_a_team:
-        args["enable_agentic_memory"] = True
 
-    if agent_memories_enabled and not agent.is_a_team:
-        args["add_culture_to_context"] = True
+def _render_memories_block(bundle: Dict[str, Any]) -> str:
+    """Render the xpander memories bundle as the context block, or "" when empty."""
+    if not bool((bundle.get("settings") or {}).get("enabled", True)):
+        return ""
+    user_rows = bundle.get("user") or []
+    agent_rows = bundle.get("agent") or []
+    if not user_rows and not agent_rows:
+        return ""
 
-        if agent.agno_settings.agentic_culture:
-            args["enable_agentic_culture"] = True
-        else:
-            args["update_cultural_knowledge"] = True
+    def _lines(rows: List[Dict[str, Any]], with_writer: bool) -> List[str]:
+        out = []
+        for row in rows:
+            mem_id = str(row.get("memory_id", ""))[:8]
+            date = str(row.get("updated_at", ""))[:10]
+            writer = _sanitize_memory(row.get("writer_agent_name"))
+            meta = f"by {writer}, {date}" if with_writer and writer else date
+            out.append(f"- [{mem_id}] ({meta}) {_sanitize_memory(row.get('memory'))}")
+        return out
+
+    parts = [
+        '<memories note="Durable memories. Do not re-save facts already listed; '
+        'use manage_memory with the id to update or delete.">'
+    ]
+    if user_rows:
+        parts.append("USER (about this user, shared across all agents):")
+        parts.extend(_lines(user_rows, with_writer=True))
+    if agent_rows:
+        parts.append("AGENT (this agent's own knowledge, all users):")
+        parts.extend(_lines(agent_rows, with_writer=False))
+    parts.append("</memories>")
+    return "\n".join(parts)
+
+
+def _build_memory_tool(agent: Agent, task: Task) -> Any:
+    """Build the ``manage_memory`` agno Function (save/update/delete, fire-and-forget)."""
+    from agno.tools.function import Function
+
+    from xpander_sdk.consts.api_routes import APIRoute
+    from xpander_sdk.core.xpander_api_client import APIClient
+
+    user = task.input.user if task.input else None
+    user_id = user.id if user else None
+    path = APIRoute.UserMemories.value.format(agent_id=agent.id)
 
-    if user:  # add user details to the agent
+    async def _persist(body: Dict[str, Any]) -> None:
+        # contained + bounded: an unretrieved raise_for_status would otherwise surface as
+        # "Task exception was never retrieved", and the client default timeout is 20 min
+        try:
+            client = APIClient(configuration=agent.configuration)
+            await asyncio.wait_for(
+                client.make_request(path=path, method="POST", payload=body),
+                timeout=_MEMORY_PERSIST_TIMEOUT_S,
+            )
+        except Exception as e:
+            logger.debug(f"[memories] persist failed for agent {agent.id}: {e}")
+
+    def _entrypoint(payload: Optional[Union[Dict[str, Any], str]] = None) -> str:
+        """Persist a memory operation in the background and return immediately."""
+        if isinstance(payload, str):
+            parsed = parse_structured_string(payload)
+            payload = parsed if isinstance(parsed, dict) else {}
+        payload = payload or {}
+        action = str(payload.get("action", "")).lower()
+        scope = str(payload.get("scope", "user")).lower()
+        memory = _sanitize_memory(payload.get("memory"))
+        memory_id = str(payload.get("memory_id") or "").strip()
+
+        if action not in _MEMORY_ACTIONS:
+            return "Invalid action: use save, update or delete."
+        if scope not in _MEMORY_SCOPES:
+            return "Invalid scope: use user or agent."
+        if action in {"save", "update"} and not memory:
+            return "Missing memory text."
+        if action in {"update", "delete"} and not memory_id:
+            return "Missing memory_id (use the id shown in <memories>)."
+        if scope == "user" and not user_id:
+            return "No user on this run; only agent scope is available."
+
+        body = {
+            "action": action,
+            "scope": scope,
+            "memory": memory or None,
+            "memory_id": memory_id or None,
+            "user_id": user_id,
+            "writer_agent_id": agent.id,
+            "writer_agent_name": getattr(agent, "name", None) or agent.id,
+        }
+        coro = _persist(body)
+        try:
+            _spawn_bg(coro)
+        except RuntimeError:
+            # sync entrypoint path (backend.get_args + Agent.run): no running loop here
+            run_sync(coro)
+        return _MEMORY_ACTIONS[action]
+
+    return Function(
+        name="manage_memory",
+        description=(
+            "Persist durable memories without being asked. save: the user reveals a stable "
+            "fact or preference (scope 'user': about the person, shared across ALL their "
+            "agents - role, team, how they like answers) or you learn user-agnostic knowledge "
+            "this agent should keep (scope 'agent', visible to every user of this agent). "
+            "ESPECIALLY save scope 'agent' when you overcome an issue: after failed attempts "
+            "you found the approach that works (right flag, endpoint, workaround, ordering) - "
+            "save the lesson so future runs skip the dead ends. "
+            "update/delete: a listed memory changed or the user asks to forget it - pass its "
+            "memory_id from <memories>. BEFORE saving, reason whether it is WORTH saving: "
+            "would this still matter in a month, on unrelated tasks? If not, do not save. "
+            "The current request itself is NEVER a memory - 'save/export my memories to a "
+            "file', 'summarize this doc', 'send this email' are tasks to PERFORM, not facts "
+            "to remember. Keep memories short (one concise sentence, max "
+            f"{MEMORY_MAX_CHARS} chars). Never store secrets, credentials, or one-off task "
+            "details. Do not re-save facts already listed in <memories>. "
+            "Wrap arguments in a `payload` object."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "payload": {
+                    "type": "object",
+                    "properties": {
+                        "action": {
+                            "type": "string",
+                            "enum": ["save", "update", "delete"],
+                        },
+                        "scope": {
+                            "type": "string",
+                            "enum": ["user", "agent"],
+                            "description": "user = about this person, cross-agent. agent = this agent's own knowledge, all users.",
+                        },
+                        "memory": {
+                            "type": "string",
+                            "description": "The memory text (save/update). One short sentence.",
+                        },
+                        "memory_id": {
+                            "type": "string",
+                            "description": "Id from the <memories> block (update/delete).",
+                        },
+                        "headers": {
+                            "type": "object",
+                            "properties": {
+                                "toolcallreasoningtitle": {
+                                    "type": "string",
+                                    "description": 'Action-oriented title (max 5 words). Example: "Remember user preference".',
+                                },
+                                "toolcallreasoningdescription": {
+                                    "type": "string",
+                                    "description": 'One-sentence summary (max 100 characters). Example: "Save that the user prefers Hebrew answers."',
+                                },
+                            },
+                            "required": [
+                                "toolcallreasoningtitle",
+                                "toolcallreasoningdescription",
+                            ],
+                        },
+                    },
+                    "required": ["action", "scope", "headers"],
+                },
+            },
+            "required": ["payload"],
+        },
+        entrypoint=_entrypoint,
+    )
+
+
+async def _configure_user_memories(
+    args: Dict[str, Any], agent: Agent, task: Optional[Task]
+) -> None:
+    """Wire the xpander memory layer: prepend the <memories> block + inject manage_memory."""
+    if agent.agno_settings.learning:
+        args["learning"] = True
+
+    user = task.input.user if task and task.input and task.input.user else None
+    if user:
         args["additional_context"] = f"User details: {user.model_dump_json()}"
 
+    if not task or agent.is_a_team:
+        return
+
+    block = ""
+    # the gateway prepends the block into dispatched children's additional_context;
+    # fetching again would duplicate it and waste a round-trip
+    gateway_passed = "<memories note=" in (task.additional_context or "")
+    if not gateway_passed and (user and user.id):
+        try:
+            from xpander_sdk.consts.api_routes import APIRoute
+            from xpander_sdk.core.xpander_api_client import APIClient
+
+            client = APIClient(configuration=agent.configuration)
+            bundle = await asyncio.wait_for(
+                client.make_request(
+                    path=APIRoute.UserMemories.value.format(agent_id=agent.id),
+                    query={"user_id": user.id},
+                ),
+                timeout=_MEMORY_FETCH_TIMEOUT_S,
+            )
+            if isinstance(bundle, dict):
+                block = _render_memories_block(bundle)
+                # honor the user's master toggle: no block AND no save tool when off
+                args["_xpander_memory_enabled"] = bool(
+                    (bundle.get("settings") or {}).get("enabled", True)
+                )
+        except Exception as e:
+            logger.debug(f"[memories] fetch skipped for agent {agent.id}: {e}")
+
+    if block:
+        existing = args.get("additional_context", "")
+        args["additional_context"] = f"{block}\n\n{existing}" if existing else block
+
 
 async def _attach_async_dependencies(
     args: Dict[str, Any],
@@ -3264,17 +3458,7 @@ async def _attach_async_dependencies(
     model: Any,
     is_async: Optional[bool] = True,
 ) -> None:
-    user = task.input.user if task and task.input and task.input.user else None
-    memories_requested = (
-        agent.agno_settings.user_memories or agent.is_omni or agent.is_autonomous
-    )
-    should_use_db = (
-        True
-        if (memories_requested and user and user.id)
-        or agent.agno_settings.agent_memories
-        else False
-    )
-    if agent.agno_settings.session_storage or should_use_db:
+    if agent.agno_settings.session_storage:
         args["db"] = await agent.aget_db(async_db=is_async)
 
 

{xpander_sdk-2.0.415 → xpander_sdk-2.0.417}/src/xpander_sdk/modules/tools_repository/utils/schemas.py

@@ -28,7 +28,7 @@ class _CoercingPayloadBase(BaseModel):
 
     @model_validator(mode="before")
     @classmethod
-    def _coerce_string_payload(cls, data):
+    def _coerce_string_payload(cls, data: Any) -> Any:
         if isinstance(data, str):
             parsed = parse_structured_string(data)
             if isinstance(parsed, dict):

{xpander_sdk-2.0.415 → xpander_sdk-2.0.417/src/xpander_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.415
+Version: 2.0.417
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI