refactor(haystack): rename HindsightToolset -> HindsightMemoryWrapper (#2118)

The class subclasses Haystack's `Toolset` but is used as an automatic
memory wrapper (auto_recall / auto_retain around an Agent), not a tool
collection. Reusing the `Toolset` name was confusing next to Haystack's
own `Toolset` abstraction — flagged by deepset DevRel in review of the
haystack-integrations gallery entry (deepset-ai/haystack-integrations#505).

Pure rename across the package, tests, README, and docs pages. The class
still subclasses `haystack.tools.Toolset`. No backward-compat alias — the
package is at 0.1.0 with no adoption yet, so the rename is clean.

Co-authored-by: DK09876 <dk09876@Dikshants-MacBook-Pro.local>

Author: DK09876

hindsight-docs/docs-integrations/haystack.md

@@ -1,15 +1,15 @@
 ---
 sidebar_position: 34
 title: "Haystack Persistent Memory with Hindsight | Integration"
-description: "Add persistent long-term memory to Haystack agents with Hindsight. Provides retain/recall/reflect Tools plus a HindsightToolset with optional auto-recall and auto-retain."
+description: "Add persistent long-term memory to Haystack agents with Hindsight. Provides retain/recall/reflect Tools plus a HindsightMemoryWrapper with optional auto-recall and auto-retain."
 ---
 
 # Haystack
 
 Persistent long-term memory for [Haystack](https://haystack.deepset.ai/) agents via Hindsight. The `hindsight-haystack` package gives you two complementary patterns:
 
 - **`create_hindsight_tools(...)`** — Returns a list of Haystack `Tool`s (`retain_memory`, `recall_memory`, `reflect_on_memory`) the model can call directly inside a turn.
-- **`HindsightToolset`** — A Haystack `Toolset` that bundles the same tools and adds optional **auto-recall** (inject relevant memories into the system prompt before each turn) and **auto-retain** (store user + assistant messages after each turn).
+- **`HindsightMemoryWrapper`** — A Haystack `Toolset` that bundles the same tools and adds optional **auto-recall** (inject relevant memories into the system prompt before each turn) and **auto-retain** (store user + assistant messages after each turn).
 
 ## Installation
 
@@ -48,14 +48,14 @@ result = agent.run(messages=[ChatMessage.from_user("Remember that I prefer dark
 print(result["messages"][-1].text)
 ```
 
-## Automatic Memory with HindsightToolset
+## Automatic Memory with HindsightMemoryWrapper
 
 For automatic recall and retain without relying on the agent to call tools:
 
 ```python
-from hindsight_haystack import HindsightToolset
+from hindsight_haystack import HindsightMemoryWrapper
 
-toolset = HindsightToolset(
+toolset = HindsightMemoryWrapper(
     client=client,
     bank_id="user-123",
     mission="Track user preferences",

hindsight-docs/src/data/integrations.json

@@ -223,7 +223,7 @@
     {
       "id": "haystack",
       "name": "Haystack",
-      "description": "Persistent memory for Haystack agents. Provides retain/recall/reflect Tools plus a HindsightToolset with optional auto-recall and auto-retain.",
+      "description": "Persistent memory for Haystack agents. Provides retain/recall/reflect Tools plus a HindsightMemoryWrapper with optional auto-recall and auto-retain.",
       "type": "official",
       "by": "hindsight",
       "category": "framework",

hindsight-integrations/haystack/README.md

@@ -41,14 +41,14 @@ result = agent.run(messages=[ChatMessage.from_user("Remember that I prefer dark
 print(result["messages"][-1].text)
 ```
 
-## Automatic Memory with HindsightToolset
+## Automatic Memory with HindsightMemoryWrapper
 
 For automatic recall and retain without relying on the agent to call tools:
 
 ```python
-from hindsight_haystack import HindsightToolset
+from hindsight_haystack import HindsightMemoryWrapper
 
-toolset = HindsightToolset(
+toolset = HindsightMemoryWrapper(
     client=client,
     bank_id="user-123",
     mission="Track user preferences",

hindsight-integrations/haystack/hindsight_haystack/__init__.py

@@ -21,7 +21,7 @@
     reset_config,
 )
 from .errors import HindsightError
-from .tools import HindsightToolset, create_hindsight_tools
+from .tools import HindsightMemoryWrapper, create_hindsight_tools
 
 __version__ = "0.1.0"
 
@@ -32,5 +32,5 @@
     "HindsightHaystackConfig",
     "HindsightError",
     "create_hindsight_tools",
-    "HindsightToolset",
+    "HindsightMemoryWrapper",
 ]

hindsight-integrations/haystack/hindsight_haystack/tools.py

@@ -2,7 +2,7 @@
 
 Provides a convenience factory that creates Haystack-compatible ``Tool``
 instances backed by Hindsight's retain/recall/reflect APIs, and a
-``HindsightToolset`` with optional auto-recall and auto-retain.
+``HindsightMemoryWrapper`` with optional auto-recall and auto-retain.
 """
 
 import asyncio
@@ -549,7 +549,7 @@ def create_hindsight_tools(
 
     Convenience factory that creates a backend and returns Haystack ``Tool``
     instances ready for use with any Haystack agent. For automatic recall
-    and retain behavior, use :class:`HindsightToolset` instead.
+    and retain behavior, use :class:`HindsightMemoryWrapper` instead.
 
     Args:
         bank_id: The Hindsight memory bank to operate on.
@@ -620,7 +620,7 @@ def create_hindsight_tools(
     )
 
 
-class HindsightToolset(Toolset):
+class HindsightMemoryWrapper(Toolset):
     """Haystack ``Toolset`` with optional auto-recall and auto-retain.
 
     Groups Hindsight memory tools into a single toolset and optionally adds
@@ -637,11 +637,11 @@ class HindsightToolset(Toolset):
 
     Example::
 
-        from hindsight_haystack import HindsightToolset
+        from hindsight_haystack import HindsightMemoryWrapper
         from haystack.components.agents import Agent
         from haystack.components.generators.chat import OpenAIChatGenerator
 
-        toolset = HindsightToolset(
+        toolset = HindsightMemoryWrapper(
             bank_id="user-123",
             client=client,
             mission="Track user preferences",
@@ -925,7 +925,7 @@ def to_dict(self) -> dict[str, Any]:
         }
 
     @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "HindsightToolset":
+    def from_dict(cls, data: dict[str, Any]) -> "HindsightMemoryWrapper":
         """Deserialize the toolset from a dictionary."""
         inner = data["data"]
         backend_kwargs = inner["backend_kwargs"]

hindsight-integrations/haystack/tests/test_tools.py

@@ -5,7 +5,7 @@
 import pytest
 from haystack.dataclasses import ChatMessage
 from hindsight_haystack import (
-    HindsightToolset,
+    HindsightMemoryWrapper,
     configure,
     create_hindsight_tools,
     reset_config,
@@ -788,19 +788,19 @@ def test_no_retry_on_409_conflict(self):
         assert client.acreate_bank.call_count == 1
 
 
-class TestHindsightToolset:
-    """Test the HindsightToolset class."""
+class TestHindsightMemoryWrapper:
+    """Test the HindsightMemoryWrapper class."""
 
     def test_creates_three_tools_by_default(self):
         client = _mock_client()
-        toolset = HindsightToolset(bank_id="test", client=client)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client)
         assert len(toolset) == 3
         names = {t.name for t in toolset}
         assert names == {"retain_memory", "recall_memory", "reflect_on_memory"}
 
     def test_include_flags(self):
         client = _mock_client()
-        toolset = HindsightToolset(
+        toolset = HindsightMemoryWrapper(
             bank_id="test",
             client=client,
             include_retain=True,
@@ -814,7 +814,7 @@ def test_serialization_round_trip(self):
         client = _mock_client()
         client._base_url = "http://test:8888"
         client._api_key = "test-key"
-        toolset = HindsightToolset(
+        toolset = HindsightMemoryWrapper(
             bank_id="test",
             client=client,
             auto_recall=True,
@@ -829,19 +829,19 @@ def test_serialization_round_trip(self):
 
         with patch("hindsight_haystack._client.Hindsight") as mock_cls:
             mock_cls.return_value = _mock_client()
-            restored = HindsightToolset.from_dict(d)
+            restored = HindsightMemoryWrapper.from_dict(d)
             assert len(restored) == 3
             assert restored._auto_recall is True
             assert restored._auto_retain is True
 
 
 class TestToolsetAutoRecall:
-    """Test auto-recall behavior in HindsightToolset.run()."""
+    """Test auto-recall behavior in HindsightMemoryWrapper.run()."""
 
     def test_auto_recall_enriches_system_prompt(self):
         client = _mock_client()
         client.arecall.return_value = _mock_recall_response(["User likes Python", "User is in NYC"])
-        toolset = HindsightToolset(bank_id="test", client=client, auto_recall=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_recall=True)
 
         # Create a mock agent
         agent = MagicMock()
@@ -862,7 +862,7 @@ def test_auto_recall_enriches_system_prompt(self):
     def test_auto_recall_uses_agent_system_prompt_when_none_provided(self):
         client = _mock_client()
         client.arecall.return_value = _mock_recall_response(["some memory"])
-        toolset = HindsightToolset(bank_id="test", client=client, auto_recall=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_recall=True)
 
         agent = MagicMock()
         agent.system_prompt = "Agent default prompt."
@@ -878,7 +878,7 @@ def test_auto_recall_uses_agent_system_prompt_when_none_provided(self):
     def test_auto_recall_overrides_with_explicit_system_prompt(self):
         client = _mock_client()
         client.arecall.return_value = _mock_recall_response(["memory"])
-        toolset = HindsightToolset(bank_id="test", client=client, auto_recall=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_recall=True)
 
         agent = MagicMock()
         agent.system_prompt = "Agent default."
@@ -899,7 +899,7 @@ def test_auto_recall_overrides_with_explicit_system_prompt(self):
 
     def test_auto_recall_skips_when_no_user_message(self):
         client = _mock_client()
-        toolset = HindsightToolset(bank_id="test", client=client, auto_recall=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_recall=True)
 
         agent = MagicMock()
         agent.system_prompt = "base prompt"
@@ -914,7 +914,7 @@ def test_auto_recall_skips_when_no_user_message(self):
 
     def test_auto_recall_disabled_by_default(self):
         client = _mock_client()
-        toolset = HindsightToolset(bank_id="test", client=client)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client)
 
         agent = MagicMock()
         agent.system_prompt = "base"
@@ -930,7 +930,7 @@ def test_auto_recall_respects_max_recall_results(self):
         client = _mock_client()
         # Return many results
         client.arecall.return_value = _mock_recall_response([f"Memory {i}" for i in range(20)])
-        toolset = HindsightToolset(
+        toolset = HindsightMemoryWrapper(
             bank_id="test",
             client=client,
             auto_recall=True,
@@ -954,7 +954,7 @@ def test_auto_recall_respects_max_recall_results(self):
     def test_auto_recall_no_memories_passes_base_prompt(self):
         client = _mock_client()
         client.arecall.return_value = _mock_recall_response([])
-        toolset = HindsightToolset(bank_id="test", client=client, auto_recall=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_recall=True)
 
         agent = MagicMock()
         agent.system_prompt = "base prompt"
@@ -969,12 +969,12 @@ def test_auto_recall_no_memories_passes_base_prompt(self):
 
 
 class TestToolsetAutoRetain:
-    """Test auto-retain behavior in HindsightToolset.run()."""
+    """Test auto-retain behavior in HindsightMemoryWrapper.run()."""
 
     def test_auto_retain_stores_user_and_assistant_messages(self):
         client = _mock_client()
         client.aretain.return_value = _mock_retain_response()
-        toolset = HindsightToolset(bank_id="test", client=client, auto_retain=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_retain=True)
 
         agent = MagicMock()
         agent.system_prompt = None
@@ -995,7 +995,7 @@ def test_auto_retain_stores_user_and_assistant_messages(self):
     def test_auto_retain_includes_role_metadata(self):
         client = _mock_client()
         client.aretain.return_value = _mock_retain_response()
-        toolset = HindsightToolset(bank_id="test", client=client, auto_retain=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_retain=True)
 
         agent = MagicMock()
         agent.system_prompt = None
@@ -1017,7 +1017,7 @@ def test_auto_retain_includes_role_metadata(self):
     def test_auto_retain_skips_system_messages(self):
         client = _mock_client()
         client.aretain.return_value = _mock_retain_response()
-        toolset = HindsightToolset(bank_id="test", client=client, auto_retain=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_retain=True)
 
         agent = MagicMock()
         agent.system_prompt = None
@@ -1040,7 +1040,7 @@ def test_auto_retain_skips_system_messages(self):
 
     def test_auto_retain_disabled_by_default(self):
         client = _mock_client()
-        toolset = HindsightToolset(bank_id="test", client=client)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client)
 
         agent = MagicMock()
         agent.system_prompt = None
@@ -1055,7 +1055,7 @@ def test_auto_retain_disabled_by_default(self):
     def test_auto_retain_handles_error_gracefully(self):
         client = _mock_client()
         client.aretain.side_effect = RuntimeError("connection refused")
-        toolset = HindsightToolset(bank_id="test", client=client, auto_retain=True)
+        toolset = HindsightMemoryWrapper(bank_id="test", client=client, auto_retain=True)
 
         agent = MagicMock()
         agent.system_prompt = None
@@ -1077,7 +1077,7 @@ def test_both_auto_recall_and_retain(self):
         client = _mock_client()
         client.arecall.return_value = _mock_recall_response(["remembered fact"])
         client.aretain.return_value = _mock_retain_response()
-        toolset = HindsightToolset(
+        toolset = HindsightMemoryWrapper(
             bank_id="test",
             client=client,
             auto_recall=True,