From 24655519c1d91b01398254f768c6d744a8129a3f Mon Sep 17 00:00:00 2001 From: visy-ani Date: Mon, 4 May 2026 14:22:38 +0530 Subject: [PATCH 1/8] docs: add Synap managed memory integration --- integrations/synap.md | 124 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 integrations/synap.md diff --git a/integrations/synap.md b/integrations/synap.md new file mode 100644 index 00000000..0d462a0e --- /dev/null +++ b/integrations/synap.md @@ -0,0 +1,124 @@ +--- +layout: integration +name: Synap +description: Add persistent, cross-session user memory to your Haystack agents and pipelines with Synap +authors: + - name: Maximem + socials: + github: maximem-ai + linkedin: https://www.linkedin.com/company/maximem/ +pypi: https://pypi.org/project/maximem-synap-haystack/ +repo: https://github.com/maximem-ai/maximem_synap +type: Memory Store +report_issue: https://github.com/maximem-ai/maximem_synap/issues +version: Haystack 2.0 +toc: true +--- + +### Table of Contents + +- [Overview](#overview) +- [Installation](#installation) +- [Usage](#usage) + - [SynapRetriever](#synapretriever) + - [SynapMemoryWriter](#synapmemorywriter) + - [Full Pipeline Example](#full-pipeline-example) + +## Overview + +[Synap](https://maximem.ai) is a managed memory layer for AI agents. The Haystack integration provides two native Haystack `@component` classes: + +- **`SynapRetriever`** — retrieves facts, preferences, episodes, and past context relevant to a query from the user's Synap memory and returns them as Haystack `Document` objects +- **`SynapMemoryWriter`** — records conversation turns to Synap so they are available for retrieval in future sessions + +Memory is scoped to the `user_id` and `customer_id` you provide, ensuring strict isolation in multi-tenant applications. + +## Installation + +```bash +pip install maximem-synap-haystack +``` + +Get an API key at [synap.maximem.ai](https://synap.maximem.ai). + +## Usage + +### SynapRetriever + +`SynapRetriever` is a standard Haystack component that takes a `query` string and returns a list of `Document` objects populated from the user's Synap memory. Plug it into any pipeline that needs long-term context before calling an LLM. + +```python +from haystack import Pipeline +from maximem_synap import MaximemSynapSDK +from synap_haystack import SynapRetriever + +sdk = MaximemSynapSDK(api_key="sk-...") + +retriever = SynapRetriever( + sdk=sdk, + user_id="user_123", + customer_id="acme_corp", +) + +pipeline = Pipeline() +pipeline.add_component("memory", retriever) +``` + +Each returned `Document` has a `content` field with the memory text and a `meta` dict that includes: + +| Key | Description | +|---|---| +| `type` | `"fact"`, `"preference"`, `"episode"`, `"emotion"`, `"temporal_event"` | +| `id` | Synap memory item ID | +| `confidence` / `strength` / `significance` | Relevance signal, type-dependent | + +### SynapMemoryWriter + +`SynapMemoryWriter` accepts a list of `Document` objects where `content` is the message text and `meta["role"]` is `"user"` or `"assistant"`. It records each turn to Synap so future retrieval requests can surface them. + +```python +from synap_haystack import SynapMemoryWriter + +writer = SynapMemoryWriter( + sdk=sdk, + conversation_id="conv_abc", + user_id="user_123", + customer_id="acme_corp", +) + +pipeline.add_component("memory_writer", writer) +``` + +The component returns `written_count`, `failed_count`, `skipped_count`, and `first_error` outputs so downstream components can branch on partial failures. If every document fails, it raises `SynapIntegrationError` — a 100% failure rate indicates a broken pipeline and should not be silenced. + +### Full Pipeline Example + +A complete retrieval-augmented pipeline that loads Synap context before the LLM and records turns afterward: + +```python +from haystack import Document, Pipeline +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from maximem_synap import MaximemSynapSDK +from synap_haystack import SynapMemoryWriter, SynapRetriever + +sdk = MaximemSynapSDK(api_key="sk-...") + +retriever = SynapRetriever(sdk=sdk, user_id="user_123", customer_id="acme_corp") +writer = SynapMemoryWriter( + sdk=sdk, conversation_id="session_1", user_id="user_123", customer_id="acme_corp" +) + +pipeline = Pipeline() +pipeline.add_component("memory", retriever) +pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o")) + +result = pipeline.run({"memory": {"query": "What are my dietary restrictions?"}}) +``` + +## More Resources + +- [Synap Documentation](https://docs.maximem.ai) +- [Haystack Integration Guide](https://docs.maximem.ai/integrations/haystack) +- [Dashboard](https://synap.maximem.ai) +- [PyPI: maximem-synap-haystack](https://pypi.org/project/maximem-synap-haystack/) From 9a253bcd6c8ef9f0f1a2b1681a319e5abd15dd5e Mon Sep 17 00:00:00 2001 From: Anish Yadav <80835632+visy-ani@users.noreply.github.com> Date: Mon, 4 May 2026 14:43:46 +0530 Subject: [PATCH 2/8] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- integrations/synap.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/integrations/synap.md b/integrations/synap.md index 0d462a0e..152d3ab3 100644 --- a/integrations/synap.md +++ b/integrations/synap.md @@ -48,11 +48,13 @@ Get an API key at [synap.maximem.ai](https://synap.maximem.ai). `SynapRetriever` is a standard Haystack component that takes a `query` string and returns a list of `Document` objects populated from the user's Synap memory. Plug it into any pipeline that needs long-term context before calling an LLM. ```python +import os + from haystack import Pipeline from maximem_synap import MaximemSynapSDK from synap_haystack import SynapRetriever -sdk = MaximemSynapSDK(api_key="sk-...") +sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_API_KEY"]) retriever = SynapRetriever( sdk=sdk, From 30f51c12cb869f65ed029302be7393259156c419 Mon Sep 17 00:00:00 2001 From: Anish Yadav <80835632+visy-ani@users.noreply.github.com> Date: Mon, 4 May 2026 17:03:58 +0530 Subject: [PATCH 3/8] docs(synap): add open source backlink to integration package --- integrations/synap.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/integrations/synap.md b/integrations/synap.md index 152d3ab3..f3447ebb 100644 --- a/integrations/synap.md +++ b/integrations/synap.md @@ -8,7 +8,7 @@ authors: github: maximem-ai linkedin: https://www.linkedin.com/company/maximem/ pypi: https://pypi.org/project/maximem-synap-haystack/ -repo: https://github.com/maximem-ai/maximem_synap +repo: https://github.com/maximem-ai/maximem_synap_sdk/tree/main/packages/integrations type: Memory Store report_issue: https://github.com/maximem-ai/maximem_synap/issues version: Haystack 2.0 @@ -124,3 +124,4 @@ result = pipeline.run({"memory": {"query": "What are my dietary restrictions?"}} - [Haystack Integration Guide](https://docs.maximem.ai/integrations/haystack) - [Dashboard](https://synap.maximem.ai) - [PyPI: maximem-synap-haystack](https://pypi.org/project/maximem-synap-haystack/) +- [Open source integration package](https://github.com/maximem-ai/maximem_synap_sdk/tree/main/packages/integrations) From 1c66d18bc22b60fca33e2e6191565bf47b2a69f9 Mon Sep 17 00:00:00 2001 From: Anish Yadav <80835632+visy-ani@users.noreply.github.com> Date: Mon, 4 May 2026 18:02:53 +0530 Subject: [PATCH 4/8] fix(synap): use env var for API key, remove unused imports, add writer to pipeline --- integrations/synap.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/integrations/synap.md b/integrations/synap.md index f3447ebb..5b0f8c73 100644 --- a/integrations/synap.md +++ b/integrations/synap.md @@ -98,13 +98,14 @@ The component returns `written_count`, `failed_count`, `skipped_count`, and `fir A complete retrieval-augmented pipeline that loads Synap context before the LLM and records turns afterward: ```python -from haystack import Document, Pipeline -from haystack.components.builders import ChatPromptBuilder +import os + +from haystack import Pipeline from haystack.components.generators.chat import OpenAIChatGenerator from maximem_synap import MaximemSynapSDK from synap_haystack import SynapMemoryWriter, SynapRetriever -sdk = MaximemSynapSDK(api_key="sk-...") +sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_API_KEY"]) retriever = SynapRetriever(sdk=sdk, user_id="user_123", customer_id="acme_corp") writer = SynapMemoryWriter( @@ -114,6 +115,7 @@ writer = SynapMemoryWriter( pipeline = Pipeline() pipeline.add_component("memory", retriever) pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o")) +pipeline.add_component("memory_writer", writer) result = pipeline.run({"memory": {"query": "What are my dietary restrictions?"}}) ``` From 5e526755528146e93b0e869725374c723bb8741c Mon Sep 17 00:00:00 2001 From: Anish Yadav <80835632+visy-ani@users.noreply.github.com> Date: Mon, 4 May 2026 23:26:03 +0530 Subject: [PATCH 5/8] fix(synap): simplify Full Pipeline Example to runnable retrieval-only snippet --- integrations/synap.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/integrations/synap.md b/integrations/synap.md index 5b0f8c73..67a3fcca 100644 --- a/integrations/synap.md +++ b/integrations/synap.md @@ -95,31 +95,30 @@ The component returns `written_count`, `failed_count`, `skipped_count`, and `fir ### Full Pipeline Example -A complete retrieval-augmented pipeline that loads Synap context before the LLM and records turns afterward: +A retrieval pipeline that surfaces relevant Synap memories as Haystack `Document` objects, ready to inject into any downstream component: ```python import os from haystack import Pipeline -from haystack.components.generators.chat import OpenAIChatGenerator from maximem_synap import MaximemSynapSDK -from synap_haystack import SynapMemoryWriter, SynapRetriever +from synap_haystack import SynapRetriever sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_API_KEY"]) -retriever = SynapRetriever(sdk=sdk, user_id="user_123", customer_id="acme_corp") -writer = SynapMemoryWriter( - sdk=sdk, conversation_id="session_1", user_id="user_123", customer_id="acme_corp" -) - pipeline = Pipeline() -pipeline.add_component("memory", retriever) -pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o")) -pipeline.add_component("memory_writer", writer) +pipeline.add_component( + "memory", + SynapRetriever(sdk=sdk, user_id="user_123", customer_id="acme_corp"), +) result = pipeline.run({"memory": {"query": "What are my dietary restrictions?"}}) +for doc in result["memory"]["documents"]: + print(doc.content) ``` +To record conversation turns, add `SynapMemoryWriter` as a separate pipeline step and supply it with `Document` objects whose `meta["role"]` is `"user"` or `"assistant"`. Wire components together with `pipeline.connect()` to match your application's prompt-building and LLM architecture. + ## More Resources - [Synap Documentation](https://docs.maximem.ai) From a24e2ef047ef1be3443608a66888e2f6c700e7f0 Mon Sep 17 00:00:00 2001 From: Anish Yadav <80835632+visy-ani@users.noreply.github.com> Date: Sat, 16 May 2026 18:04:18 +0530 Subject: [PATCH 6/8] =?UTF-8?q?docs(synap):=20address=20review=20=E2=80=94?= =?UTF-8?q?=20fix=20repo=20path,=20add=20License=20section=20+=20TOC=20ent?= =?UTF-8?q?ry?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- integrations/synap.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/integrations/synap.md b/integrations/synap.md index 67a3fcca..dc074726 100644 --- a/integrations/synap.md +++ b/integrations/synap.md @@ -8,7 +8,7 @@ authors: github: maximem-ai linkedin: https://www.linkedin.com/company/maximem/ pypi: https://pypi.org/project/maximem-synap-haystack/ -repo: https://github.com/maximem-ai/maximem_synap_sdk/tree/main/packages/integrations +repo: https://github.com/maximem-ai/maximem_synap_sdk/tree/main/packages/integrations/synap-haystack type: Memory Store report_issue: https://github.com/maximem-ai/maximem_synap/issues version: Haystack 2.0 @@ -23,6 +23,7 @@ toc: true - [SynapRetriever](#synapretriever) - [SynapMemoryWriter](#synapmemorywriter) - [Full Pipeline Example](#full-pipeline-example) +- [License](#license) ## Overview @@ -125,4 +126,8 @@ To record conversation turns, add `SynapMemoryWriter` as a separate pipeline ste - [Haystack Integration Guide](https://docs.maximem.ai/integrations/haystack) - [Dashboard](https://synap.maximem.ai) - [PyPI: maximem-synap-haystack](https://pypi.org/project/maximem-synap-haystack/) -- [Open source integration package](https://github.com/maximem-ai/maximem_synap_sdk/tree/main/packages/integrations) +- [Open source integration package](https://github.com/maximem-ai/maximem_synap_sdk/tree/main/packages/integrations/synap-haystack) + +## License + +`maximem-synap-haystack` is released under the [Apache License 2.0](https://github.com/maximem-ai/maximem_synap_sdk/blob/main/LICENSE). From bf515e8af8b669f17254ec362487db6465e08022 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kacper=20=C5=81ukawski?= Date: Mon, 25 May 2026 17:05:47 +0200 Subject: [PATCH 7/8] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- integrations/synap.md | 1 + 1 file changed, 1 insertion(+) diff --git a/integrations/synap.md b/integrations/synap.md index dc074726..27021b4f 100644 --- a/integrations/synap.md +++ b/integrations/synap.md @@ -23,6 +23,7 @@ toc: true - [SynapRetriever](#synapretriever) - [SynapMemoryWriter](#synapmemorywriter) - [Full Pipeline Example](#full-pipeline-example) +- [More Resources](#more-resources) - [License](#license) ## Overview From 118c619e63471b389ab7091318d3221faeaa7799 Mon Sep 17 00:00:00 2001 From: Anish Yadav <80835632+visy-ani@users.noreply.github.com> Date: Wed, 3 Jun 2026 18:24:02 +0530 Subject: [PATCH 8/8] docs(synap): restructure around SynapMemoryStore to match Mem0 pattern --- integrations/synap.md | 111 ++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 54 deletions(-) diff --git a/integrations/synap.md b/integrations/synap.md index 27021b4f..1793c056 100644 --- a/integrations/synap.md +++ b/integrations/synap.md @@ -20,106 +20,109 @@ toc: true - [Overview](#overview) - [Installation](#installation) - [Usage](#usage) - - [SynapRetriever](#synapretriever) - - [SynapMemoryWriter](#synapmemorywriter) - - [Full Pipeline Example](#full-pipeline-example) + - [Available Classes](#available-classes) + - [Standalone Memory Operations](#standalone-memory-operations) + - [Use in a Pipeline](#use-in-a-pipeline) - [More Resources](#more-resources) - [License](#license) ## Overview -[Synap](https://maximem.ai) is a managed memory layer for AI agents. The Haystack integration provides two native Haystack `@component` classes: +[Synap](https://maximem.ai) is a managed long-term memory layer for AI agents. It runs a full extraction pipeline on every conversation turn — automatically identifying facts, preferences, episodes, emotions, and temporal events — and retrieves only what is semantically relevant to the current query. -- **`SynapRetriever`** — retrieves facts, preferences, episodes, and past context relevant to a query from the user's Synap memory and returns them as Haystack `Document` objects -- **`SynapMemoryWriter`** — records conversation turns to Synap so they are available for retrieval in future sessions +The `maximem-synap-haystack` package provides a Haystack-native memory store that follows the same shape as `mem0-haystack`: + +- **`SynapMemoryStore`**: A persistent memory store backed by the Synap API. Owns all SDK interaction (`add_memories` / `search_memories` / `search_memories_as_single_message`). +- **`SynapMemoryRetriever`** and **`SynapMemoryWriter`**: Pipeline `@component` classes for retrieving memories as `ChatMessage` objects and writing conversation turns to the store. +- **`SynapRetriever`**: An additional `@component` that returns memories as `Document` objects for classic RAG-style pipelines. Memory is scoped to the `user_id` and `customer_id` you provide, ensuring strict isolation in multi-tenant applications. +More information: + +- [Synap website](https://maximem.ai) +- [Synap documentation](https://docs.maximem.ai) +- [Synap GitHub repository](https://github.com/maximem-ai/maximem_synap_sdk) + ## Installation ```bash pip install maximem-synap-haystack ``` -Get an API key at [synap.maximem.ai](https://synap.maximem.ai). +Set your Synap API key: + +```bash +export SYNAP_API_KEY="your-synap-api-key" +``` + +You can obtain an API key at [synap.maximem.ai](https://synap.maximem.ai). ## Usage -### SynapRetriever +### Available Classes + +- **`SynapMemoryStore`**: The memory store — a plain object (not a `@component`) that owns all Synap SDK interaction. Use it directly for standalone read/write, or pass it to the components below. +- **`SynapMemoryRetriever`**: Retrieves memories from Synap as system `ChatMessage` objects. Mem0-shaped chat read path. +- **`SynapMemoryWriter`**: Writes user / assistant `ChatMessage` objects to Synap. Returns per-message status so callers can branch on partial failures. +- **`SynapRetriever`**: Alternate retriever that returns Haystack `Document` objects (RAG-style read path). + +### Standalone Memory Operations -`SynapRetriever` is a standard Haystack component that takes a `query` string and returns a list of `Document` objects populated from the user's Synap memory. Plug it into any pipeline that needs long-term context before calling an LLM. +You can use `SynapMemoryStore` directly to add and search memories: ```python import os -from haystack import Pipeline +from haystack.dataclasses import ChatMessage from maximem_synap import MaximemSynapSDK -from synap_haystack import SynapRetriever +from synap_haystack import SynapMemoryStore sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_API_KEY"]) +store = SynapMemoryStore(sdk, user_id="alice", customer_id="acme_corp") -retriever = SynapRetriever( - sdk=sdk, - user_id="user_123", - customer_id="acme_corp", -) - -pipeline = Pipeline() -pipeline.add_component("memory", retriever) -``` - -Each returned `Document` has a `content` field with the memory text and a `meta` dict that includes: - -| Key | Description | -|---|---| -| `type` | `"fact"`, `"preference"`, `"episode"`, `"emotion"`, `"temporal_event"` | -| `id` | Synap memory item ID | -| `confidence` / `strength` / `significance` | Relevance signal, type-dependent | - -### SynapMemoryWriter - -`SynapMemoryWriter` accepts a list of `Document` objects where `content` is the message text and `meta["role"]` is `"user"` or `"assistant"`. It records each turn to Synap so future retrieval requests can surface them. - -```python -from synap_haystack import SynapMemoryWriter - -writer = SynapMemoryWriter( - sdk=sdk, +# Write — extracted server-side into long-term memory +store.add_memories( + messages=[ChatMessage.from_user("I prefer window seats and aisle on red-eyes.")], conversation_id="conv_abc", - user_id="user_123", - customer_id="acme_corp", ) -pipeline.add_component("memory_writer", writer) -``` +# Read — semantic, query-driven +memories = store.search_memories(query="seat preference") +for msg in memories: + print(msg.text) -The component returns `written_count`, `failed_count`, `skipped_count`, and `first_error` outputs so downstream components can branch on partial failures. If every document fails, it raises `SynapIntegrationError` — a 100% failure rate indicates a broken pipeline and should not be silenced. +# Single-message variant — useful for prompt injection +context = store.search_memories_as_single_message(query="seat preference") +``` -### Full Pipeline Example +### Use in a Pipeline -A retrieval pipeline that surfaces relevant Synap memories as Haystack `Document` objects, ready to inject into any downstream component: +`SynapMemoryRetriever` and `SynapMemoryWriter` are thin `@component` wrappers around the store. Construct the store once and share it across both: ```python import os from haystack import Pipeline +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator from maximem_synap import MaximemSynapSDK -from synap_haystack import SynapRetriever +from synap_haystack import SynapMemoryRetriever, SynapMemoryStore, SynapMemoryWriter sdk = MaximemSynapSDK(api_key=os.environ["SYNAP_API_KEY"]) +store = SynapMemoryStore(sdk, user_id="alice", customer_id="acme_corp") pipeline = Pipeline() -pipeline.add_component( - "memory", - SynapRetriever(sdk=sdk, user_id="user_123", customer_id="acme_corp"), -) +pipeline.add_component("memory_retriever", SynapMemoryRetriever(store=store)) +pipeline.add_component("prompt_builder", ChatPromptBuilder()) +pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o")) +pipeline.add_component("memory_writer", SynapMemoryWriter(store=store)) -result = pipeline.run({"memory": {"query": "What are my dietary restrictions?"}}) -for doc in result["memory"]["documents"]: - print(doc.content) +pipeline.connect("memory_retriever.messages", "prompt_builder.template") +pipeline.connect("prompt_builder.prompt", "llm.messages") ``` -To record conversation turns, add `SynapMemoryWriter` as a separate pipeline step and supply it with `Document` objects whose `meta["role"]` is `"user"` or `"assistant"`. Wire components together with `pipeline.connect()` to match your application's prompt-building and LLM architecture. +For classic RAG pipelines that want `Document` objects rather than `ChatMessage` objects, use `SynapRetriever` instead of `SynapMemoryRetriever` — same store, different output shape. ## More Resources