Skip to main content

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.

The hindsight-openai-agents package provides FunctionTool instances that plug directly into the OpenAI Agents SDK Agent. Agents can store and retrieve long-term memories using the same tools=[...] interface they already use for any other tool — no special wiring required.

​
Installation

pip install hindsight-openai-agents openai-agents
hindsight-openai-agents pulls in openai-agents and hindsight-client automatically.

​
Quick start

import asyncio
from agents import Agent, Runner
from hindsight_client import Hindsight
from hindsight_openai_agents import create_hindsight_tools

async def main():
    client = Hindsight(base_url="http://localhost:8888")
    await client.acreate_bank(bank_id="user-123")

    tools = create_hindsight_tools(client=client, bank_id="user-123")

    agent = Agent(
        name="assistant",
        instructions=(
            "You are a helpful assistant with long-term memory. "
            "Use hindsight_retain to store important facts. "
            "Use hindsight_recall to search memory before answering."
        ),
        tools=tools,
    )

    # Store a memory
    result = await Runner.run(agent, "Remember that I prefer dark mode")
    print(result.final_output)

    # Hindsight processes retained content asynchronously (fact extraction,
    # entity resolution, embeddings). A brief pause ensures memories are
    # searchable before the next recall. In production, this delay is only
    # needed when retain and recall happen back-to-back in the same script.
    await asyncio.sleep(3)

    # Recall it later
    result = await Runner.run(agent, "What are my UI preferences?")
    print(result.final_output)

    await client.aclose()

asyncio.run(main())
In a Jupyter notebook, you don’t need asyncio.run() — use await directly since the notebook already has an active event loop.
The agent gets three tools:
  • hindsight_retain — Store information to long-term memory
  • hindsight_recall — Search long-term memory for relevant facts
  • hindsight_reflect — Synthesize a reasoned answer from memories

​
Auto-inject memories with memory_instructions()

Instead of relying on the agent to call hindsight_recall explicitly, auto-inject relevant memories into the system prompt on every turn: 
from hindsight_openai_agents import create_hindsight_tools, memory_instructions

agent = Agent(
    name="assistant",
    instructions=memory_instructions(
        client=client,
        bank_id="user-123",
        base_instructions="You are a helpful assistant with long-term memory.",
    ),
    tools=create_hindsight_tools(
        client=client,
        bank_id="user-123",
        include_recall=False,  # recall is handled by memory_instructions
    ),
)
memory_instructions() returns an async callable compatible with Agent(instructions=...). On each turn it recalls relevant memories and appends them to your base instructions. If recall fails or returns nothing, it falls back to base_instructions alone.

​
Selecting tools

Include only the tools you need: 
tools = create_hindsight_tools(
    client=client,
    bank_id="user-123",
    include_retain=True,
    include_recall=True,
    include_reflect=False,
)

​
Global configuration

Configure once and create tools anywhere without passing a client every time: 
from hindsight_openai_agents 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",                  # low / mid / high
    max_tokens=4096,
    tags=["env:prod"],
    recall_tags=["scope:global"],
    recall_tags_match="any",
)

tools = create_hindsight_tools(bank_id="user-123")

​
Memory scoping with tags

Partition memories by topic, session, or user to prevent cross-contamination: 
tools = create_hindsight_tools(
    client=client,
    bank_id="user-123",
    tags=["source:chat", "session:abc"],
    recall_tags=["source:chat"],
    recall_tags_match="any",
)

​
Multi-agent workflows

Give each agent its own memory bank, or share a bank across agents: 
# 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 memory
shared_tools = create_hindsight_tools(
    client=client,
    bank_id="team-shared",
    tags=["team:content"],
)

​
Bank lifecycle

Create banks before first use. Bank creation is idempotent — calling acreate_bank on an existing bank is safe. 
async def main():
    client = Hindsight(base_url="http://localhost:8888")
    await client.acreate_bank(bank_id="user-123")

    tools = create_hindsight_tools(client=client, bank_id="user-123")
    # ... use tools ...

    # Optional: delete bank when no longer needed
    await client.adelete_bank(bank_id="user-123")

​
Requirements

  • Python >= 3.10
  • openai-agents >= 0.7.0
  • hindsight-client >= 0.4.0

Build docs developers (and LLMs) love

Get started for freeTalk to us