fleet-memory/hindsight-docs/docs/sdks/python.md

sidebar_position
1

Python Client

Official Python client for the Hindsight API.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Installation

The hindsight-all package includes embedded PostgreSQL, HTTP API server, and client:

pip install hindsight-all

If you already have a Hindsight server running:

pip install hindsight-client

Quick Start

import os
from hindsight import HindsightServer, HindsightClient

with HindsightServer(
    llm_provider="openai",
    llm_model="gpt-4.1-mini",
    llm_api_key=os.environ["OPENAI_API_KEY"]
) as server:
    client = HindsightClient(base_url=server.url)

    # Store a memory
    client.put(agent_id="my-agent", content="Alice works at Google")

    # Search memories
    results = client.search(agent_id="my-agent", query="What does Alice do?")
    for r in results:
        print(r["text"], r["weight"])

    # Generate response with personality
    answer = client.think(agent_id="my-agent", query="Tell me about Alice")
    print(answer["text"])

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

# Store a memory
client.put(agent_id="my-agent", content="Alice works at Google")

# Search memories
results = client.search(agent_id="my-agent", query="What does Alice do?")
for r in results:
    print(r["text"], r["weight"])

# Generate response with personality
answer = client.think(agent_id="my-agent", query="Tell me about Alice")
print(answer["text"])

Client Initialization

from hindsight_client import Hindsight

client = Hindsight(
    base_url="http://localhost:8888",  # Hindsight API URL
    timeout=30.0,                       # Request timeout in seconds
)

Memory Operations

Store Single Memory

client.store(
    agent_id="my-agent",
    content="Alice works at Google as a software engineer",
    context="career discussion",           # Optional context
    event_date="2024-01-15T10:00:00Z",    # Optional event date
)

Store Batch

client.store_batch(
    agent_id="my-agent",
    items=[
        {"content": "Alice works at Google", "context": "career"},
        {"content": "Bob is a data scientist", "context": "career"},
    ],
    document_id="conversation_001",  # Optional grouping
)

Search Operations

Basic Search

results = client.search(
    agent_id="my-agent",
    query="What does Alice do?",
)

for r in results:
    print(f"{r['text']} (weight: {r['weight']})")

Advanced Search

results = client.search_memories(
    agent_id="my-agent",
    query="What does Alice do?",
    fact_type=["world", "agent"],  # Filter by type
    max_tokens=4096,               # Token budget for results
    top_k=10,                      # Max results
)

Search by Fact Type

# Search only world facts
world_facts = client.search_memories(
    agent_id="my-agent",
    query="Who works at Google?",
    fact_type=["world"],
)

# Search only opinions
opinions = client.search_memories(
    agent_id="my-agent",
    query="What do I think about Python?",
    fact_type=["opinion"],
)

Think (Generate Response)

Generate personality-aware responses using retrieved memories:

answer = client.think(
    agent_id="my-agent",
    query="What should I know about Alice?",
    thinking_budget=100,  # Tokens for query understanding
)

print(answer["text"])           # Generated response
print(answer["based_on"])       # Memories used
print(answer["new_opinions"])   # New opinions formed

Agent Management

Create Agent

client.create_agent(
    agent_id="my-agent",
    name="Assistant",
    background="I am a helpful AI assistant",
    personality={
        "openness": 0.7,
        "conscientiousness": 0.8,
        "extraversion": 0.5,
        "agreeableness": 0.6,
        "neuroticism": 0.3,
        "bias_strength": 0.5,
    },
)

Get Profile

profile = client.get_profile(agent_id="my-agent")
print(profile["personality"])
print(profile["background"])

List Agents

agents = client.list_agents()
for agent in agents:
    print(agent["agent_id"])

Update Personality

client.update_personality(
    agent_id="my-agent",
    openness=0.9,
    conscientiousness=0.7,
)

Update Background

client.update_background(
    agent_id="my-agent",
    background="Additional context to merge with existing background",
)

Error Handling

from hindsight_client import Hindsight, HindsightError

client = Hindsight(base_url="http://localhost:8888")

try:
    results = client.search(agent_id="unknown", query="test")
except HindsightError as e:
    print(f"Error: {e.message}")
    print(f"Status: {e.status}")

Async Support

import asyncio
from hindsight_client import AsyncHindsight

async def main():
    client = AsyncHindsight(base_url="http://localhost:8888")

    # All methods have async versions
    await client.store(agent_id="my-agent", content="Hello world")
    results = await client.search(agent_id="my-agent", query="Hello")

    print(results)

asyncio.run(main())