docs: add AG2 integration page (#723)

- Add AG2 integration doc with quick start, configuration, GroupChat example, and API reference
- Add to sidebar, versioned sidebar, and integrations hub
- Add AG2 icon

hindsight-docs/docs/sdks/integrations/ag2.md

@@ -0,0 +1,182 @@
+---
+sidebar_position: 8
+---
+
+# AG2
+
+Persistent long-term memory for [AG2](https://ag2.ai) agents (community AutoGen fork). Give your agents retain/recall/reflect tools that persist across conversations.
+
+[View Changelog →](/changelog/integrations/ag2)
+
+## Features
+
+- **Drop-in Tools** — `register_hindsight_tools()` registers retain, recall, and reflect in one line
+- **AG2-native** — Uses `Annotated` type hints compatible with AG2's `@register_for_llm` / `@register_for_execution` pattern
+- **GroupChat Support** — Multiple agents can share a single memory bank
+- **Selective Tools** — Include only the tools you need (`include_retain`, `include_recall`, `include_reflect`)
+- **Simple Configuration** — Configure once globally or override per tool set
+
+## Installation
+
+```bash
+pip install hindsight-ag2
+```
+
+## Quick Start
+
+```python
+from autogen import AssistantAgent, UserProxyAgent, LLMConfig
+from hindsight_ag2 import register_hindsight_tools
+
+llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")
+
+with llm_config:
+    assistant = AssistantAgent(
+        name="assistant",
+        system_message="You are a helpful assistant with long-term memory.",
+    )
+    user_proxy = UserProxyAgent(
+        name="user",
+        human_input_mode="NEVER",
+    )
+
+# Register Hindsight memory tools on both agents
+register_hindsight_tools(
+    assistant, user_proxy,
+    bank_id="my-bank",
+    hindsight_api_url="http://localhost:8888",
+)
+
+# The assistant can now use hindsight_retain, hindsight_recall, hindsight_reflect
+result = user_proxy.initiate_chat(
+    assistant,
+    message="Remember that I prefer Python over JavaScript.",
+)
+```
+
+That's it. The assistant can now store and retrieve memories across conversations.
+
+## How It Works
+
+The integration provides three AG2-compatible tool functions backed by Hindsight's API:
+
+| Tool | Hindsight | What happens |
+|------|-----------|--------------|
+| `hindsight_retain(content)` | `retain(bank_id, content, ...)` | Content is stored. Hindsight extracts facts, entities, and relationships from the raw text. |
+| `hindsight_recall(query)` | `recall(bank_id, query, ...)` | Hindsight runs semantic search, BM25, graph traversal, and reranking. Returns a numbered list of matching memories. |
+| `hindsight_reflect(query)` | `reflect(bank_id, query, ...)` | Hindsight synthesizes a reasoned answer from all relevant memories, using the bank's disposition traits. |
+
+Tools are plain Python functions with `Annotated` type hints. AG2 uses these hints to generate the tool schema that the LLM sees.
+
+## Configuration
+
+### Global Configuration
+
+```python
+from hindsight_ag2 import configure
+
+configure(
+    hindsight_api_url="http://localhost:8888",
+    api_key="your-key",       # or set HINDSIGHT_API_KEY env var
+    budget="mid",              # low / mid / high
+    max_tokens=4096,
+    tags=["source:ag2"],       # default tags for retain
+)
+```
+
+### Per-Tool Overrides
+
+Constructor arguments override global configuration:
+
+```python
+from hindsight_ag2 import create_hindsight_tools
+
+tools = create_hindsight_tools(
+    bank_id="my-bank",
+    hindsight_api_url="http://localhost:8888",
+    budget="high",
+    max_tokens=8192,
+    tags=["team:alpha"],
+)
+```
+
+## GroupChat with Shared Memory
+
+Multiple agents can share a single memory bank in a GroupChat:
+
+```python
+from autogen import AssistantAgent, UserProxyAgent, GroupChat, GroupChatManager, LLMConfig
+from hindsight_ag2 import register_hindsight_tools
+
+llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")
+
+with llm_config:
+    researcher = AssistantAgent(name="researcher", system_message="You research topics.")
+    writer = AssistantAgent(name="writer", system_message="You write content.")
+    executor = UserProxyAgent(name="executor", human_input_mode="NEVER")
+
+# All agents share the same memory bank
+for agent in [researcher, writer]:
+    register_hindsight_tools(agent, executor, bank_id="team-memory")
+
+group_chat = GroupChat(agents=[researcher, writer, executor], messages=[])
+manager = GroupChatManager(groupchat=group_chat)
+```
+
+## Manual Registration
+
+For full control over how tools are registered:
+
+```python
+from hindsight_ag2 import create_hindsight_tools
+
+tools = create_hindsight_tools(
+    bank_id="my-bank",
+    hindsight_api_url="http://localhost:8888",
+)
+for tool_fn in tools:
+    assistant.register_for_llm(description=tool_fn.__doc__)(tool_fn)
+    user_proxy.register_for_execution()(tool_fn)
+```
+
+## API Reference
+
+### Configuration
+
+| Function | Description |
+|----------|-------------|
+| `configure(...)` | Set global connection and default settings |
+| `get_config()` | Get current configuration |
+| `reset_config()` | Reset configuration to None |
+
+### create_hindsight_tools
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `bank_id` | required | Hindsight memory bank ID |
+| `client` | `None` | Pre-configured `Hindsight` client |
+| `hindsight_api_url` | from config | Hindsight API URL |
+| `api_key` | from config | API key |
+| `budget` | `"mid"` | Recall/reflect budget (low/mid/high) |
+| `max_tokens` | `4096` | Max tokens for recall results |
+| `tags` | `None` | Tags applied when storing memories |
+| `recall_tags` | `None` | Tags to filter when searching |
+| `recall_tags_match` | `"any"` | Tag matching mode (any/all/any_strict/all_strict) |
+| `retain_metadata` | `None` | Metadata dict for retain operations |
+| `retain_document_id` | `None` | Document ID for retain (groups/upserts memories) |
+| `recall_types` | `None` | Fact types to filter (world, experience, opinion, observation) |
+| `recall_include_entities` | `False` | Include entity information in recall results |
+| `reflect_context` | `None` | Additional context for reflect operations |
+| `reflect_max_tokens` | `max_tokens` | Max tokens for reflect results |
+| `reflect_response_schema` | `None` | JSON schema to constrain reflect output format |
+| `reflect_tags` | `recall_tags` | Tags to filter memories used in reflect |
+| `reflect_tags_match` | `recall_tags_match` | Tag matching for reflect |
+| `include_retain` | `True` | Include the retain tool |
+| `include_recall` | `True` | Include the recall tool |
+| `include_reflect` | `True` | Include the reflect tool |
+
+## Requirements
+
+- Python >= 3.10
+- ag2 >= 0.9.0
+- A running Hindsight API server

hindsight-docs/sidebars.ts

@@ -250,6 +250,12 @@ const sidebars: SidebarsConfig = {
           label: 'Strands Agents',
           customProps: { icon: '/img/icons/strands.png' },
         },
+        {
+          type: 'doc',
+          id: 'sdks/integrations/ag2',
+          label: 'AG2',
+          customProps: { icon: '/img/icons/ag2.svg' },
+        },
         {
           type: 'doc',
           id: 'sdks/integrations/skills',

hindsight-docs/src/data/integrations.json

@@ -140,6 +140,16 @@
       "link": "/sdks/integrations/strands",
       "icon": "/img/icons/strands.png"
     },
+    {
+      "id": "ag2",
+      "name": "AG2",
+      "description": "Persistent long-term memory for AG2 agents with retain, recall, and reflect tools across conversations.",
+      "type": "official",
+      "by": "hindsight",
+      "category": "framework",
+      "link": "/sdks/integrations/ag2",
+      "icon": "/img/icons/ag2.svg"
+    },
     {
       "id": "hindclaw",
       "name": "HindClaw",

hindsight-docs/static/img/icons/ag2.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none"><g fill="#000" clip-path="url(#a)"><path d="M32 0h-2.142v2.142H32V0Zm-2.142 10.667H27.73v4.269h2.128v-4.27Zm0-8.525H27.73v2.127h2.128V2.142ZM27.73 8.539h-2.127v2.128h2.127V8.539Zm0-4.269h-2.127v2.14h2.127V4.27Zm-2.127 2.141h-4.27V8.54h4.27V6.41Zm-4.27-2.141H10.667v2.14h10.666V4.27Zm4.27 12.794v-4.256H23.46v-2.141H8.54v2.141H6.397v4.256h19.206Zm-6.397-4.256h2.127v2.128h-2.127v-2.128Zm-8.54 0h2.128v2.128h-2.127v-2.128Zm.001-6.397h-4.27V8.54h4.27V6.41Zm-4.27 2.128H4.27v2.128h2.127V8.539Zm0-4.269H4.27v2.14h2.127V4.27ZM4.27 10.667H2.142v4.269H4.27v-4.27Zm0-8.525H2.142v2.127H4.27V2.142ZM2.142 0H0v2.142h2.142V0Zm27.593 25.017v-2.265h-6.794v-2.265h6.794v2.265H32v2.265h-2.265Zm-4.53 2.265v-2.265h4.53v2.265h-4.53Zm-2.264 4.53v-4.53h2.265v2.264H32v2.265h-9.06Zm-9.206-9.06v-2.265h6.795v2.265h-6.795Zm-2.264 6.794v-6.794h2.264v6.794h-2.264Zm6.794 0v-2.264H16v-2.265h4.53v4.53h-2.265Zm-4.53 2.265v-2.265h4.53v2.265h-4.53ZM0 31.811v-9.059h2.265v-2.265h4.53v2.265h2.264v9.06H6.794v-4.53h-4.53v4.53H0Zm2.265-6.794h4.53v-2.174h-4.53v2.174Z"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h32v32H0z"/></clipPath></defs></svg>

hindsight-docs/versioned_docs/version-0.4/sdks/integrations/ag2.md

@@ -0,0 +1,182 @@
+---
+sidebar_position: 8
+---
+
+# AG2
+
+Persistent long-term memory for [AG2](https://ag2.ai) agents (community AutoGen fork). Give your agents retain/recall/reflect tools that persist across conversations.
+
+[View Changelog →](/changelog/integrations/ag2)
+
+## Features
+
+- **Drop-in Tools** — `register_hindsight_tools()` registers retain, recall, and reflect in one line
+- **AG2-native** — Uses `Annotated` type hints compatible with AG2's `@register_for_llm` / `@register_for_execution` pattern
+- **GroupChat Support** — Multiple agents can share a single memory bank
+- **Selective Tools** — Include only the tools you need (`include_retain`, `include_recall`, `include_reflect`)
+- **Simple Configuration** — Configure once globally or override per tool set
+
+## Installation
+
+```bash
+pip install hindsight-ag2
+```
+
+## Quick Start
+
+```python
+from autogen import AssistantAgent, UserProxyAgent, LLMConfig
+from hindsight_ag2 import register_hindsight_tools
+
+llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")
+
+with llm_config:
+    assistant = AssistantAgent(
+        name="assistant",
+        system_message="You are a helpful assistant with long-term memory.",
+    )
+    user_proxy = UserProxyAgent(
+        name="user",
+        human_input_mode="NEVER",
+    )
+
+# Register Hindsight memory tools on both agents
+register_hindsight_tools(
+    assistant, user_proxy,
+    bank_id="my-bank",
+    hindsight_api_url="http://localhost:8888",
+)
+
+# The assistant can now use hindsight_retain, hindsight_recall, hindsight_reflect
+result = user_proxy.initiate_chat(
+    assistant,
+    message="Remember that I prefer Python over JavaScript.",
+)
+```
+
+That's it. The assistant can now store and retrieve memories across conversations.
+
+## How It Works
+
+The integration provides three AG2-compatible tool functions backed by Hindsight's API:
+
+| Tool | Hindsight | What happens |
+|------|-----------|--------------|
+| `hindsight_retain(content)` | `retain(bank_id, content, ...)` | Content is stored. Hindsight extracts facts, entities, and relationships from the raw text. |
+| `hindsight_recall(query)` | `recall(bank_id, query, ...)` | Hindsight runs semantic search, BM25, graph traversal, and reranking. Returns a numbered list of matching memories. |
+| `hindsight_reflect(query)` | `reflect(bank_id, query, ...)` | Hindsight synthesizes a reasoned answer from all relevant memories, using the bank's disposition traits. |
+
+Tools are plain Python functions with `Annotated` type hints. AG2 uses these hints to generate the tool schema that the LLM sees.
+
+## Configuration
+
+### Global Configuration
+
+```python
+from hindsight_ag2 import configure
+
+configure(
+    hindsight_api_url="http://localhost:8888",
+    api_key="your-key",       # or set HINDSIGHT_API_KEY env var
+    budget="mid",              # low / mid / high
+    max_tokens=4096,
+    tags=["source:ag2"],       # default tags for retain
+)
+```
+
+### Per-Tool Overrides
+
+Constructor arguments override global configuration:
+
+```python
+from hindsight_ag2 import create_hindsight_tools
+
+tools = create_hindsight_tools(
+    bank_id="my-bank",
+    hindsight_api_url="http://localhost:8888",
+    budget="high",
+    max_tokens=8192,
+    tags=["team:alpha"],
+)
+```
+
+## GroupChat with Shared Memory
+
+Multiple agents can share a single memory bank in a GroupChat:
+
+```python
+from autogen import AssistantAgent, UserProxyAgent, GroupChat, GroupChatManager, LLMConfig
+from hindsight_ag2 import register_hindsight_tools
+
+llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")
+
+with llm_config:
+    researcher = AssistantAgent(name="researcher", system_message="You research topics.")
+    writer = AssistantAgent(name="writer", system_message="You write content.")
+    executor = UserProxyAgent(name="executor", human_input_mode="NEVER")
+
+# All agents share the same memory bank
+for agent in [researcher, writer]:
+    register_hindsight_tools(agent, executor, bank_id="team-memory")
+
+group_chat = GroupChat(agents=[researcher, writer, executor], messages=[])
+manager = GroupChatManager(groupchat=group_chat)
+```
+
+## Manual Registration
+
+For full control over how tools are registered:
+
+```python
+from hindsight_ag2 import create_hindsight_tools
+
+tools = create_hindsight_tools(
+    bank_id="my-bank",
+    hindsight_api_url="http://localhost:8888",
+)
+for tool_fn in tools:
+    assistant.register_for_llm(description=tool_fn.__doc__)(tool_fn)
+    user_proxy.register_for_execution()(tool_fn)
+```
+
+## API Reference
+
+### Configuration
+
+| Function | Description |
+|----------|-------------|
+| `configure(...)` | Set global connection and default settings |
+| `get_config()` | Get current configuration |
+| `reset_config()` | Reset configuration to None |
+
+### create_hindsight_tools
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `bank_id` | required | Hindsight memory bank ID |
+| `client` | `None` | Pre-configured `Hindsight` client |
+| `hindsight_api_url` | from config | Hindsight API URL |
+| `api_key` | from config | API key |
+| `budget` | `"mid"` | Recall/reflect budget (low/mid/high) |
+| `max_tokens` | `4096` | Max tokens for recall results |
+| `tags` | `None` | Tags applied when storing memories |
+| `recall_tags` | `None` | Tags to filter when searching |
+| `recall_tags_match` | `"any"` | Tag matching mode (any/all/any_strict/all_strict) |
+| `retain_metadata` | `None` | Metadata dict for retain operations |
+| `retain_document_id` | `None` | Document ID for retain (groups/upserts memories) |
+| `recall_types` | `None` | Fact types to filter (world, experience, opinion, observation) |
+| `recall_include_entities` | `False` | Include entity information in recall results |
+| `reflect_context` | `None` | Additional context for reflect operations |
+| `reflect_max_tokens` | `max_tokens` | Max tokens for reflect results |
+| `reflect_response_schema` | `None` | JSON schema to constrain reflect output format |
+| `reflect_tags` | `recall_tags` | Tags to filter memories used in reflect |
+| `reflect_tags_match` | `recall_tags_match` | Tag matching for reflect |
+| `include_retain` | `True` | Include the retain tool |
+| `include_recall` | `True` | Include the recall tool |
+| `include_reflect` | `True` | Include the reflect tool |
+
+## Requirements
+
+- Python >= 3.10
+- ag2 >= 0.9.0
+- A running Hindsight API server

hindsight-docs/versioned_sidebars/version-0.4-sidebars.json

@@ -323,6 +323,14 @@
             "icon": "/img/icons/strands.png"
           }
         },
+        {
+          "type": "doc",
+          "id": "sdks/integrations/ag2",
+          "label": "AG2",
+          "customProps": {
+            "icon": "/img/icons/ag2.svg"
+          }
+        },
         {
           "type": "doc",
           "id": "sdks/integrations/skills",