Mem0

haystack_integrations.components.retrievers.mem0.retriever

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"]

init

python

__init__(*, memory_store: Mem0MemoryStore, top_k: int = 5) -> None

Initialize the Mem0MemoryRetriever.

Parameters:

• memory_store (Mem0MemoryStore) – The Mem0MemoryStore instance to retrieve memories from.
• top_k (int) – Default maximum number of memories to return per query.

run

python

run(
    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.

Parameters:

• query (str | None) – Text query used to search for relevant memories. Pass None to retrieve all memories matching the scope.
• user_id (str | None) – User ID to scope the search.
• run_id (str | None) – Run ID to scope the search.
• agent_id (str | None) – Agent ID to scope the search.
• app_id (str | None) – App ID to scope the search.
• filters (dict[str, Any] | None) – 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 and Memory Filters. Fields that are not native Mem0 filter fields are treated as Mem0 metadata fields.
• top_k (int | None) – Maximum number of memories to return. Overrides the init-time default.

Returns:

• dict[str, list[ChatMessage]] – 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"].

to_dict

python

to_dict() -> dict[str, Any]

Serialize this component to a dictionary.

from_dict

python

from_dict(data: dict[str, Any]) -> Mem0MemoryRetriever

Deserialize this component from a dictionary.

haystack_integrations.components.writers.mem0.writer

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"])

init

python

__init__(*, memory_store: Mem0MemoryStore, infer: bool = True) -> None

Initialize the Mem0MemoryWriter.

Parameters:

• memory_store (Mem0MemoryStore) – The Mem0MemoryStore instance to write memories to.
• infer (bool) – If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.

run

python

run(
    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.

Parameters:

• messages (list[ChatMessage]) – List of ChatMessage objects to store.
• user_id (str | None) – User ID to scope the stored memories.
• run_id (str | None) – Run ID to scope the stored memories.
• agent_id (str | None) – Agent ID to scope the stored memories.
• app_id (str | None) – App ID to scope the stored memories.

Returns:

• dict[str, int] – Dictionary with key memories_written containing the count of stored memory items.

to_dict

python

to_dict() -> dict[str, Any]

Serialize this component to a dictionary.

from_dict

python

from_dict(data: dict[str, Any]) -> Mem0MemoryWriter

Deserialize this component from a dictionary.

haystack_integrations.memory_stores.mem0.errors

Mem0MemoryStoreError

Bases: RuntimeError

Raised when a Mem0 API operation fails.

haystack_integrations.memory_stores.mem0.memory_store

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.

init

python

__init__(*, 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).

Parameters:

• api_key (Secret) – The Mem0 API key. Defaults to the MEM0_API_KEY environment variable.

warm_up

python

warm_up() -> 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.

client

python

client: MemoryClient

Return the initialized client, calling warm_up() if necessary.

to_dict

python

to_dict() -> dict[str, Any]

Serialize the store configuration to a dictionary.

from_dict

python

from_dict(data: dict[str, Any]) -> Mem0MemoryStore

Deserialize the store from a dictionary.

add_memories

python

add_memories(
    *,
    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.

Parameters:

• messages (list[ChatMessage]) – List of ChatMessage objects to store as memories.
• user_id (str | None) – User ID to scope these memories.
• run_id (str | None) – Run ID to scope these memories.
• agent_id (str | None) – Agent ID to scope these memories. Required for Mem0 to store assistant messages.
• app_id (str | None) – App ID to scope these memories.
• infer (bool) – If True, Mem0 extracts memories from messages. If False, Mem0 stores message text as-is.
• kwargs (Any) – 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[dict[str, Any]] – List of objects with memory_id and memory text for each stored memory.

Raises:

• Mem0MemoryStoreError – If the Mem0 API call fails.

search_memories

python

search_memories(
    *,
    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.

Parameters:

• query (str | None) – Text query to search. If omitted, returns all memories matching the scope.
• filters (dict[str, Any] | None) – Haystack-style filters to apply. See Haystack metadata filtering. Mem0 requires entity IDs inside filters and supports a fixed set of native fields and operators: Search Memories API and Memory Filters. Fields that are not native Mem0 filter fields are treated as Mem0 metadata fields.
• top_k (int) – Maximum number of results to return.
• user_id (str | None) – User ID to scope the search.
• run_id (str | None) – Run ID to scope the search.
• agent_id (str | None) – Agent ID to scope the search.
• app_id (str | None) – App ID to scope the search.
• kwargs (Any) – Additional keyword arguments forwarded to the Mem0 client.

Returns:

• list[ChatMessage] – 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.

haystack_integrations.tools.mem0.retriever_tool

Mem0MemoryRetrieverTool

Bases: 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)

init

python

__init__(
    *,
    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.

Parameters:

• memory_store (Mem0MemoryStore) – The Mem0MemoryStore instance to query.
• top_k (int) – Default maximum number of memories to return. The LLM may override this.
• name (str) – Tool name exposed to the LLM.
• description (str) – Tool description exposed to the LLM.
• parameters (dict[str, Any]) – JSON schema for the parameters exposed to the LLM. Defaults to optional query and top_k.
• inputs_from_state (dict[str, str]) – 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"}.

warm_up

python

warm_up() -> None

Initialize the Mem0 client. Subsequent calls are no-ops.

retrieve

python

retrieve(
    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.

Parameters:

• query (str | None) – Text query used to search for relevant memories. If omitted or None, all memories matching the scope are returned.
• top_k (int | None) – Maximum number of memories to return for query searches. Overrides the tool default.
• user_id (str | None) – User ID to scope the search. Injected from Agent State by default.
• run_id (str | None) – Run ID to scope the search. Can be injected with a custom inputs_from_state mapping.
• agent_id (str | None) – Agent ID to scope the search. Can be injected with a custom inputs_from_state mapping.
• app_id (str | None) – App ID to scope the search. Can be injected with a custom inputs_from_state mapping.

Returns:

• str – Retrieved memories formatted for the Agent, or a message when no memories were found.

to_dict

python

to_dict() -> dict[str, Any]

Serialize this tool to a dictionary.

from_dict

python

from_dict(data: dict[str, Any]) -> Mem0MemoryRetrieverTool

Deserialize this tool from a dictionary.

haystack_integrations.tools.mem0.writer_tool

Mem0MemoryWriterTool

Bases: 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)

init

python

__init__(
    *,
    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.

Parameters:

• memory_store (Mem0MemoryStore) – The Mem0MemoryStore instance to write to.
• name (str) – Tool name exposed to the LLM.
• description (str) – Tool description exposed to the LLM.
• parameters (dict[str, Any]) – JSON schema for the parameters exposed to the LLM. Defaults to text and infer.
• inputs_from_state (dict[str, str]) – 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"}.

warm_up

python

warm_up() -> None

Initialize the Mem0 client. Subsequent calls are no-ops.

store

python

store(
    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.

Parameters:

• text (str) – The information to store as a memory.
• infer (bool) – If True, Mem0 extracts memories from the text. If False, Mem0 stores the text as-is.
• user_id (str | None) – User ID to scope the stored memory. Injected from Agent State by default.
• run_id (str | None) – Run ID to scope the stored memory. Can be injected with a custom inputs_from_state mapping.
• agent_id (str | None) – Agent ID to scope the stored memory. Can be injected with a custom inputs_from_state mapping.
• app_id (str | None) – App ID to scope the stored memory. Can be injected with a custom inputs_from_state mapping.

Returns:

• str – A string indicating how many memory items were stored.

to_dict

python

to_dict() -> dict[str, Any]

Serialize this tool to a dictionary.

from_dict

python

from_dict(data: dict[str, Any]) -> Mem0MemoryWriterTool

Deserialize this tool from a dictionary.