mem0-haystack 0.1.0__py3-none-any.whl

haystack_integrations/components/retrievers/mem0/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.components.retrievers.mem0.retriever import Mem0MemoryRetriever
+
+__all__ = ["Mem0MemoryRetriever"]

haystack_integrations/components/retrievers/mem0/retriever.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.memory_stores.mem0.memory_store import Mem0MemoryStore
+
+
+@component
+class Mem0MemoryRetriever:
+    """
+    Retrieves memories from a Mem0MemoryStore as a list of ChatMessage objects.
+
+    Use this component in a Haystack Pipeline to fetch relevant memories before passing
+    context to a language model or Agent. The returned memories are system messages.
+
+    Provide either `filters` or at least one Mem0 entity ID (`user_id`, `run_id`, `agent_id`, or `app_id`)
+    when running the component. If both are provided, the filters and entity IDs are combined.
+
+    ### Usage example
+
+    ```python
+    from haystack_integrations.components.retrievers.mem0 import Mem0MemoryRetriever
+    from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+
+    store = Mem0MemoryStore()
+    retriever = Mem0MemoryRetriever(memory_store=store, top_k=3)
+
+    result = retriever.run(query="What does Alice like?", user_id="alice")
+    memories = result["memories"]
+    print([message.text for message in memories])
+
+    # Pass query=None to retrieve all memories in scope.
+    all_memories = retriever.run(query=None, user_id="alice")["memories"]
+    ```
+    """
+
+    def __init__(self, *, memory_store: Mem0MemoryStore, top_k: int = 5) -> None:
+        """
+        Initialize the Mem0MemoryRetriever.
+
+        :param memory_store: The Mem0MemoryStore instance to retrieve memories from.
+        :param top_k: Default maximum number of memories to return per query.
+        """
+        self.memory_store = memory_store
+        self.top_k = top_k
+
+    @component.output_types(memories=list[ChatMessage])
+    def run(
+        self,
+        query: str | None,
+        *,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        filters: dict[str, Any] | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[ChatMessage]]:
+        """
+        Retrieve memories matching the query from Mem0.
+
+        :param query: Text query used to search for relevant memories. Pass `None` to retrieve all memories matching
+            the scope.
+        :param user_id: User ID to scope the search.
+        :param run_id: Run ID to scope the search.
+        :param agent_id: Agent ID to scope the search.
+        :param app_id: App ID to scope the search.
+        :param filters: Haystack-style filters to apply. When provided with ID parameters, they are combined.
+            Mem0 requires entity IDs inside filters and supports a fixed set of native fields and operators:
+            [Search Memories API](https://docs.mem0.ai/api-reference/memory/search-memories) and
+            [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters). Fields that are not native
+            Mem0 filter fields are treated as Mem0 metadata fields.
+        :param top_k: Maximum number of memories to return. Overrides the init-time default.
+        :returns: Dictionary with key `memories` containing a list of ChatMessage objects. User-provided
+            Mem0 metadata is included in each message's meta. Mem0 retrieval fields such as `memory_id`, `user_id`,
+            `score`, and timestamps are included under `meta["mem0"]`.
+        """
+        memories = self.memory_store.search_memories(
+            query=query,
+            filters=filters,
+            top_k=top_k if top_k is not None else self.top_k,
+            user_id=user_id,
+            run_id=run_id,
+            agent_id=agent_id,
+            app_id=app_id,
+        )
+        return {"memories": memories}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this component to a dictionary."""
+        return default_to_dict(
+            self,
+            memory_store=self.memory_store.to_dict(),
+            top_k=self.top_k,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Mem0MemoryRetriever":
+        """Deserialize this component from a dictionary."""
+        if data.get("init_parameters", {}).get("memory_store"):
+            data["init_parameters"]["memory_store"] = default_from_dict(
+                Mem0MemoryStore, data["init_parameters"]["memory_store"]
+            )
+        return default_from_dict(cls, data)

haystack_integrations/components/writers/mem0/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.components.writers.mem0.writer import Mem0MemoryWriter
+
+__all__ = ["Mem0MemoryWriter"]

haystack_integrations/components/writers/mem0/writer.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import ChatMessage
+
+from haystack_integrations.memory_stores.mem0.memory_store import Mem0MemoryStore
+
+
+@component
+class Mem0MemoryWriter:
+    """
+    Writes ChatMessage objects as memories to a Mem0MemoryStore.
+
+    Use this component in a Haystack Pipeline to persist conversation messages.
+    Scoping IDs (`user_id`, `run_id`, `agent_id`, `app_id`) are runtime parameters so the
+    same pipeline instance can serve multiple users or agents. The `infer` setting controls whether
+    Mem0 extracts memories from messages or stores message text as-is.
+
+    ### Usage example
+
+    ```python
+    from haystack.dataclasses import ChatMessage
+    from haystack_integrations.components.writers.mem0 import Mem0MemoryWriter
+    from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+
+    store = Mem0MemoryStore()
+    writer = Mem0MemoryWriter(memory_store=store, infer=False)
+
+    result = writer.run(
+        messages=[ChatMessage.from_user("Alice prefers concise Python examples.")],
+        user_id="alice",
+    )
+    print(result["memories_written"])
+    ```
+    """
+
+    def __init__(self, *, memory_store: Mem0MemoryStore, infer: bool = True) -> None:
+        """
+        Initialize the Mem0MemoryWriter.
+
+        :param memory_store: The Mem0MemoryStore instance to write memories to.
+        :param infer: If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.
+        """
+        self.memory_store = memory_store
+        self.infer = infer
+
+    @component.output_types(memories_written=int)
+    def run(
+        self,
+        messages: list[ChatMessage],
+        *,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+    ) -> dict[str, int]:
+        """
+        Write messages as memories to the Mem0 store.
+
+        :param messages: List of ChatMessage objects to store.
+        :param user_id: User ID to scope the stored memories.
+        :param run_id: Run ID to scope the stored memories.
+        :param agent_id: Agent ID to scope the stored memories.
+        :param app_id: App ID to scope the stored memories.
+        :returns: Dictionary with key `memories_written` containing the count of stored memory items.
+        """
+        result = self.memory_store.add_memories(
+            messages=messages,
+            user_id=user_id,
+            run_id=run_id,
+            agent_id=agent_id,
+            app_id=app_id,
+            infer=self.infer,
+        )
+        count = len(result) if isinstance(result, list) else 0
+        return {"memories_written": count}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this component to a dictionary."""
+        return default_to_dict(self, memory_store=self.memory_store.to_dict(), infer=self.infer)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Mem0MemoryWriter":
+        """Deserialize this component from a dictionary."""
+        if data.get("init_parameters", {}).get("memory_store"):
+            data["init_parameters"]["memory_store"] = Mem0MemoryStore.from_dict(data["init_parameters"]["memory_store"])
+        return default_from_dict(cls, data)

haystack_integrations/memory_stores/mem0/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.memory_stores.mem0.errors import Mem0MemoryStoreError
+from haystack_integrations.memory_stores.mem0.memory_store import Mem0MemoryStore
+
+__all__ = [
+    "Mem0MemoryStore",
+    "Mem0MemoryStoreError",
+]

haystack_integrations/memory_stores/mem0/errors.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+class Mem0MemoryStoreError(RuntimeError):
+    """Raised when a Mem0 API operation fails."""

haystack_integrations/memory_stores/mem0/filters.py

@@ -0,0 +1,215 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Utilities for translating Haystack filters into Mem0 Platform filters.
+
+Mem0 Platform `search` and `get_all` expect entity IDs such as `user_id`, `agent_id`, `app_id`, and `run_id`
+inside the `filters` object. They also reserve a fixed set of top-level filter fields such as `created_at`,
+`categories`, `keywords`, and `memory_ids`.
+
+See:
+- [Search Memories API](https://docs.mem0.ai/api-reference/memory/search-memories)
+- [Get Memories API](https://docs.mem0.ai/api-reference/memory/get-memories)
+- [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters)
+
+Haystack users usually think of arbitrary fields as metadata filters. To keep that API natural while sending valid
+Mem0 filters, fields that are not native Mem0 filter fields are nested under `metadata`. For example,
+`{"field": "category", "operator": "==", "value": "work"}` becomes `{"metadata": {"category": "work"}}`.
+"""
+
+from typing import Any
+
+from haystack.errors import FilterError
+
+# Keep this list aligned with the top-level filter keys documented in:
+# https://docs.mem0.ai/api-reference/memory/search-memories
+# https://docs.mem0.ai/platform/features/v2-memory-filters
+_TOP_LEVEL_FILTER_FIELDS = {
+    "user_id",
+    "agent_id",
+    "app_id",
+    "run_id",
+    "created_at",
+    "updated_at",
+    "timestamp",
+    "categories",
+    "metadata",
+    "keywords",
+    "feedback",
+    "feedback_reason",
+    "memory_ids",
+}
+
+
+def _build_search_filters(
+    *,
+    filters: dict[str, Any] | None = None,
+    user_id: str | None = None,
+    run_id: str | None = None,
+    agent_id: str | None = None,
+    app_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    Build Mem0 search filters from explicit IDs and optional Haystack-style filters.
+
+    Mem0 `search` and `get_all` expect entity IDs inside the `filters` object.
+    This helper keeps the public store API convenient while ensuring IDs and custom filters are both applied.
+    It combines everything as Haystack-style filters first, then normalizes the combined filter to Mem0 format.
+    Fields that are not native Mem0 filter fields are treated as Mem0 metadata fields.
+
+    Mem0 filter reference:
+    - [Search Memories API](https://docs.mem0.ai/api-reference/memory/search-memories)
+    - [Get Memories API](https://docs.mem0.ai/api-reference/memory/get-memories)
+
+    :param filters: Haystack-style filters to combine with IDs.
+    :param user_id: User ID to scope the search.
+    :param run_id: Run ID to scope the search.
+    :param agent_id: Agent ID to scope the search.
+    :param app_id: App ID to scope the search.
+    :returns: Mem0-compatible filters.
+    :raises ValueError: If neither filters nor an entity ID is provided.
+    """
+    conditions = [
+        {"field": key, "operator": "==", "value": value}
+        for key, value in {"user_id": user_id, "run_id": run_id, "agent_id": agent_id, "app_id": app_id}.items()
+        if value
+    ]
+
+    if filters:
+        if filters.get("operator", "").upper() == "AND" and "conditions" in filters:
+            conditions.extend(filters["conditions"])
+        else:
+            conditions.append(filters)
+
+    if not conditions:
+        msg = "Either filters or at least one of user_id, run_id, agent_id, or app_id must be provided."
+        raise ValueError(msg)
+
+    combined_filter = conditions[0] if len(conditions) == 1 else {"operator": "AND", "conditions": conditions}
+    return normalize_filters(combined_filter)
+
+
+def normalize_filters(filters: dict[str, Any]) -> dict[str, Any]:
+    """
+    Convert Haystack-style filters to the Mem0 filter format.
+
+    Mem0 Platform supports logical filters (`AND`, `OR`, `NOT`) and comparison operators on native fields.
+    It also supports metadata filters under the top-level `metadata` key.
+    See [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters) for the list of fields and
+    operators.
+
+    :param filters: Haystack filter dictionary.
+    :returns: Equivalent Mem0 filter dictionary. Fields that are not native Mem0 filter fields are nested under
+        `metadata`.
+    :raises FilterError: If the filter structure or operators are invalid.
+    """
+    if not isinstance(filters, dict):
+        msg = "Filters must be a dictionary."
+        raise FilterError(msg)
+    if "field" in filters:
+        return _parse_comparison_condition(filters)
+    return _parse_logical_condition(filters)
+
+
+def _parse_logical_condition(condition: dict[str, Any]) -> dict[str, Any]:
+    """
+    Parse a Haystack logical condition into Mem0's logical filter shape.
+
+    Mem0 documents `AND`, `OR`, and `NOT` as supported logical operators:
+    [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters)
+    """
+    if "operator" not in condition:
+        msg = f"'operator' key missing in: {condition}"
+        raise FilterError(msg)
+    if "conditions" not in condition:
+        msg = f"'conditions' key missing in: {condition}"
+        raise FilterError(msg)
+
+    operator = condition["operator"].upper()
+    if operator not in ("AND", "OR", "NOT"):
+        msg = f"Unsupported logical operator: {operator!r}. Use AND, OR, or NOT."
+        raise FilterError(msg)
+
+    converted = [_convert(c) for c in condition["conditions"]]
+    return {operator: converted}
+
+
+def _parse_comparison_condition(condition: dict[str, Any]) -> dict[str, Any]:
+    """
+    Parse a Haystack comparison condition into Mem0's native or metadata filter shape.
+
+    Native Mem0 fields are kept at the top level. All other fields are treated as metadata fields because Mem0's
+    Platform API expects metadata filters under the `metadata` key:
+    [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters)
+    """
+    if "field" not in condition:
+        msg = f"'field' key missing in: {condition}"
+        raise FilterError(msg)
+    if "operator" not in condition:
+        msg = f"'operator' key missing in: {condition}"
+        raise FilterError(msg)
+    if "value" not in condition:
+        msg = f"'value' key missing in: {condition}"
+        raise FilterError(msg)
+
+    field: str = condition["field"]
+    operator: str = condition["operator"]
+    value: Any = condition["value"]
+
+    if field not in _TOP_LEVEL_FILTER_FIELDS:
+        return _parse_metadata_comparison_condition(field, operator, value)
+
+    op_map = {
+        "==": lambda f, v: {f: v},
+        "!=": lambda f, v: {f: {"ne": v}},
+        ">": lambda f, v: {f: {"gt": v}},
+        ">=": lambda f, v: {f: {"gte": v}},
+        "<": lambda f, v: {f: {"lt": v}},
+        "<=": lambda f, v: {f: {"lte": v}},
+        "in": lambda f, v: {f: {"in": v if isinstance(v, list) else [v]}},
+        "not in": lambda f, v: {f: {"ne": v}},
+        "contains": lambda f, v: {f: {"contains": v}},
+        "icontains": lambda f, v: {f: {"icontains": v}},
+    }
+
+    if operator not in op_map:
+        msg = f"Unsupported filter operator: {operator!r}."
+        raise FilterError(msg)
+
+    return op_map[operator](field, value)
+
+
+def _parse_metadata_comparison_condition(field: str, operator: str, value: Any) -> dict[str, Any]:
+    """
+    Convert a Haystack metadata comparison into Mem0's `metadata` filter shape.
+
+    Mem0 metadata filters support bare equality, `ne`, and `contains`; operators such as `in`, `gt`, and `lt` are not
+    supported for metadata filters.
+    For multi-value metadata checks, Mem0 recommends composing equality clauses with `OR`.
+
+    See [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters).
+    """
+    metadata_field = field.removeprefix("metadata.")
+    op_map = {
+        "==": lambda f, v: {"metadata": {f: v}},
+        "!=": lambda f, v: {"metadata": {f: {"ne": v}}},
+        "contains": lambda f, v: {"metadata": {f: {"contains": v}}},
+    }
+
+    if operator not in op_map:
+        msg = (
+            f"Unsupported metadata filter operator: {operator!r}. "
+            "Mem0 metadata filters support ==, !=, and contains. "
+            "For multi-value metadata filters, combine equality conditions with OR."
+        )
+        raise FilterError(msg)
+
+    return op_map[operator](metadata_field, value)
+
+
+def _convert(node: dict[str, Any]) -> dict[str, Any]:
+    if "field" in node:
+        return _parse_comparison_condition(node)
+    return _parse_logical_condition(node)

haystack_integrations/memory_stores/mem0/memory_store.py

@@ -0,0 +1,218 @@
+# 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.utils import Secret, deserialize_secrets_inplace
+
+from haystack_integrations.memory_stores.mem0.errors import Mem0MemoryStoreError
+from haystack_integrations.memory_stores.mem0.filters import _build_search_filters
+from mem0 import MemoryClient
+
+logger = logging.getLogger(__name__)
+
+
+class Mem0MemoryStore:
+    """
+    A memory store backed by the Mem0 cloud API.
+
+    Stores and retrieves ChatMessage-based memories scoped by user_id, run_id, agent_id, or app_id.
+    The Mem0 client is created lazily on first use (or explicitly via warm_up()).
+    Requires a Mem0 API key set via the MEM0_API_KEY environment variable or passed explicitly.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Secret = Secret.from_env_var("MEM0_API_KEY"),
+    ) -> None:
+        """
+        Initialize the Mem0 memory store.
+
+        The Mem0 client is not created until warm_up() is called (or the first method that
+        needs the client is invoked).
+
+        :param api_key: The Mem0 API key. Defaults to the MEM0_API_KEY environment variable.
+        """
+        self.api_key = api_key
+        self._client: MemoryClient | None = None
+
+    def warm_up(self) -> None:
+        """
+        Create the Mem0 client. Called automatically on first use if not called explicitly.
+
+        Calling this method explicitly is useful when you want to validate the API key
+        or pre-connect before the first pipeline run.
+        """
+        if self._client is None:
+            self._client = MemoryClient(api_key=self.api_key.resolve_value())
+
+    @property
+    def client(self) -> MemoryClient:
+        """Return the initialized client, calling warm_up() if necessary."""
+        self.warm_up()
+        return self._client  # type: ignore[return-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."""
+        if data.get("init_parameters"):
+            deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)
+
+    def add_memories(
+        self,
+        *,
+        messages: list[ChatMessage],
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        infer: bool = True,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """
+        Add ChatMessage memories to Mem0.
+
+        :param messages: List of ChatMessage objects to store as memories.
+        :param user_id: User ID to scope these memories.
+        :param run_id: Run ID to scope these memories.
+        :param agent_id: Agent ID to scope these memories. Required for Mem0 to store assistant messages.
+        :param app_id: App ID to scope these memories.
+        :param infer: If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.
+        :param kwargs: Additional keyword arguments forwarded to the Mem0 client add method.
+            Note: ChatMessage.meta is ignored because Mem0 doesn't support per-message metadata.
+            Pass `metadata` as a kwarg to attach metadata to the whole batch instead.
+        :returns: List of objects with `memory_id` and `memory` text for each stored memory.
+        :raises Mem0MemoryStoreError: If the Mem0 API call fails.
+        """
+        ids = self._get_ids(user_id=user_id, run_id=run_id, agent_id=agent_id, app_id=app_id)
+        mem0_messages = [{"content": msg.text, "role": msg.role.value} for msg in messages if msg.text]
+        if not mem0_messages:
+            logger.warning(
+                "No valid messages to add after filtering out empty texts. Returning without calling Mem0 API."
+            )
+            return []
+
+        added: list[dict[str, Any]] = []
+        try:
+            status = self.client.add(
+                messages=mem0_messages,
+                infer=infer,
+                **ids,
+                **kwargs,
+            )
+            if status and "results" in status:
+                for result in status["results"]:
+                    data = result.get("data")
+                    memory_text = data.get("memory") if isinstance(data, dict) else result.get("memory")
+                    added.append({"memory_id": result.get("id"), "memory": memory_text})
+        except Exception as e:
+            msg = f"Failed to add memories: {e}"
+            raise Mem0MemoryStoreError(msg) from e
+        return added
+
+    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,
+        app_id: str | None = None,
+        **kwargs: Any,
+    ) -> list[ChatMessage]:
+        """
+        Search for memories in Mem0.
+
+        Either `filters` or at least one of `user_id`, `run_id`, `agent_id`, or `app_id` must be provided.
+        When both `filters` and IDs are provided, they are combined with an `AND` condition.
+
+        :param query: Text query to search. If omitted, returns all memories matching the scope.
+        :param filters: Haystack-style filters to apply. See
+            [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering).
+            Mem0 requires entity IDs inside filters and supports a fixed set of native fields and operators:
+            [Search Memories API](https://docs.mem0.ai/api-reference/memory/search-memories) and
+            [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters).
+            Fields that are not native Mem0 filter fields are treated as Mem0 metadata fields.
+        :param top_k: Maximum number of results to return.
+        :param user_id: User ID to scope the search.
+        :param run_id: Run ID to scope the search.
+        :param agent_id: Agent ID to scope the search.
+        :param app_id: App ID to scope the search.
+        :param kwargs: Additional keyword arguments forwarded to the Mem0 client.
+        :returns: List of ChatMessage (system role) objects containing the retrieved memories. User-provided
+            Mem0 metadata is included in each message's meta. Mem0 retrieval fields such as `memory_id`, `user_id`,
+            `score`, and timestamps are included under `meta["mem0"]`.
+        :raises Mem0MemoryStoreError: If the Mem0 API call fails.
+        """
+        mem0_filters = _build_search_filters(
+            filters=filters,
+            user_id=user_id,
+            run_id=run_id,
+            agent_id=agent_id,
+            app_id=app_id,
+        )
+
+        try:
+            if not query:
+                raw = self.client.get_all(filters=mem0_filters, **kwargs)
+            else:
+                raw = self.client.search(query=query, top_k=top_k, filters=mem0_filters, **kwargs)
+
+            result_messages = []
+            for memory in raw["results"]:
+                meta = dict(memory["metadata"]) if memory["metadata"] else {}
+                meta["mem0"] = {
+                    "memory_id": memory.get("id"),
+                    "user_id": memory.get("user_id"),
+                    "agent_id": memory.get("agent_id"),
+                    "app_id": memory.get("app_id"),
+                    "run_id": memory.get("run_id"),
+                    "score": memory.get("score"),
+                    "score_breakdown": memory.get("score_breakdown"),
+                    "categories": memory.get("categories"),
+                    "created_at": memory.get("created_at"),
+                    "updated_at": memory.get("updated_at"),
+                }
+                result_messages.append(ChatMessage.from_system(text=memory["memory"], meta=meta))
+            return result_messages
+        except Exception as e:
+            msg = f"Failed to search memories: {e}"
+            raise Mem0MemoryStoreError(msg) from e
+
+    def _get_ids(
+        self,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Return non-empty Mem0 entity IDs for scoped memory operations.
+
+        Mem0 requires at least one entity ID when adding or searching memories without explicit filters.
+        Valid entity IDs are `user_id`, `run_id`, `agent_id`, and `app_id`.
+
+        :param user_id: User ID to include in the scope.
+        :param run_id: Run ID to include in the scope.
+        :param agent_id: Agent ID to include in the scope.
+        :param app_id: App ID to include in the scope.
+        :returns: Dictionary containing only provided entity IDs.
+        :raises ValueError: If no entity ID is provided.
+        """
+        if not any([user_id, run_id, agent_id, app_id]):
+            msg = "At least one of user_id, run_id, agent_id, or app_id must be provided."
+            raise ValueError(msg)
+        return {
+            k: v for k, v in {"user_id": user_id, "run_id": run_id, "agent_id": agent_id, "app_id": app_id}.items() if v
+        }

haystack_integrations/tools/mem0/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.tools.mem0.retriever_tool import Mem0MemoryRetrieverTool
+from haystack_integrations.tools.mem0.writer_tool import Mem0MemoryWriterTool
+
+__all__ = ["Mem0MemoryRetrieverTool", "Mem0MemoryWriterTool"]

haystack_integrations/tools/mem0/retriever_tool.py

@@ -0,0 +1,173 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from copy import deepcopy
+from typing import Any
+
+from haystack.core.serialization import generate_qualified_class_name
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool
+
+from haystack_integrations.memory_stores.mem0.memory_store import Mem0MemoryStore
+
+_DEFAULT_DESCRIPTION = (
+    "Search long-term memories relevant to a query, or return all scoped memories when no query is provided. "
+    "Use this tool when stored context from past conversations or facts could help answer the user."
+)
+
+_PARAMETERS: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "query": {
+            "type": ["string", "null"],
+            "description": (
+                "The search query to find relevant memories. Omit or pass null to return all memories in scope."
+            ),
+        },
+        "top_k": {"type": "integer", "description": "Maximum number of memories to return for query searches."},
+    },
+}
+
+_DEFAULT_INPUTS_FROM_STATE: dict[str, str] = {"user_id": "user_id"}
+
+
+class Mem0MemoryRetrieverTool(Tool):
+    """
+    A tool that searches a Mem0MemoryStore for memories.
+
+    The `user_id` is injected at runtime from Agent State via `inputs_from_state`,
+    so a single tool instance can serve many users. The LLM only sees `query` and `top_k` by default.
+    If the LLM omits `query` or passes `None`, Mem0 returns all memories matching the injected scope.
+    Pass a custom `inputs_from_state` mapping to inject other supported Mem0 entity IDs such as
+    `run_id`, `agent_id`, or `app_id`. The mapping keys are Agent State keys and the values are this
+    tool's parameter names. For example, use
+    `inputs_from_state={"user_id": "user_id", "session_id": "run_id"}` to pass `state["session_id"]`
+    to the tool's `run_id` parameter at runtime.
+
+    ### Usage example
+
+    ```python
+    from haystack.components.agents import Agent
+    from haystack.components.generators.chat import OpenAIChatGenerator
+    from haystack.dataclasses import ChatMessage
+    from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+    from haystack_integrations.tools.mem0 import Mem0MemoryRetrieverTool
+
+    store = Mem0MemoryStore()
+    retrieve_memories = Mem0MemoryRetrieverTool(memory_store=store, top_k=5)
+
+    agent = Agent(
+        chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+        tools=[retrieve_memories],
+        state_schema={"user_id": {"type": str}, "session_id": {"type": str}},
+    )
+
+    # The Agent can call retrieve_memories with a query for targeted recall,
+    # or without a query when it needs all scoped memories.
+    result = agent.run(
+        messages=[ChatMessage.from_user("What do you remember about me?")],
+        user_id="alice",
+        session_id="chat-42",
+    )
+    print(result["last_message"].text)
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        memory_store: Mem0MemoryStore,
+        top_k: int = 5,
+        name: str = "retrieve_memories",
+        description: str = _DEFAULT_DESCRIPTION,
+        parameters: dict[str, Any] = _PARAMETERS,
+        inputs_from_state: dict[str, str] = _DEFAULT_INPUTS_FROM_STATE,
+    ) -> None:
+        """
+        Initialize the Mem0MemoryRetrieverTool.
+
+        :param memory_store: The Mem0MemoryStore instance to query.
+        :param top_k: Default maximum number of memories to return. The LLM may override this.
+        :param name: Tool name exposed to the LLM.
+        :param description: Tool description exposed to the LLM.
+        :param parameters: JSON schema for the parameters exposed to the LLM. Defaults to optional `query` and `top_k`.
+        :param inputs_from_state: Mapping from Agent State keys to this tool's parameter names.
+            Defaults to `{"user_id": "user_id"}`, which injects `state["user_id"]` into the `user_id`
+            parameter. To pass more Mem0 IDs at runtime, add the state fields to the Agent's
+            `state_schema` and map them to the corresponding tool parameters, for example
+            `{"user_id": "user_id", "session_id": "run_id", "agent_name": "agent_id", "app_name": "app_id"}`.
+        """
+        self.memory_store = memory_store
+        self.top_k = top_k
+        self._is_warmed_up = False
+        super().__init__(
+            name=name,
+            description=description,
+            # We deepcopy to avoid accidental mutations since dicts are mutable and could be shared across instances
+            parameters=deepcopy(parameters),
+            function=self.retrieve,
+            inputs_from_state=dict(inputs_from_state),
+        )
+
+    def warm_up(self) -> None:
+        """Initialize the Mem0 client. Subsequent calls are no-ops."""
+        if self._is_warmed_up:
+            return
+        self.memory_store.warm_up()
+        self._is_warmed_up = True
+
+    def retrieve(
+        self,
+        query: str | None = None,
+        *,
+        top_k: int | None = None,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+    ) -> str:
+        """
+        Retrieve memories relevant to a query, or all memories when no query is provided.
+
+        :param query: Text query used to search for relevant memories. If omitted or `None`, all memories matching
+            the scope are returned.
+        :param top_k: Maximum number of memories to return for query searches. Overrides the tool default.
+        :param user_id: User ID to scope the search. Injected from Agent State by default.
+        :param run_id: Run ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+        :param agent_id: Agent ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+        :param app_id: App ID to scope the search. Can be injected with a custom `inputs_from_state` mapping.
+        :returns: Retrieved memories formatted for the Agent, or a message when no memories were found.
+        """
+        memories: list[ChatMessage] = self.memory_store.search_memories(
+            query=query,
+            top_k=top_k if top_k is not None else self.top_k,
+            user_id=user_id,
+            run_id=run_id,
+            agent_id=agent_id,
+            app_id=app_id,
+        )
+        if not memories:
+            return "No memories found."
+        return "\n".join(f"- {m.text}" for m in memories if m.text)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this tool to a dictionary."""
+        return {
+            "type": generate_qualified_class_name(type(self)),
+            "data": {
+                "memory_store": self.memory_store.to_dict(),
+                "top_k": self.top_k,
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+                "inputs_from_state": self.inputs_from_state,
+            },
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Mem0MemoryRetrieverTool":
+        """Deserialize this tool from a dictionary."""
+        inner = data["data"]
+        inner["memory_store"] = Mem0MemoryStore.from_dict(inner["memory_store"])
+        return cls(**inner)

haystack_integrations/tools/mem0/writer_tool.py

@@ -0,0 +1,164 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from copy import deepcopy
+from typing import Any
+
+from haystack.core.serialization import generate_qualified_class_name
+from haystack.dataclasses import ChatMessage
+from haystack.tools import Tool
+
+from haystack_integrations.memory_stores.mem0.memory_store import Mem0MemoryStore
+
+_DEFAULT_DESCRIPTION = (
+    "Store a piece of information as a long-term memory. "
+    "Use this tool to persist important facts, preferences, or context for future conversations."
+)
+
+_PARAMETERS: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "text": {"type": "string", "description": "The information to store as a memory."},
+        "infer": {
+            "type": "boolean",
+            "description": "If true, Mem0 extracts memories from the text. If false, Mem0 stores the text as-is.",
+            "default": False,
+        },
+    },
+    "required": ["text"],
+}
+
+_DEFAULT_INPUTS_FROM_STATE: dict[str, str] = {"user_id": "user_id"}
+
+
+class Mem0MemoryWriterTool(Tool):
+    """
+    A tool that writes a memory to a Mem0MemoryStore.
+
+    The `user_id` is injected at runtime from Agent State via `inputs_from_state`,
+    so a single tool instance can serve many users. The LLM only sees `text` and `infer`.
+    Pass a custom `inputs_from_state` mapping to inject other supported Mem0 entity IDs such as
+    `run_id`, `agent_id`, or `app_id`. The mapping keys are Agent State keys and the values are this
+    tool's parameter names. For example, use
+    `inputs_from_state={"user_id": "user_id", "session_id": "run_id"}` to pass `state["session_id"]`
+    to the tool's `run_id` parameter at runtime.
+
+    ### Usage example
+
+    ```python
+    from haystack.components.agents import Agent
+    from haystack.components.generators.chat import OpenAIChatGenerator
+    from haystack.dataclasses import ChatMessage
+    from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
+    from haystack_integrations.tools.mem0 import Mem0MemoryWriterTool
+
+    store = Mem0MemoryStore()
+    store_memory = Mem0MemoryWriterTool(memory_store=store)
+
+    agent = Agent(
+        chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+        tools=[store_memory],
+        state_schema={"user_id": {"type": str}, "session_id": {"type": str}},
+    )
+
+    result = agent.run(
+        messages=[ChatMessage.from_user("Remember that I prefer concise Python examples.")],
+        user_id="alice",
+        session_id="chat-42",
+    )
+    print(result["last_message"].text)
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        memory_store: Mem0MemoryStore,
+        name: str = "store_memory",
+        description: str = _DEFAULT_DESCRIPTION,
+        parameters: dict[str, Any] = _PARAMETERS,
+        inputs_from_state: dict[str, str] = _DEFAULT_INPUTS_FROM_STATE,
+    ) -> None:
+        """
+        Initialize the Mem0MemoryWriterTool.
+
+        :param memory_store: The Mem0MemoryStore instance to write to.
+        :param name: Tool name exposed to the LLM.
+        :param description: Tool description exposed to the LLM.
+        :param parameters: JSON schema for the parameters exposed to the LLM. Defaults to `text` and `infer`.
+        :param inputs_from_state: Mapping from Agent State keys to this tool's parameter names.
+            Defaults to `{"user_id": "user_id"}`, which injects `state["user_id"]` into the `user_id`
+            parameter. To pass more Mem0 IDs at runtime, add the state fields to the Agent's
+            `state_schema` and map them to the corresponding tool parameters, for example
+            `{"user_id": "user_id", "session_id": "run_id", "agent_name": "agent_id", "app_name": "app_id"}`.
+        """
+        self.memory_store = memory_store
+        self._is_warmed_up = False
+        super().__init__(
+            name=name,
+            description=description,
+            # We deepcopy to avoid accidental mutations since dicts are mutable and could be shared across instances
+            parameters=deepcopy(parameters),
+            function=self.store,
+            inputs_from_state=dict(inputs_from_state),
+        )
+
+    def warm_up(self) -> None:
+        """Initialize the Mem0 client. Subsequent calls are no-ops."""
+        if self._is_warmed_up:
+            return
+        self.memory_store.warm_up()
+        self._is_warmed_up = True
+
+    def store(
+        self,
+        text: str,
+        *,
+        infer: bool = False,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+    ) -> str:
+        """
+        Store text as a memory.
+
+        :param text: The information to store as a memory.
+        :param infer: If True, Mem0 extracts memories from the text. If False, Mem0 stores the text as-is.
+        :param user_id: User ID to scope the stored memory. Injected from Agent State by default.
+        :param run_id: Run ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+        :param agent_id: Agent ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+        :param app_id: App ID to scope the stored memory. Can be injected with a custom `inputs_from_state` mapping.
+        :returns: A string indicating how many memory items were stored.
+        """
+        result = self.memory_store.add_memories(
+            messages=[ChatMessage.from_user(text)],
+            infer=infer,
+            user_id=user_id,
+            run_id=run_id,
+            agent_id=agent_id,
+            app_id=app_id,
+        )
+        count = len(result) if isinstance(result, list) else 0
+        return f"Stored {count} memory item(s)."
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this tool to a dictionary."""
+        return {
+            "type": generate_qualified_class_name(type(self)),
+            "data": {
+                "memory_store": self.memory_store.to_dict(),
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+                "inputs_from_state": self.inputs_from_state,
+            },
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Mem0MemoryWriterTool":
+        """Deserialize this tool from a dictionary."""
+        inner = data["data"]
+        inner["memory_store"] = Mem0MemoryStore.from_dict(inner["memory_store"])
+        return cls(**inner)

mem0_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: mem0-haystack
+Version: 0.1.0
+Summary: Haystack integration for mem0
+Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mem0#readme
+Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
+Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mem0
+Author-email: deepset GmbH <info@deepset.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE.txt
+Keywords: agents,haystack,llm,mem0,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=2.19.0
+Requires-Dist: mem0ai>=0.1.0
+Description-Content-Type: text/markdown
+
+# mem0-haystack
+
+[![PyPI - Version](https://img.shields.io/pypi/v/mem0-haystack.svg)](https://pypi.org/project/mem0-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mem0-haystack.svg)](https://pypi.org/project/mem0-haystack)
+
+- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/mem0/CHANGELOG.md)
+
+---
+
+## Contributing
+
+Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+To run integration tests locally, export the `MEM0_API_KEY` environment variable.

mem0_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+haystack_integrations/components/retrievers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/components/retrievers/mem0/__init__.py,sha256=xMrzu_Y6FsHcz3OSAch8gt5tlEVJsOBTYeqgkH-K3lA,237
+haystack_integrations/components/retrievers/mem0/retriever.py,sha256=qS1sLHZbyMpSJgPKrZW00u0ikhCTF3qPwMzzNIbcjEQ,4509
+haystack_integrations/components/writers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/components/writers/mem0/__init__.py,sha256=ExDrh8bx6LIJs5OQzBuaapXIzD3o2ETuKe0-3Q3p1rI,225
+haystack_integrations/components/writers/mem0/writer.py,sha256=IeNm9_4jIz2Q9THhCJE47iz1aHp_9f7a0DPPsKCHrZQ,3416
+haystack_integrations/memory_stores/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/memory_stores/mem0/__init__.py,sha256=rAcc2e7rZMaqdWmGb7xmrT83D_HpE89QDVHbvpJ687U,340
+haystack_integrations/memory_stores/mem0/errors.py,sha256=CSPsuQKfPC7FEQCGGgtgjnY7-MHydQ7EM9crwZfJcCc,204
+haystack_integrations/memory_stores/mem0/filters.py,sha256=Jf3GdM6uCdQS4LrxvHz2ukTnPI0rGrFxVj6OQxZhjh8,8384
+haystack_integrations/memory_stores/mem0/memory_store.py,sha256=UQ1XjsM1sRnjIJFJmsHRzoVv1tvT0oj7uSskErke49I,9497
+haystack_integrations/tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/tools/mem0/__init__.py,sha256=Sd9pCAw-ZaanUJiubxsJYw_2HRRVMcb23gVHH3Ychg4,336
+haystack_integrations/tools/mem0/retriever_tool.py,sha256=g8Z6UkZUONYoTwKumbMMmqIa0zkndfpGkucGY91yzWQ,7284
+haystack_integrations/tools/mem0/writer_tool.py,sha256=CqfB0PoMSftMtpuzGj-4jqnt4n2Z9Wuige_pZKSXVD0,6513
+mem0_haystack-0.1.0.dist-info/METADATA,sha256=HQ38lFq90JIZEiMAY5DvYfpvwW0qPY1gBoUNeHdraPQ,1828
+mem0_haystack-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mem0_haystack-0.1.0.dist-info/licenses/LICENSE.txt,sha256=OrAtTu4aPmrTjKDSTzkSPgo_ji6NOMWO2N9JOTFyAzM,11350
+mem0_haystack-0.1.0.dist-info/RECORD,,

mem0_haystack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mem0_haystack-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023-present deepset GmbH
+
+   Licensed 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.