hindsight-openai-agents 0.1.0

OpenAI Agents SDK integration for Hindsight - persistent memory tools for AI agents

hindsight-openai-agents

OpenAI Agents SDK integration for Hindsight — persistent long-term memory for AI agents.

Provides FunctionTool instances that give OpenAI Agents SDK agents the ability to store, search, and synthesize memories across conversations.

Prerequisites

• A running Hindsight instance (self-hosted via Docker or Hindsight Cloud)
• Python 3.10+

Installation

pip install hindsight-openai-agents openai-agents

hindsight-openai-agents pulls in openai-agents and hindsight-client.

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)

    # Clean up
    await client.aclose()

asyncio.run(main())

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

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,  # Omit reflect
)

Global Configuration

Instead of passing a client to every call, configure once:

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",                  # Recall budget: low/mid/high
    max_tokens=4096,               # Max tokens for recall results
    tags=["env:prod"],             # Tags for stored memories
    recall_tags=["scope:global"],  # Tags to filter recall
    recall_tags_match="any",       # Tag match mode
)

# Now create tools without passing client
tools = create_hindsight_tools(bank_id="user-123")

Memory Scoping with Tags

Use tags to partition memories by topic, session, or user:

# Store memories tagged by source
tools = create_hindsight_tools(
    client=client,
    bank_id="user-123",
    tags=["source:chat", "session:abc"],
    recall_tags=["source:chat"],
    recall_tags_match="any",
)

Configuration Reference

Parameter	Default	Description
bank_id	required	Hindsight memory bank ID
client	None	Pre-configured Hindsight client
hindsight_api_url	None	API URL (used if no client provided)
api_key	None	API key (used if no client provided)
budget	"mid"	Recall/reflect budget level (low/mid/high)
max_tokens	4096	Maximum 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	Default metadata dict for retain operations
retain_document_id	None	Default 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	None	Max tokens for reflect results (defaults to max_tokens)
reflect_response_schema	None	JSON schema to constrain reflect output format
reflect_tags	None	Tags to filter memories used in reflect (defaults to recall_tags)
reflect_tags_match	None	Tag matching for reflect (defaults to recall_tags_match)
include_retain	True	Include the retain (store) tool
include_recall	True	Include the recall (search) tool
include_reflect	True	Include the reflect (synthesize) tool

Requirements

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

Documentation

• Integration docs
• Hindsight API docs