fleet-memory/hindsight-integrations/ag2/README.md

hindsight-ag2

AG2 integration for Hindsight — persistent long-term memory for AI agents.

Provides Hindsight-backed tool functions that give AG2 agents long-term memory across conversations via retain/recall/reflect operations.

Prerequisites

• Python 3.10+
• Running Hindsight instance (quickstart)

Installation

pip install hindsight-ag2

Quick Start

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.",
)

Tools

Tool	Operation	Description
hindsight_retain	Retain	Store facts, preferences, decisions to long-term memory
hindsight_recall	Recall	Multi-strategy search across stored memories
hindsight_reflect	Reflect	Synthesize reasoned answers from memories

Configuration

Global config

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-call overrides

All global settings can be overridden per create_hindsight_tools() call:

Parameter	Description	Default
bank_id	Memory bank ID (required)	—
client	Pre-configured Hindsight client	—
hindsight_api_url	API URL	Global config or production
api_key	API key	Global config or env var
budget	Recall/reflect budget	"mid"
max_tokens	Max tokens for recall	4096
tags	Tags for retain operations	None
recall_tags	Tags to filter recall	None
recall_tags_match	Tag match mode	"any"
retain_metadata	Metadata dict for retain	None
retain_document_id	Document ID for retain	None
recall_types	Fact types to filter	None
recall_include_entities	Include entities in recall	False
reflect_context	Additional context for reflect	None
reflect_max_tokens	Max tokens for reflect	max_tokens
reflect_response_schema	JSON schema for reflect output	None
reflect_tags	Tags for reflect (fallback: recall_tags)	None
reflect_tags_match	Tag match for reflect	recall_tags_match

Advanced: Manual Registration

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)

Advanced: GroupChat with Shared Memory

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)

Requirements

• ag2>=0.9.0
• hindsight-client>=0.4.0

Documentation

• Hindsight Documentation
• AG2 Documentation
• API Reference