Documentation Index
Fetch the complete documentation index at: https://mintlify.com/vectorize-io/hindsight/llms.txt
Use this file to discover all available pages before exploring further.
Hindsight integrates with the two most widely used multi-agent frameworks: CrewAI and AutoGen (including the AG2 community fork). Both integrations expose retain, recall, and reflect as framework-native constructs — a storage backend for CrewAI and tool functions for AutoGen and AG2.
CrewAI
The hindsight-crewai package implements CrewAI’s Storage interface for ExternalMemory. CrewAI automatically calls search() at the start of each task and save() after each task completes — your crew learns across runs with no extra code.Installation
pip install hindsight-crewai
Quick start
from hindsight_crewai import configure, HindsightStorage
from crewai.memory.external.external_memory import ExternalMemory
from crewai import Agent, Crew, Task
configure(
hindsight_api_url="https://api.hindsight.vectorize.io",
api_key="hsk_...", # or set HINDSIGHT_API_KEY env var
)
crew = Crew(
agents=[Agent(role="Researcher", goal="Find information", backstory="...")],
tasks=[Task(description="Research AI trends", expected_output="Report")],
external_memory=ExternalMemory(
storage=HindsightStorage(bank_id="my-crew")
),
)
crew.kickoff()
kickoff() calls, so the crew builds on prior findings over time.How it works
| CrewAI | Hindsight | What happens |
|---|
save(value, metadata, agent) | retain(bank_id, content, ...) | Task output is stored — Hindsight extracts facts, entities, and relationships |
search(query, limit) | recall(bank_id, query, ...) | Semantic search, BM25, graph traversal, and reranking |
reset() | delete_bank(bank_id) | Wipes the bank and recreates it with its original mission |
Configuration
from hindsight_crewai import configure
configure(
hindsight_api_url="https://api.hindsight.vectorize.io",
api_key="your-api-key",
budget="mid", # low / mid / high
max_tokens=4096,
tags=["env:prod"],
recall_tags=["scope:global"],
recall_tags_match="any", # any / all / any_strict / all_strict
verbose=True,
)
storage = HindsightStorage(
bank_id="my-crew",
budget="high",
max_tokens=8192,
tags=["team:alpha"],
)
Bank mission
Set a mission to guide how Hindsight processes and organizes memories:storage = HindsightStorage(
bank_id="my-crew",
mission="Track software architecture decisions, technical debt, and team preferences.",
)
Per-agent memory banks
Give each agent its own isolated memory bank:storage = HindsightStorage(
bank_id="my-crew",
per_agent_banks=True,
# Researcher -> "my-crew-researcher"
# Writer -> "my-crew-writer"
)
storage = HindsightStorage(
bank_id="my-crew",
bank_resolver=lambda base, agent: f"{base}-{agent.lower()}" if agent else base,
)
When per_agent_banks=True, the automatic search() at task start queries the base bank (shared context), since CrewAI’s search() method does not receive the agent parameter. For per-agent search isolation, create separate HindsightStorage instances per agent.
HindsightReflectTool as an agent tool:from hindsight_crewai import HindsightReflectTool
reflect_tool = HindsightReflectTool(
bank_id="my-crew",
budget="mid",
reflect_context="You are helping a software team track decisions.",
)
agent = Agent(
role="Analyst",
goal="Analyze project history",
backstory="...",
tools=[reflect_tool],
)
Full example
A research crew that remembers findings across runs:from hindsight_crewai import configure, HindsightStorage, HindsightReflectTool
from crewai.memory.external.external_memory import ExternalMemory
from crewai import Agent, Crew, Task
configure(
hindsight_api_url="https://api.hindsight.vectorize.io",
api_key="hsk_...",
)
storage = HindsightStorage(
bank_id="research-crew",
mission="Track technology research findings and comparisons.",
)
reflect_tool = HindsightReflectTool(bank_id="research-crew", budget="mid")
researcher = Agent(
role="Researcher",
goal="Research topics, building on prior knowledge.",
backstory="Before starting, use hindsight_reflect to check what you already know.",
tools=[reflect_tool],
)
writer = Agent(
role="Writer",
goal="Write summaries incorporating prior findings.",
backstory="Use hindsight_reflect to recall prior research.",
tools=[reflect_tool],
)
crew = Crew(
agents=[researcher, writer],
tasks=[
Task(description="Research the benefits of Rust", expected_output="Analysis", agent=researcher),
Task(description="Write an executive summary", expected_output="Summary", agent=writer),
],
external_memory=ExternalMemory(storage=storage),
)
# Run 1: researches Rust, stores findings
crew.kickoff()
# Run 2: recalls Rust research when comparing with Go
crew.tasks[0].description = "Compare Rust with Go"
crew.kickoff()
Requirements
- Python >= 3.10
crewai >= 0.86.0- A running Hindsight API server
AutoGen
The hindsight-autogen package provides FunctionTool instances that plug directly into AutoGen’s AssistantAgent. The integration is async-native and works seamlessly in AutoGen’s runtime.Installation
pip install hindsight-autogen autogen-agentchat "autogen-ext[openai]"
hindsight-autogen pulls in autogen-core and hindsight-client. You also need autogen-agentchat for AssistantAgent and autogen-ext[openai] for the OpenAI model client.Quick start
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from hindsight_client import Hindsight
from hindsight_autogen import create_hindsight_tools
async def main():
client = Hindsight(base_url="http://localhost:8888")
await client.acreate_bank(bank_id="user-123")
model_client = OpenAIChatCompletionClient(model="gpt-4o")
tools = create_hindsight_tools(client=client, bank_id="user-123")
agent = AssistantAgent(
name="assistant",
model_client=model_client,
tools=tools,
)
# Store a memory
result = await agent.run(task="Remember that I prefer dark mode")
print(result.messages[-1].content)
# Brief pause for async fact extraction before recall
await asyncio.sleep(3)
# Recall it later
result = await agent.run(task="What are my UI preferences?")
print(result.messages[-1].content)
await client.aclose()
await model_client.close()
asyncio.run(main())
In a Jupyter notebook, use await directly — no need for asyncio.run() since the notebook already has an active event loop.
hindsight_retain, hindsight_recall, and hindsight_reflect.tools = create_hindsight_tools(
client=client,
bank_id="user-123",
include_retain=True,
include_recall=True,
include_reflect=False,
)
Global configuration
from hindsight_autogen import configure, create_hindsight_tools
configure(
hindsight_api_url="http://localhost:8888",
api_key="your-api-key", # or set HINDSIGHT_API_KEY env var
budget="mid",
max_tokens=4096,
tags=["env:prod"],
recall_tags=["scope:global"],
recall_tags_match="any",
)
tools = create_hindsight_tools(bank_id="user-123")
Multi-agent teams
Give each agent its own memory bank, or share a bank across a team:# Per-agent memory
researcher_tools = create_hindsight_tools(client=client, bank_id="researcher-memory")
writer_tools = create_hindsight_tools(client=client, bank_id="writer-memory")
# Shared team memory
shared_tools = create_hindsight_tools(
client=client,
bank_id="team-shared",
tags=["team:content"],
)
Requirements
- Python >= 3.10
autogen-core >= 0.4.0hindsight-client >= 0.4.0
AG2
AG2 is the community AutoGen fork (ag2.ai). The hindsight-ag2 package uses AG2’s native @register_for_llm / @register_for_execution pattern with Annotated type hints to register retain, recall, and reflect in one line.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",
)
result = user_proxy.initiate_chat(
assistant,
message="Remember that I prefer Python over JavaScript.",
)
GroupChat with shared memory
Multiple agents can share a single memory bank in a GroupChat: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)
Global configuration
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",
max_tokens=4096,
tags=["source:ag2"],
)
Manual registration
For full control over how tools are registered: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)
Requirements
- Python >= 3.10
ag2 >= 0.9.0- A running Hindsight API server
