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

Hindsight-OpenAI

Drop-in replacement for OpenAI Python client with automatic Hindsight integration.

Overview

hindsight-openai is a transparent wrapper around the official OpenAI Python client that automatically:

• 🧠 Injects relevant memories from your Hindsight system into conversations
• 💾 Stores conversation history to Hindsight for future retrieval
• 🔄 Works seamlessly with existing OpenAI code (just change the import)
• ⚡ Supports both sync and async clients

Installation

This package is part of the Hindsight workspace. Install from the root:

# From repository root
uv sync

# Or install just this package
cd hindsight-integrations/openai
uv pip install -e .

Quick Start

Basic Usage

from hindsight_openai import configure, OpenAI

# Configure Hindsight integration once
configure(
    hindsight_api_url="http://localhost:8888",
    agent_id="my-agent",
    store_conversations=True,
    inject_memories=True,
)

# Use OpenAI client as normal - Hindsight integration happens automatically
client = OpenAI(api_key="sk-...")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "What did we discuss about AI last week?"}
    ]
)

print(response.choices[0].message.content)

Async Usage

from hindsight_openai import configure, AsyncOpenAI

configure(
    hindsight_api_url="http://localhost:8888",
    agent_id="my-agent",
)

client = AsyncOpenAI(api_key="sk-...")

response = await client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Remind me about my preferences"}
    ]
)

Configuration Options

The configure() function accepts the following parameters:

Parameter	Type	Default	Description
hindsight_api_url	str	"http://localhost:8888"	URL of your Hindsight API server
agent_id	str	None	Required. Agent identifier for memory operations
api_key	str	None	Optional API key for Hindsight authentication
store_conversations	bool	True	Store conversations to Hindsight
inject_memories	bool	True	Inject relevant memories into prompts
document_id	str	None	Optional document ID for stored conversations
enabled	bool	True	Master switch to enable/disable Hindsight integration

How It Works

Memory Injection

When inject_memories=True, the wrapper:

1. Extracts the user's query from the last message
2. Searches Hindsight for relevant memories using the query
3. Injects the top memories as a system message before the conversation
4. Sends the enhanced conversation to OpenAI

Example:

# Your code:
messages = [
    {"role": "user", "content": "What's my favorite programming language?"}
]

# What gets sent to OpenAI (automatically):
messages = [
    {
        "role": "system",
        "content": "Relevant context from your memory:\n\n1. User prefers Python for its simplicity\n   (Date: 2024-01-15)\n   (Type: opinion)"
    },
    {"role": "user", "content": "What's my favorite programming language?"}
]

Conversation Storage

When store_conversations=True, the wrapper:

1. Captures the conversation context (recent messages)
2. Captures the assistant's response
3. Stores the complete exchange to Hindsight asynchronously
4. Tags it with context "openai_conversation" for filtering

This creates a searchable memory of all your AI conversations.

Advanced Usage

Disable for Specific Requests

from hindsight_openai import configure, OpenAI, reset_config

# Configure globally
configure(hindsight_api_url="http://localhost:8888", agent_id="agent-1")

client = OpenAI(api_key="sk-...")

# Normal request with Hindsight
response1 = client.chat.completions.create(...)

# Temporarily disable
reset_config()
response2 = client.chat.completions.create(...)  # No Hindsight integration

# Re-enable
configure(hindsight_api_url="http://localhost:8888", agent_id="agent-1")

Using Document ID

Group related conversations together using a document ID:

configure(
    hindsight_api_url="http://localhost:8888",
    agent_id="my-agent",
    document_id="meeting-2024-01-15",  # All conversations tagged with this ID
)

client = OpenAI(api_key="sk-...")

# All these calls will be stored under the same document
response1 = client.chat.completions.create(...)
response2 = client.chat.completions.create(...)

Cleanup

from hindsight_openai import cleanup_interceptor

# Clean up resources when done
await cleanup_interceptor()

Requirements

• Python >= 3.10
• openai >= 1.0.0
• httpx >= 0.23.0
• A running Hindsight API server

Development

Running Tests

uv run pytest tests

Project Structure

hindsight-integrations/openai/
├── hindsight_openai/
│   ├── __init__.py       # Main exports
│   ├── client.py         # OpenAI client wrappers
│   ├── config.py         # Global configuration
│   └── interceptor.py    # Request/response interception logic
├── tests/
│   └── test_client.py    # Test suite
├── pyproject.toml        # Package configuration
└── README.md             # This file

License

Part of the Hindsight project.