731238707d
Add hindsight-ag2 package providing persistent memory tools for AG2 agents via retain/recall/reflect operations.
143 lines
4.5 KiB
Markdown
143 lines
4.5 KiB
Markdown
# hindsight-ag2
|
|
|
|
AG2 integration for [Hindsight](https://github.com/vectorize-io/hindsight) — persistent long-term memory for AI agents.
|
|
|
|
Provides Hindsight-backed tool functions that give [AG2](https://ag2.ai) agents long-term memory across conversations via retain/recall/reflect operations.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.10+
|
|
- Running Hindsight instance ([quickstart](https://github.com/vectorize-io/hindsight#quick-start))
|
|
|
|
## 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.",
|
|
)
|
|
```
|
|
|
|
## 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
|
|
|
|
```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-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
|
|
|
|
```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)
|
|
```
|
|
|
|
## Advanced: GroupChat with Shared Memory
|
|
|
|
```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)
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- `ag2>=0.9.0`
|
|
- `hindsight-client>=0.4.0`
|
|
|
|
## Documentation
|
|
|
|
- [Hindsight Documentation](https://hindsight.docs.vectorize.io)
|
|
- [AG2 Documentation](https://docs.ag2.ai)
|
|
- [API Reference](https://hindsight.docs.vectorize.io/api)
|