haystack-experimental 0.16.0__py3-none-any.whl → 0.17.0__py3-none-any.whl

haystack_experimental/components/agents/agent.py

@@ -57,6 +57,7 @@ from haystack_experimental.components.agents.human_in_the_loop.strategies import
 )
 from haystack_experimental.components.retrievers import ChatMessageRetriever
 from haystack_experimental.components.writers import ChatMessageWriter
+from haystack_experimental.memory_stores.types import MemoryStore
 
 logger = logging.getLogger(__name__)
 
@@ -146,6 +147,7 @@ class Agent(HaystackAgent):
         confirmation_strategies: dict[str, ConfirmationStrategy] | None = None,
         tool_invoker_kwargs: dict[str, Any] | None = None,
         chat_message_store: ChatMessageStore | None = None,
+        memory_store: MemoryStore | None = None,
     ) -> None:
         """
         Initialize the agent component.
@@ -164,6 +166,9 @@ class Agent(HaystackAgent):
         :param raise_on_tool_invocation_failure: Should the agent raise an exception when a tool invocation fails?
             If set to False, the exception will be turned into a chat message and passed to the LLM.
         :param tool_invoker_kwargs: Additional keyword arguments to pass to the ToolInvoker.
+        :param chat_message_store: The ChatMessageStore that the agent can use to store
+            and retrieve chat messages history.
+        :param memory_store: The memory store that the agent can use to store and retrieve memories.
         :raises TypeError: If the chat_generator does not support tools parameter in its run method.
         :raises ValueError: If the exit_conditions are not valid.
         """
@@ -186,6 +191,7 @@ class Agent(HaystackAgent):
         self._chat_message_writer = (
             ChatMessageWriter(chat_message_store=chat_message_store) if chat_message_store else None
         )
+        self._memory_store = memory_store
 
     def _initialize_fresh_execution(
         self,
@@ -198,6 +204,7 @@ class Agent(HaystackAgent):
         tools: ToolsType | list[str] | None = None,
         confirmation_strategy_context: dict[str, Any] | None = None,
         chat_message_store_kwargs: dict[str, Any] | None = None,
+        memory_store_kwargs: dict[str, Any] | None = None,
         **kwargs: dict[str, Any],
     ) -> _ExecutionContext:
         """
@@ -209,29 +216,62 @@ class Agent(HaystackAgent):
         :param system_prompt: System prompt for the agent. If provided, it overrides the default system prompt.
         :param tools: Optional list of Tool objects, a Toolset, or list of tool names to use for this run.
             When passing tool names, tools are selected from the Agent's originally configured tools.
+
+        :param memory_store_kwargs: Optional dictionary of keyword arguments to pass to the MemoryStore.
+            For example, it can include the `user_id`, `run_id`, and `agent_id` parameters
+            for storing and retrieving memories.
         :param confirmation_strategy_context: Optional dictionary for passing request-scoped resources
             to confirmation strategies.
         :param chat_message_store_kwargs: Optional dictionary of keyword arguments to pass to the ChatMessageStore.
+            For example, it can include the `chat_history_id` and `last_k` parameters for retrieving chat history.
         :param kwargs: Additional data to pass to the State used by the Agent.
         """
         system_prompt = system_prompt or self.system_prompt
-        if system_prompt is not None:
-            messages = [ChatMessage.from_system(system_prompt)] + messages
+        retrieved_memory = None
+        updated_system_prompt = system_prompt
+
+        # Retrieve memories from the memory store
+        if self._memory_store:
+            retrieved_memories = self._memory_store.search_memories(query=messages[-1].text, **memory_store_kwargs)  # type: ignore[arg-type]
+
+            # we combine the memories into a single string
+            combined_memory = "\n".join(
+                f"- MEMORY #{idx + 1}: {memory.text}" for idx, memory in enumerate(retrieved_memories)
+            )
+            retrieved_memory = ChatMessage.from_system(text=combined_memory)
+
+        if retrieved_memory:
+            memory_instruction = (
+                "\n\nWhen messages start with `[MEMORY]`, treat them as long-term "
+                "context and use them to guide the response if relevant."
+            )
+            updated_system_prompt = f"{system_prompt}{memory_instruction}"
+
+            memory_text = f"Here are the relevant memories for the user's query: {retrieved_memory.text}"
+            print(memory_text)
+            updated_memory = ChatMessage.from_system(text=memory_text)
+        else:
+            updated_memory = None
+
+        combined_messages = messages + [updated_memory] if updated_memory else messages
+        if updated_system_prompt is not None:
+            combined_messages = [ChatMessage.from_system(updated_system_prompt)] + combined_messages
 
         # NOTE: difference with parent method to add chat message retrieval
         if self._chat_message_retriever:
             retriever_kwargs = _select_kwargs(self._chat_message_retriever, chat_message_store_kwargs or {})
             if "chat_history_id" in retriever_kwargs:
                 messages = self._chat_message_retriever.run(
-                    current_messages=messages,
+                    current_messages=combined_messages,
                     **retriever_kwargs,
                 )["messages"]
+                combined_messages = messages
 
-        if all(m.is_from(ChatRole.SYSTEM) for m in messages):
+        if all(m.is_from(ChatRole.SYSTEM) for m in combined_messages):
             logger.warning("All messages provided to the Agent component are system messages. This is not recommended.")
 
         state = State(schema=self.state_schema, data=kwargs)
-        state.set("messages", messages)
+        state.set("messages", combined_messages)
 
         streaming_callback = select_streaming_callback(  # type: ignore[call-overload]
             init_callback=self.streaming_callback, runtime_callback=streaming_callback, requires_async=requires_async
@@ -329,6 +369,7 @@ class Agent(HaystackAgent):
         tools: ToolsType | list[str] | None = None,
         confirmation_strategy_context: dict[str, Any] | None = None,
         chat_message_store_kwargs: dict[str, Any] | None = None,
+        memory_store_kwargs: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
@@ -352,6 +393,19 @@ class Agent(HaystackAgent):
             can use for non-blocking user interaction.
         :param chat_message_store_kwargs: Optional dictionary of keyword arguments to pass to the ChatMessageStore.
             For example, it can include the `chat_history_id` and `last_k` parameters for retrieving chat history.
+        :param memory_store_kwargs: Optional dictionary of keyword arguments to pass to the MemoryStore.
+            It can include:
+            - `user_id`: The user ID to search and add memories from.
+            - `run_id`: The run ID to search and add memories from.
+            - `agent_id`: The agent ID to search and add memories from.
+            - `search_criteria`: A dictionary of containing kwargs for the `search_memories` method.
+                This can include:
+                - `filters`: A dictionary of filters to search for memories.
+                - `query`: The query to search for memories.
+                    Note: If you pass this, the user query passed to the agent will be
+                    ignored for memory retrieval.
+                - `top_k`: The number of memories to return.
+                - `include_memory_metadata`: Whether to include the memory metadata in the ChatMessage.
         :param kwargs: Additional data to pass to the State schema used by the Agent.
             The keys must match the schema defined in the Agent's `state_schema`.
         :returns:
@@ -362,6 +416,8 @@ class Agent(HaystackAgent):
         :raises RuntimeError: If the Agent component wasn't warmed up before calling `run()`.
         :raises BreakpointException: If an agent breakpoint is triggered.
         """
+        memory_store_kwargs = memory_store_kwargs or {}
+
         agent_inputs = {
             "messages": messages,
             "streaming_callback": streaming_callback,
@@ -392,6 +448,7 @@ class Agent(HaystackAgent):
                 tools=tools,
                 confirmation_strategy_context=confirmation_strategy_context,
                 chat_message_store_kwargs=chat_message_store_kwargs,
+                memory_store_kwargs=memory_store_kwargs,
                 **kwargs,
             )
 
@@ -547,6 +604,11 @@ class Agent(HaystackAgent):
         if msgs := result.get("messages"):
             result["last_message"] = msgs[-1]
 
+            # Add the new conversation as memories to the memory store
+            if self._memory_store:
+                new_memories = [message for message in msgs if message.role.value != "system"]
+                self._memory_store.add_memories(messages=new_memories, **memory_store_kwargs)
+
         # Write messages to ChatMessageStore if configured
         if self._chat_message_writer:
             writer_kwargs = _select_kwargs(self._chat_message_writer, chat_message_store_kwargs or {})
@@ -567,6 +629,7 @@ class Agent(HaystackAgent):
         tools: ToolsType | list[str] | None = None,
         confirmation_strategy_context: dict[str, Any] | None = None,
         chat_message_store_kwargs: dict[str, Any] | None = None,
+        memory_store_kwargs: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
@@ -593,6 +656,20 @@ class Agent(HaystackAgent):
             can use for non-blocking user interaction.
         :param chat_message_store_kwargs: Optional dictionary of keyword arguments to pass to the ChatMessageStore.
             For example, it can include the `chat_history_id` and `last_k` parameters for retrieving chat history.
+        :param kwargs: Additional data to pass to the State schema used by the Agent.
+        :param memory_store_kwargs: Optional dictionary of keyword arguments to pass to the MemoryStore.
+            It can include:
+            - `user_id`: The user ID to search and add memories from.
+            - `run_id`: The run ID to search and add memories from.
+            - `agent_id`: The agent ID to search and add memories from.
+            - `search_criteria`: A dictionary of containing kwargs for the `search_memories` method.
+                This can include:
+                - `filters`: A dictionary of filters to search for memories.
+                - `query`: The query to search for memories.
+                    Note: If you pass this, the user query passed to the agent will be
+                    ignored for memory retrieval.
+                - `top_k`: The number of memories to return.
+                - `include_memory_metadata`: Whether to include the memory metadata in the ChatMessage.
         :param kwargs: Additional data to pass to the State schema used by the Agent.
             The keys must match the schema defined in the Agent's `state_schema`.
         :returns:
@@ -603,6 +680,8 @@ class Agent(HaystackAgent):
         :raises RuntimeError: If the Agent component wasn't warmed up before calling `run_async()`.
         :raises BreakpointException: If an agent breakpoint is triggered.
         """
+        memory_store_kwargs = memory_store_kwargs or {}
+
         agent_inputs = {
             "messages": messages,
             "streaming_callback": streaming_callback,
@@ -631,6 +710,7 @@ class Agent(HaystackAgent):
                 tools=tools,
                 confirmation_strategy_context=confirmation_strategy_context,
                 chat_message_store_kwargs=chat_message_store_kwargs,
+                memory_store_kwargs=memory_store_kwargs,
                 **kwargs,
             )
 
@@ -773,6 +853,11 @@ class Agent(HaystackAgent):
         if msgs := result.get("messages"):
             result["last_message"] = msgs[-1]
 
+            # Add the new conversation as memories to the memory store
+            if self._memory_store:
+                new_memories = [message for message in msgs if message.role.value != "system"]
+                self._memory_store.add_memories(messages=new_memories, **memory_store_kwargs)
+
         # Write messages to ChatMessageStore if configured
         if self._chat_message_writer:
             writer_kwargs = _select_kwargs(self._chat_message_writer, chat_message_store_kwargs or {})

haystack_experimental/memory_stores/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .types import MemoryStore
+
+__all__ = ["MemoryStore"]

haystack_experimental/memory_stores/mem0/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import sys
+from typing import TYPE_CHECKING
+
+from lazy_imports import LazyImporter
+
+_import_structure = {"memory_store": ["Mem0MemoryStore"]}
+
+if TYPE_CHECKING:
+    from .memory_store import Mem0MemoryStore as Mem0MemoryStore
+
+else:
+    sys.modules[__name__] = LazyImporter(name=__name__, module_file=__file__, import_structure=_import_structure)

haystack_experimental/memory_stores/mem0/memory_store.py

@@ -0,0 +1,323 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import default_from_dict, default_to_dict, logging
+from haystack.dataclasses.chat_message import ChatMessage
+from haystack.lazy_imports import LazyImport
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+with LazyImport(message="Run 'pip install mem0ai'") as mem0_import:
+    from mem0 import MemoryClient  # pylint: disable=import-error
+
+logger = logging.getLogger(__name__)
+
+
+class Mem0MemoryStore:
+    """
+    A memory store implementation using Mem0 as the backend.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Secret = Secret.from_env_var("MEM0_API_KEY"),
+    ):
+        """
+        Initialize the Mem0 memory store.
+
+        :param api_key: The Mem0 API key. You can also set it using `MEM0_API_KEY` environment variable.
+        """
+
+        mem0_import.check()
+        self.api_key = api_key
+        self.client = MemoryClient(
+            api_key=self.api_key.resolve_value(),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the store configuration to a dictionary."""
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Mem0MemoryStore":
+        """Deserialize the store from a dictionary."""
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+
+        return default_from_dict(cls, data)
+
+    def add_memories(
+        self,
+        *,
+        messages: list[ChatMessage],
+        infer: bool = True,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        async_mode: bool = False,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """
+        Add ChatMessage memories to Mem0.
+
+        :param messages: List of ChatMessage objects with memory metadata
+        :param infer: Whether to infer facts from the messages. If False, the whole message will
+            be added as a memory.
+        :param user_id: The user ID to to store and retrieve memories from the memory store.
+        :param run_id: The run ID to to store and retrieve memories from the memory store.
+        :param agent_id: The agent ID to to store and retrieve memories from the memory store.
+            If you want Mem0 to store chat messages from the assistant, you need to set the agent_id.
+        :param async_mode: Whether to add memories asynchronously.
+            If True, the method will return immediately and the memories will be added in the background.
+        :param kwargs: Additional keyword arguments to pass to the Mem0 client.add method.
+            Note: ChatMessage.meta in the list of messages will be ignored because Mem0 doesn't allow
+            passing metadata for each message in the list. You can pass metadata for the whole memory
+            by passing the `metadata` keyword argument to the method.
+        :returns: List of objects with the memory_id and the memory
+        """
+        added_ids = []
+        ids = self._get_ids(user_id, run_id, agent_id)
+        instructions = """
+        Store all memories from the user and suggestions from the assistant.
+        """
+
+        self.client.project.update(custom_instructions=instructions)
+        mem0_messages = []
+        for message in messages:
+            if not message.text:
+                continue
+            # we save the role of the message in the metadata
+            mem0_messages.append({"content": message.text, "role": message.role.value})
+        try:
+            status = self.client.add(messages=mem0_messages, infer=infer, **ids, async_mode=async_mode, **kwargs)
+            if status:
+                for result in status["results"]:
+                    memory_id = {"memory_id": result.get("id"), "memory": result["memory"]}
+                    added_ids.append(memory_id)
+        except Exception as e:
+            raise RuntimeError(f"Failed to add memory message: {e}") from e
+        return added_ids
+
+    def search_memories(
+        self,
+        *,
+        query: str | None = None,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 5,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        include_memory_metadata: bool = False,
+        **kwargs: Any,
+    ) -> list[ChatMessage]:
+        """
+        Search for memories in Mem0.
+
+        If filters are not provided, at least one of user_id, run_id, or agent_id must be set.
+        If filters are provided, the search will be scoped to the provided filters and the other ids will be ignored.
+        :param query: Text query to search for. If not provided, all memories will be returned.
+        :param filters: Haystack filters to apply on search. For more details on Haystack filters, see https://docs.haystack.deepset.ai/docs/metadata-filtering
+        :param top_k: Maximum number of results to return
+        :param user_id: The user ID to to store and retrieve memories from the memory store.
+        :param run_id: The run ID to to store and retrieve memories from the memory store.
+        :param agent_id: The agent ID to to store and retrieve memories from the memory store.
+            If you want Mem0 to store chat messages from the assistant, you need to set the agent_id.
+        :param include_memory_metadata: Whether to include the mem0 related metadata for the
+            retrieved memory in the ChatMessage.
+            If True, the metadata will include the mem0 related metadata i.e. memory_id, score, etc.
+            in the `mem0_memory_metadata` key.
+            If False, the `ChatMessage.meta` will only contain the user defined metadata.
+        :param kwargs: Additional keyword arguments to pass to the Mem0 client.
+            If query is passed, the kwargs will be passed to the Mem0 client.search method.
+            If query is not passed, the kwargs will be passed to the Mem0 client.get_all method.
+        :returns: List of ChatMessage memories matching the criteria
+        """
+        # Prepare filters for Mem0
+
+        if filters:
+            mem0_filters = self.normalize_filters(filters)
+        else:
+            ids = self._get_ids(user_id, run_id, agent_id)
+            if len(ids) == 1:
+                mem0_filters = dict(ids)
+            else:
+                mem0_filters = {"AND": [{key: value} for key, value in ids.items()]}
+        try:
+            if not query:
+                memories = self.client.get_all(filters=mem0_filters, **kwargs)
+            else:
+                memories = self.client.search(
+                    query=query,
+                    top_k=top_k,
+                    filters=mem0_filters,
+                    **kwargs,
+                )
+            messages = []
+            for memory in memories["results"]:
+                meta = memory["metadata"].copy() if memory["metadata"] else {}
+                # we also include the mem0 related metadata i.e. memory_id, score, etc.
+                if include_memory_metadata:
+                    meta["retrieved_memory_metadata"] = memory.copy()
+                    meta["retrieved_memory_metadata"].pop("memory")
+                messages.append(ChatMessage.from_system(text=memory["memory"], meta=meta))
+            return messages
+
+        except Exception as e:
+            raise RuntimeError(f"Failed to search memories: {e}") from e
+
+    def search_memories_as_single_message(
+        self,
+        *,
+        query: str | None = None,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 5,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        **kwargs: Any,
+    ) -> ChatMessage:
+        """
+        Search for memories in Mem0 and return a single ChatMessage object.
+
+        If filters are not provided, at least one of user_id, run_id, or agent_id must be set.
+        If filters are provided, the search will be scoped to the provided filters and the other ids will be ignored.
+        :param query: Text query to search for. If not provided, all memories will be returned.
+        :param filters: Additional filters to apply on search. For more details on mem0 filters, see https://mem0.ai/docs/search/
+        :param top_k: Maximum number of results to return
+        :param user_id: The user ID to to store and retrieve memories from the memory store.
+        :param run_id: The run ID to to store and retrieve memories from the memory store.
+        :param agent_id: The agent ID to to store and retrieve memories from the memory store.
+            If you want Mem0 to store chat messages from the assistant, you need to set the agent_id.
+        :param kwargs: Additional keyword arguments to pass to the Mem0 client.
+            If query is passed, the kwargs will be passed to the Mem0 client.search method.
+            If query is not passed, the kwargs will be passed to the Mem0 client.get_all method.
+        :returns: A single ChatMessage object with the memories matching the criteria
+        """
+        # Prepare filters for Mem0
+        if filters:
+            mem0_filters = self.normalize_filters(filters)
+        else:
+            ids = self._get_ids(user_id, run_id, agent_id)
+            if len(ids) == 1:
+                mem0_filters = dict(ids)
+            else:
+                mem0_filters = {"AND": [{key: value} for key, value in ids.items()]}
+
+        try:
+            if not query:
+                memories = self.client.get_all(filters=mem0_filters, **kwargs)
+            else:
+                memories = self.client.search(
+                    query=query,
+                    top_k=top_k,
+                    filters=mem0_filters,
+                    **kwargs,
+                )
+
+            # we combine the memories into a single string
+            combined_memory = "\n".join(
+                f"- MEMORY #{idx + 1}: {memory['memory']}" for idx, memory in enumerate(memories["results"])
+            )
+
+            return ChatMessage.from_system(text=combined_memory)
+
+        except Exception as e:
+            raise RuntimeError(f"Failed to search memories: {e}") from e
+
+    def delete_all_memories(
+        self,
+        *,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Delete memory records from Mem0.
+
+        At least one of user_id, run_id, or agent_id must be set.
+        :param user_id: The user ID to delete memories from.
+        :param run_id: The run ID to delete memories from.
+        :param agent_id: The agent ID to delete memories from.
+        :param kwargs: Additional keyword arguments to pass to the Mem0 client.delete_all method.
+        """
+        ids = self._get_ids(user_id, run_id, agent_id)
+
+        try:
+            self.client.delete_all(**ids, **kwargs)
+            logger.info("All memories deleted successfully for scope {ids}", ids=ids)
+        except Exception as e:
+            raise RuntimeError(f"Failed to delete memories with scope {ids}: {e}") from e
+
+    def delete_memory(self, memory_id: str, **kwargs: Any) -> None:
+        """
+        Delete memory from Mem0.
+
+        :param memory_id: The ID of the memory to delete.
+        :param kwargs: Additional keyword arguments to pass to the Mem0 client.delete method.
+        """
+        try:
+            self.client.delete(memory_id=memory_id, **kwargs)
+            logger.info("Memory deleted successfully for memory_id {memory_id}", memory_id=memory_id)
+        except Exception as e:
+            raise RuntimeError(f"Failed to delete memory {memory_id}: {e}") from e
+
+    def _get_ids(
+        self, user_id: str | None = None, run_id: str | None = None, agent_id: str | None = None
+    ) -> dict[str, Any]:
+        """
+        Check that at least one of the ids is set.
+
+        Return the set ids as a dictionary.
+        """
+        if not user_id and not run_id and not agent_id:
+            raise ValueError("At least one of user_id, run_id, or agent_id must be set")
+        ids = {
+            "user_id": user_id,
+            "run_id": run_id,
+            "agent_id": agent_id,
+        }
+        return {key: value for key, value in ids.items() if value is not None}
+
+    @staticmethod
+    def normalize_filters(filters: dict[str, Any]) -> dict[str, Any]:
+        """
+        Convert Haystack filters to Mem0 filters.
+        """
+
+        def convert_comparison(condition: dict[str, Any]) -> dict[str, Any]:
+            operator_map = {
+                "==": lambda field, value: {field: value},
+                "!=": lambda field, value: {field: {"ne": value}},
+                ">": lambda field, value: {field: {"gt": value}},
+                ">=": lambda field, value: {field: {"gte": value}},
+                "<": lambda field, value: {field: {"lt": value}},
+                "<=": lambda field, value: {field: {"lte": value}},
+                "in": lambda field, value: {field: {"in": value if isinstance(value, list) else [value]}},
+                "not in": lambda field, value: {field: {"ne": value}},
+            }
+            field = condition["field"]
+            value = condition["value"]
+            operator = condition["operator"]
+            if operator not in operator_map:
+                raise ValueError(f"Unsupported operator {operator}")
+            return operator_map[operator](field, value)
+
+        def convert_logic(node: dict[str, Any]) -> dict[str, Any]:
+            operator = node["operator"].upper()
+            if operator not in ("AND", "OR", "NOT"):
+                raise ValueError(f"Unsupported logic operator {operator}")
+            mem0_conditions = [convert_node(cond) for cond in node["conditions"]]
+            return {operator: mem0_conditions}
+
+        def convert_node(node: dict[str, Any]) -> dict[str, Any]:
+            if "field" in node:
+                return convert_comparison(node)
+            return convert_logic(node)
+
+        return convert_node(filters)

haystack_experimental/memory_stores/types/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .protocol import MemoryStore
+
+__all__ = ["MemoryStore"]

haystack_experimental/memory_stores/types/protocol.py

@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any, Protocol
+
+from haystack.dataclasses import ChatMessage
+
+# Ellipsis are needed for the type checker, it's safe to disable module-wide
+# pylint: disable=unnecessary-ellipsis
+
+
+class MemoryStore(Protocol):
+    """
+    Stores ChatMessage-based memories to be used by agents and components.
+
+    Implementations typically persist user- and agent-specific memories and
+    support adding, searching, and deleting memories.
+    """
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes this memory store to a dictionary.
+        """
+        ...
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MemoryStore":
+        """
+        Deserializes the memory store from a dictionary.
+        """
+        ...
+
+    def add_memories(
+        self,
+        *,
+        messages: list[ChatMessage],
+        user_id: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Add ChatMessage memories to the store.
+
+        :param messages: List of ChatMessage objects with memory metadata.
+        :param user_id: User ID to scope memories.
+        :param kwargs: Additional keyword arguments to pass to the add method.
+        """
+        ...
+
+    def search_memories(
+        self,
+        *,
+        query: str | None = None,
+        filters: dict[str, Any] | None = None,
+        top_k: int = 5,
+        user_id: str | None = None,
+        **kwargs: Any,
+    ) -> list[ChatMessage]:
+        """
+        Search for memories in the store.
+
+        :param query: Text query to search for. If not provided, all memories may be returned.
+        :param filters: Haystack filters to apply on search.
+        :param top_k: Maximum number of results to return.
+        :param user_id: User ID to scope memories.
+        :param kwargs: Additional keyword arguments to pass to the search method.
+
+        :returns: List of ChatMessage memories matching the criteria.
+        """
+        ...
+
+    def delete_all_memories(
+        self,
+        *,
+        user_id: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Delete all memories in the given scope.
+
+        In case of multiple optional ids, one of the ids must be set.
+        :param user_id: User ID to delete memories.
+        :param kwargs: Additional keyword arguments to pass to the delete method.
+        """
+        ...
+
+    def delete_memory(self, memory_id: str, **kwargs: Any) -> None:
+        """
+        Delete a single memory by its ID.
+
+        :param memory_id: The ID of the memory to delete.
+        :param kwargs: Additional keyword arguments to pass to the delete method.
+        """
+        ...

{haystack_experimental-0.16.0.dist-info → haystack_experimental-0.17.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haystack-experimental
-Version: 0.16.0
+Version: 0.17.0
 Summary: Experimental components and features for the Haystack LLM framework.
 Project-URL: CI: GitHub, https://github.com/deepset-ai/haystack-experimental/actions
 Project-URL: GitHub: issues, https://github.com/deepset-ai/haystack-experimental/issues
@@ -77,6 +77,7 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 | [`Agent`][17]; [Confirmation Policies][18]; [ConfirmationUIs][19]; [ConfirmationStrategies][20]; [`ConfirmationUIResult` and `ToolExecutionDecision`][21] [HITLBreakpointException][22] | Human in the Loop                     | December 2025     | rich         | None                                                                                                                                                                                                                                                       | [Discuss][23] |
 | [`LLMSummarizer`][24]                                                                                                                                                                   | Document Summarizer                   | January 2025      | None         | None                                                                                                                                                                                                                                                       | [Discuss][25] |
 | [`InMemoryChatMessageStore`][1]; [`ChatMessageRetriever`][2]; [`ChatMessageWriter`][3]                                                                                                  | Chat Message Store, Retriever, Writer | February 2025     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/conversational_rag_using_memory.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>       | [Discuss][4]  |
+| [`Mem0MemoryStore`][26]                                                                                                                                                                   | MemoryStore                   | February 2025      | mem0ai         | None                                                                                                                                                                                                                                                       | -- |
 
 [1]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/chat_message_stores/in_memory.py
 [2]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/retrievers/chat_message_retriever.py
@@ -95,6 +96,7 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 [23]: https://github.com/deepset-ai/haystack-experimental/discussions/381
 [24]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/sumarizers/llm_summarizer.py
 [25]: https://github.com/deepset-ai/haystack-experimental/discussions/382
+[26]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/memory_stores/mem0/memory_store.py
 
 ### Adopted experiments
 | Name                                                                                                                                                                                                                                       | Type                                     | Final release |

{haystack_experimental-0.16.0.dist-info → haystack_experimental-0.17.0.dist-info}/RECORD

@@ -4,7 +4,7 @@ haystack_experimental/chat_message_stores/in_memory.py,sha256=Dw5N9l8qk-RONEVVJb
 haystack_experimental/chat_message_stores/types.py,sha256=BHpk36OesvAxMgu6iOOYt4gmqw_cIE4nFDVgiutCguA,2726
 haystack_experimental/components/__init__.py,sha256=eHD7xrty2PCky_gG3ty19rpM4WfV32TyytM7gJODwl4,110
 haystack_experimental/components/agents/__init__.py,sha256=Sxu9LxPpQ5cljgoTgUeNC0GY8CwUdiSy1JWkd_-RRJ4,414
-haystack_experimental/components/agents/agent.py,sha256=n76MmXq_P0TAuFxHwNe5FC1iBAIjKbs8xOoZioyaypY,45651
+haystack_experimental/components/agents/agent.py,sha256=R0QUvQsLSuA-t90dASNdOE_cAwX_JJJamjU5RpQLcbs,50686
 haystack_experimental/components/agents/human_in_the_loop/__init__.py,sha256=xLr1G9pNWMmCpKN9mbv6yqeFfwMcbZyaVfCkzlwMxhY,1674
 haystack_experimental/components/agents/human_in_the_loop/breakpoint.py,sha256=K5rU61821uXjXkcXuXkN3p1_9Boq7FhJK1GOcAz7C0g,2939
 haystack_experimental/components/agents/human_in_the_loop/dataclasses.py,sha256=qQG4yRlzzcNeBlWagnZpjeJKZ2v_n2_9V9W0ZvsgBn4,2538
@@ -34,14 +34,19 @@ haystack_experimental/core/pipeline/__init__.py,sha256=eHD7xrty2PCky_gG3ty19rpM4
 haystack_experimental/core/pipeline/breakpoint.py,sha256=NcagwEJupIZ_Mp20YLmJyeqTZe8qwo6LfuB7OTXnlXk,5214
 haystack_experimental/dataclasses/__init__.py,sha256=eHD7xrty2PCky_gG3ty19rpM4WfV32TyytM7gJODwl4,110
 haystack_experimental/dataclasses/breakpoints.py,sha256=JevVOYiUMAsdg0QmSGiF_6aPveO83q47U-v-8Vd4nd0,2082
+haystack_experimental/memory_stores/__init__.py,sha256=xkSdV7qQ_e1kNO4PrXW37CIJMGavYiwbPtsfeSHQaQ4,169
+haystack_experimental/memory_stores/mem0/__init__.py,sha256=pntAgiFC6jXvzyHUQUNPtyChlys69jLa6rTVbClTb9I,458
+haystack_experimental/memory_stores/mem0/memory_store.py,sha256=PkDMVRWXooorTpHtnMRHZLgsxokJR8DlnV7vgedhPyk,14148
+haystack_experimental/memory_stores/types/__init__.py,sha256=7Sgg1w9bSGXDQkFXjmB4G4PGCBW7hDIYXItad7UxW4M,172
+haystack_experimental/memory_stores/types/protocol.py,sha256=LG0oK5jAJiVivtzQV7GacyikCDuZZQRQtPtkoJLCDj8,2761
 haystack_experimental/utils/__init__.py,sha256=eHD7xrty2PCky_gG3ty19rpM4WfV32TyytM7gJODwl4,110
 haystack_experimental/utils/hallucination_risk_calculator/__init__.py,sha256=kCd-qceud_T8P1XJHgRMaOnljyDjfFQ5UIdxEb5t6V0,219
 haystack_experimental/utils/hallucination_risk_calculator/core_math.py,sha256=8XIa2gX1B7U400KutPgxfIUHrOggkBPAm9gIkwhF7UM,4079
 haystack_experimental/utils/hallucination_risk_calculator/dataclasses.py,sha256=8HQL-ktwoog0WZlFz3-NQhhmVMjzMIrRjRoYuYXmorE,2284
 haystack_experimental/utils/hallucination_risk_calculator/openai_planner.py,sha256=Vt0icGcrPtTRywh9L2YfwB62a7pDynrm5-qlKaLHLsA,11381
 haystack_experimental/utils/hallucination_risk_calculator/skeletonization.py,sha256=KYdBDw5LcRtw8cmKW4aNGOKh3YrA17CPmcRE-FG6kSA,5466
-haystack_experimental-0.16.0.dist-info/METADATA,sha256=C6Dzv_tSvCuvTNMBEgfvdX9nMiZ026jbgNU1AvzXx1w,17078
-haystack_experimental-0.16.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-haystack_experimental-0.16.0.dist-info/licenses/LICENSE,sha256=93_5nS97uHxptHvK9E8BZgKxLGeIS-rBWT2swIv-X5Y,11368
-haystack_experimental-0.16.0.dist-info/licenses/LICENSE-MIT.txt,sha256=knmLkIKj_6tTrTSVRg9Tq88Kww4UCPLt2I1RGXJv9sQ,1037
-haystack_experimental-0.16.0.dist-info/RECORD,,
+haystack_experimental-0.17.0.dist-info/METADATA,sha256=VSHcnCORUhN3N_yPhKH8bCM7WGrXLeDx5BJpVyw_7wI,17721
+haystack_experimental-0.17.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+haystack_experimental-0.17.0.dist-info/licenses/LICENSE,sha256=93_5nS97uHxptHvK9E8BZgKxLGeIS-rBWT2swIv-X5Y,11368
+haystack_experimental-0.17.0.dist-info/licenses/LICENSE-MIT.txt,sha256=knmLkIKj_6tTrTSVRg9Tq88Kww4UCPLt2I1RGXJv9sQ,1037
+haystack_experimental-0.17.0.dist-info/RECORD,,