Skip to content

Commit 3b82648

Browse files
sjrlsjrl
authored
docs: Add docs for mem0 integration (#11357)
1 parent 3d90a53 commit 3b82648

28 files changed

Lines changed: 950 additions & 2 deletions

‎docs-website/docs/pipeline-components/retrievers.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,7 @@ For details on how to initialize and use a Retriever in a pipeline, see the docu
168168
| [InMemoryBM25Retriever](retrievers/inmemorybm25retriever.mdx) | A keyword-based Retriever compatible with the InMemoryDocumentStore. |
169169
| [InMemoryEmbeddingRetriever](retrievers/inmemoryembeddingretriever.mdx) | An embedding-based Retriever compatible with the InMemoryDocumentStore. |
170170
| [FilterRetriever](retrievers/filterretriever.mdx) | A special Retriever to be used with any Document Store to get the Documents that match specific filters. |
171+
| [Mem0MemoryRetriever](retrievers/mem0memoryretriever.mdx) | Retrieves ChatMessage memories from Mem0 for memory-augmented Agent and pipeline workflows. |
171172
| [MultiQueryEmbeddingRetriever](retrievers/multiqueryembeddingretriever.mdx) | Retrieves documents using multiple queries in parallel with an embedding-based Retriever. |
172173
| [MultiQueryTextRetriever](retrievers/multiquerytextretriever.mdx) | Retrieves documents using multiple queries in parallel with a text-based Retriever. |
173174
| [MultiRetriever](retrievers/multiretriever.mdx) | Runs multiple text retrievers in parallel and combines their deduplicated results. Experimental. |

‎docs-website/docs/pipeline-components/retrievers/mem0memoryretriever.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: "Mem0MemoryRetriever"
3+
id: mem0memoryretriever
4+
slug: "/mem0memoryretriever"
5+
description: "Retrieves long-term memories from Mem0 as ChatMessage objects."
6+
---
7+
8+
# Mem0MemoryRetriever
9+
10+
Retrieves long-term memories from Mem0 as `ChatMessage` objects.
11+
12+
<div className="key-value-table">
13+
14+
| | |
15+
| --- | --- |
16+
| **Most common position in a pipeline** | Before an [`Agent`](../agents-1/agent.mdx) or Chat Generator in memory-augmented pipelines |
17+
| **Mandatory init variables** | `memory_store`: A `Mem0MemoryStore` instance |
18+
| **Mandatory run variables** | `query`: A text query or `None`; at least one Mem0 scope through `user_id`, `run_id`, `agent_id`, `app_id`, or `filters` |
19+
| **Output variables** | `memories`: A list of `ChatMessage` objects |
20+
| **Mem0 API docs** | [Search Memories](https://docs.mem0.ai/api-reference/memory/search-memories), [Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters) |
21+
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mem0 |
22+
| **Package name** | `mem0-haystack` |
23+
24+
</div>
25+
26+
## Overview
27+
28+
`Mem0MemoryRetriever` retrieves memories from a `Mem0MemoryStore` and returns them as system `ChatMessage` objects.
29+
Use it to inject long-term memory into an Agent or a chat generation pipeline before the model produces a response.
30+
31+
The `query` input can be a string or `None`.
32+
When `query` is a string, the component searches for relevant memories and applies `top_k`.
33+
When `query` is `None`, it returns all memories matching the provided scope.
34+
35+
Scope the retrieval with at least one Mem0 entity ID: `user_id`, `run_id`, `agent_id`, or `app_id`.
36+
You can also pass Haystack-style `filters`; when filters and ID parameters are both provided, they are combined with an `AND` condition.
37+
For general filter syntax, see [Metadata Filtering](../../concepts/metadata-filtering.mdx).
38+
39+
User-provided Mem0 metadata is included in each returned message's `meta`.
40+
Mem0 retrieval fields such as `memory_id`, `user_id`, `score`, and timestamps are included under `meta["mem0"]`.
41+
42+
### Installation
43+
44+
Install the Mem0 integration:
45+
46+
```shell
47+
pip install mem0-haystack
48+
```
49+
50+
Set your Mem0 API key:
51+
52+
```shell
53+
export MEM0_API_KEY="your-mem0-api-key"
54+
```
55+
56+
## Usage
57+
58+
### On its own
59+
60+
```python
61+
from haystack.dataclasses import ChatMessage
62+
63+
from haystack_integrations.components.retrievers.mem0 import Mem0MemoryRetriever
64+
from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
65+
66+
store = Mem0MemoryStore()
67+
store.add_memories(
68+
messages=[ChatMessage.from_user("Alice prefers concise Python examples.")],
69+
user_id="alice",
70+
infer=False,
71+
)
72+
73+
retriever = Mem0MemoryRetriever(memory_store=store, top_k=3)
74+
75+
result = retriever.run(query="answer style", user_id="alice")
76+
memories = result["memories"]
77+
78+
for memory in memories:
79+
print(memory.text)
80+
```
81+
82+
To retrieve all memories in scope, pass `query=None`:
83+
84+
```python
85+
all_memories = retriever.run(query=None, user_id="alice")["memories"]
86+
print([memory.text for memory in all_memories])
87+
```
88+
89+
### In a Pipeline
90+
91+
This example retrieves memories, prepends them to the current user message, and passes the combined message list to an Agent.
92+
93+
```python
94+
from haystack import Pipeline
95+
from haystack.components.agents import Agent
96+
from haystack.components.converters import OutputAdapter
97+
from haystack.components.generators.chat import OpenAIChatGenerator
98+
from haystack.components.generators.utils import print_streaming_chunk
99+
from haystack.dataclasses import ChatMessage
100+
101+
from haystack_integrations.components.retrievers.mem0 import Mem0MemoryRetriever
102+
from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
103+
104+
store = Mem0MemoryStore()
105+
106+
pipeline = Pipeline()
107+
pipeline.add_component("retriever", Mem0MemoryRetriever(memory_store=store, top_k=5))
108+
pipeline.add_component(
109+
"memory_context",
110+
OutputAdapter(
111+
template="{{ memories + user_messages }}",
112+
output_type=list[ChatMessage],
113+
unsafe=True,
114+
),
115+
)
116+
pipeline.add_component(
117+
"agent",
118+
Agent(
119+
chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
120+
system_prompt=(
121+
"Use any system messages at the start of the conversation as long-term memory. "
122+
"Answer concisely."
123+
),
124+
streaming_callback=print_streaming_chunk,
125+
),
126+
)
127+
128+
pipeline.connect("retriever.memories", "memory_context.memories")
129+
pipeline.connect("memory_context.output", "agent.messages")
130+
131+
query = "Give me a short implementation tip."
132+
133+
pipeline.run(
134+
{
135+
"retriever": {
136+
"query": query,
137+
"user_id": "alice",
138+
},
139+
"memory_context": {
140+
"user_messages": [
141+
ChatMessage.from_user(query),
142+
],
143+
},
144+
},
145+
)
146+
```

‎docs-website/docs/pipeline-components/writers/mem0memorywriter.mdx‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
title: "Mem0MemoryWriter"
3+
id: mem0memorywriter
4+
slug: "/mem0memorywriter"
5+
description: "Writes ChatMessage objects to Mem0 as long-term memories."
6+
---
7+
8+
# Mem0MemoryWriter
9+
10+
Writes `ChatMessage` objects to Mem0 as long-term memories.
11+
12+
<div className="key-value-table">
13+
14+
| | |
15+
| --- | --- |
16+
| **Most common position in a pipeline** | After an [`Agent`](../agents-1/agent.mdx) or Chat Generator in memory-augmented pipelines |
17+
| **Mandatory init variables** | `memory_store`: A `Mem0MemoryStore` instance |
18+
| **Mandatory run variables** | `messages`: A list of `ChatMessage` objects; at least one Mem0 scope through `user_id`, `run_id`, `agent_id`, or `app_id` |
19+
| **Output variables** | `memories_written`: The number of memories written |
20+
| **Mem0 API docs** | [Add Memories](https://docs.mem0.ai/api-reference/memory/add-memories) |
21+
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mem0 |
22+
| **Package name** | `mem0-haystack` |
23+
24+
</div>
25+
26+
## Overview
27+
28+
`Mem0MemoryWriter` writes a list of `ChatMessage` objects to a `Mem0MemoryStore`. Use it near the end of a memory-augmented pipeline to persist conversation facts, user preferences, and durable project context for future runs.
29+
30+
Scope written memories with at least one Mem0 entity ID: `user_id`, `run_id`, `agent_id`, or `app_id`. These are runtime inputs, so one pipeline instance can write memories for multiple users, sessions, agents, or applications.
31+
32+
The `infer` init parameter controls how Mem0 stores the incoming messages:
33+
34+
- `infer=True` lets Mem0 extract memories from the messages. This is useful when writing a full Agent turn that includes the user message, tool context, and final assistant response.
35+
- `infer=False` stores the supplied message text as-is. This is useful when the upstream component has already selected the exact memory text.
36+
37+
### Installation
38+
39+
Install the Mem0 integration:
40+
41+
```shell
42+
pip install mem0-haystack
43+
```
44+
45+
Set your Mem0 API key:
46+
47+
```shell
48+
export MEM0_API_KEY="your-mem0-api-key"
49+
```
50+
51+
## Usage
52+
53+
### On its own
54+
55+
```python
56+
from haystack.dataclasses import ChatMessage
57+
58+
from haystack_integrations.components.writers.mem0 import Mem0MemoryWriter
59+
from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
60+
61+
store = Mem0MemoryStore()
62+
writer = Mem0MemoryWriter(memory_store=store, infer=False)
63+
64+
result = writer.run(
65+
messages=[ChatMessage.from_user("Alice prefers concise Python examples.")],
66+
user_id="alice",
67+
)
68+
69+
print(result["memories_written"])
70+
```
71+
72+
### In a Pipeline
73+
74+
This example connects an Agent's full `messages` output to `Mem0MemoryWriter` with `infer=True`, so Mem0 can extract memories from the full turn context.
75+
76+
```python
77+
from haystack import Pipeline
78+
from haystack.components.agents import Agent
79+
from haystack.components.generators.chat import OpenAIChatGenerator
80+
from haystack.components.generators.utils import print_streaming_chunk
81+
from haystack.dataclasses import ChatMessage
82+
83+
from haystack_integrations.components.writers.mem0 import Mem0MemoryWriter
84+
from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore
85+
86+
store = Mem0MemoryStore()
87+
88+
pipeline = Pipeline()
89+
pipeline.add_component(
90+
"agent",
91+
Agent(
92+
chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
93+
system_prompt=(
94+
"Answer the user and preserve durable user facts or preferences for future conversations."
95+
),
96+
streaming_callback=print_streaming_chunk,
97+
),
98+
)
99+
pipeline.add_component("writer", Mem0MemoryWriter(memory_store=store, infer=True))
100+
101+
pipeline.connect("agent.messages", "writer.messages")
102+
103+
result = pipeline.run(
104+
{
105+
"agent": {
106+
"messages": [
107+
ChatMessage.from_user(
108+
"My name is Alice and I prefer concise Python examples.",
109+
),
110+
],
111+
},
112+
"writer": {
113+
"user_id": "alice",
114+
},
115+
},
116+
)
117+
118+
print(result["writer"]["memories_written"])
119+
```

‎docs-website/docs/tools/mcptool.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ MCPTool enables integration with external tools and services through the Model C
1616
| **Mandatory init variables** | `name`: The name of the tool<br />`server_info`: Information about the MCP server to connect to |
1717
| **API reference** | [MCP](/reference/integrations-mcp) |
1818
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mcp |
19+
| **Package name** | `mcp-haystack` |
1920

2021
</div>
2122

‎docs-website/docs/tools/mcptoolset.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ description: "`MCPToolset` connects to an MCP-compliant server and automatically
1616
| **Mandatory init variables** | `server_info`: Information about the MCP server to connect to |
1717
| **API reference** | [mcp](/reference/integrations-mcp) |
1818
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/mcp |
19+
| **Package name** | `mcp-haystack` |
1920

2021
</div>
2122

‎docs-website/docs/tools/ready-made-tools.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: "Ready-Made Tools"
3+
id: ready-made-tools
4+
slug: "/ready-made-tools"
5+
description: "Ready-made Tools and Toolsets in Haystack provide prebuilt capabilities for common Agent workflows."
6+
---
7+
8+
# Ready-Made Tools
9+
10+
Ready-made Tools and Toolsets provide prebuilt capabilities for common Agent workflows. You can pass them directly to an [Agent](../pipeline-components/agents-1/agent.mdx), use them with a [ToolInvoker](../pipeline-components/tools/toolinvoker.mdx), or inspect their function and parameter schema when you need to customize their behavior.
11+
12+
These are the ready-made Tools and Toolsets available in Haystack:
13+
14+
| Tool or Toolset | Description |
15+
| --- | --- |
16+
| [E2BToolset](ready-made-tools/e2btoolset.mdx) | Gives Agents access to a live E2B cloud sandbox for executing bash commands and managing files. |
17+
| [GitHubFileEditorTool](ready-made-tools/githubfileeditortool.mdx) | Edits files in GitHub repositories. |
18+
| [GitHubIssueCommenterTool](ready-made-tools/githubissuecommentertool.mdx) | Posts comments to GitHub issues. |
19+
| [GitHubIssueViewerTool](ready-made-tools/githubissueviewertool.mdx) | Fetches and parses GitHub issues into documents. |
20+
| [GitHubPRCreatorTool](ready-made-tools/githubprcreatortool.mdx) | Creates pull requests from a fork back to the original repository. |
21+
| [GitHubRepoViewerTool](ready-made-tools/githubrepoviewertool.mdx) | Navigates and fetches content from GitHub repositories. |
22+
| [Mem0MemoryRetrieverTool](ready-made-tools/mem0memorytools.mdx) | Retrieves long-term memories from Mem0 for Agent workflows. |
23+
| [Mem0MemoryWriterTool](ready-made-tools/mem0memorytools.mdx) | Stores long-term memories in Mem0 for future Agent runs. |

‎docs-website/docs/tools/ready-made-tools/e2btoolset.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ A Toolset that gives Agents access to a live [E2B](https://e2b.dev/) cloud sandb
1616
| **Mandatory init variables** | `api_key`: E2B API key. Can be set with `E2B_API_KEY` env var. |
1717
| **API reference** | [E2B](/reference/integrations-e2b) |
1818
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/e2b |
19+
| **Package name** | `e2b-haystack` |
1920

2021
</div>
2122

‎docs-website/docs/tools/ready-made-tools/githubfileeditortool.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ A Tool that allows Agents and ToolInvokers to edit files in GitHub repositories.
1616
| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
1717
| **API reference** | [Tools](/reference/tools-api) |
1818
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
19+
| **Package name** | `github-haystack` |
1920

2021
</div>
2122

‎docs-website/docs/tools/ready-made-tools/githubissuecommentertool.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ A Tool that allows Agents and ToolInvokers to post comments to GitHub issues.
1616
| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var. |
1717
| **API reference** | [Tools](/reference/tools-api) |
1818
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
19+
| **Package name** | `github-haystack` |
1920

2021
</div>
2122

‎docs-website/docs/tools/ready-made-tools/githubissueviewertool.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ A Tool that allows Agents and ToolInvokers to fetch and parse GitHub issues into
1515
| --- | --- |
1616
| **API reference** | [Tools](/reference/tools-api) |
1717
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
18+
| **Package name** | `github-haystack` |
1819

1920
</div>
2021

0 commit comments

Comments
 (0)