Python SDK Guide

Fresh

Source: docs.hindsight.vectorize.io/python-sdk

Installation

pip install hindsight-client
# or
poetry add hindsight-client
# or
pipenv install hindsight-client

Quick Start

from hindsight_client import Hindsight

client = Hindsight(
    base_url="https://api.hindsight.vectorize.io",
    api_key="your-api-key"
)

# Create a memory bank
bank = client.create_bank(bank_id="my-assistant", name="My Assistant")

# Store a memory
client.retain(bank_id="my-assistant", content="The user prefers concise responses and dark mode.")

# Retrieve memories
result = client.recall(bank_id="my-assistant", query="What are the user's preferences?")
for memory in result.results:
    print(memory.text)

# Get an AI-powered answer
response = client.reflect(bank_id="my-assistant", query="How should I format my responses?")
print(response.text)

client.close()

Client Configuration

# Basic
client = Hindsight(
    base_url="https://api.hindsight.vectorize.io",
    api_key="your-api-key"
)

# Advanced with timeout
client = Hindsight(
    base_url="https://api.hindsight.vectorize.io",
    api_key="your-api-key",
    timeout=60.0
)

# From environment variables
import os
client = Hindsight(
    base_url=os.environ["HINDSIGHT_BASE_URL"],
    api_key=os.environ["HINDSIGHT_API_KEY"]
)

Memory Banks

Create

bank = client.create_bank(
    bank_id="customer-support-agent",
    name="Customer Support Agent",
    background="Handles customer inquiries for an e-commerce platform",
    disposition={"skepticism": 3, "literalism": 2, "empathy": 4}
)

List Memories

result = client.list_memories(bank_id="my-assistant", limit=100, offset=0)
print(f"Total memories: {result.total}")

Retain (Store)

Basic

client.retain(
    bank_id="my-assistant",
    content="User mentioned they work remotely and prefer async communication."
)

With Context and Metadata

client.retain(
    bank_id="my-assistant",
    content="Customer reported a bug with the checkout process.",
    context="Support ticket conversation",
    metadata={"ticket_id": "TKT-12345", "priority": "high"}
)

With Timestamp

from datetime import datetime
client.retain(bank_id="my-assistant", content="User signed up.", timestamp=datetime.now())

Batch

items = [
    {"content": "User is based in Pacific timezone"},
    {"content": "User prefers email over phone calls"},
    {"content": "User has been a customer for 3 years"}
]
client.retain_batch(bank_id="my-assistant", items=items)

Recall (Search)

Basic

result = client.recall(
    bank_id="my-assistant",
    query="What communication preferences does the user have?"
)
for memory in result.results:
    print(f"[{memory.type}] {memory.text}")

With Filters

result = client.recall(
    bank_id="my-assistant",
    query="project deadlines",
    max_tokens=4096,
    budget="mid"
)

# Filter by memory type
result = client.recall(
    bank_id="my-assistant",
    query="user preferences",
    types=["observation"]
)

Include Entities

result = client.recall(
    bank_id="my-assistant",
    query="Tell me about Alice",
    include_entities=True,
    max_entity_tokens=1000
)

Reflect (Reason)

Basic

response = client.reflect(
    bank_id="my-assistant",
    query="What should I know about this customer before our call?"
)
print(response.text)

With Context and Budget

response = client.reflect(
    bank_id="my-assistant",
    query="What are their main pain points?",
    context="We're preparing for a product review meeting",
    budget="high"
)
print(response.text)
for source in response.based_on:
    print(f"Based on: {source}")

Mental Models

Create

result = client.create_mental_model(
    bank_id="my-assistant",
    name="User Profile",
    source_query="What do we know about this user's preferences and background?"
)

Create with Options

result = client.create_mental_model(
    bank_id="my-assistant",
    name="Team Directory",
    source_query="Who works here and what do they do?",
    tags=["team", "directory"],
    max_tokens=4096,
    trigger={"refresh_after_consolidation": True}
)

List, Get, Refresh, Update, Delete

# List
models = client.list_mental_models(bank_id="my-assistant")
models = client.list_mental_models(bank_id="my-assistant", tags=["team"])

# Get
model = client.get_mental_model(bank_id="my-assistant", mental_model_id="mm_abc123")

# Refresh
result = client.refresh_mental_model(bank_id="my-assistant", mental_model_id="mm_abc123")

# Update
model = client.update_mental_model(
    bank_id="my-assistant",
    mental_model_id="mm_abc123",
    name="Updated Profile",
    trigger={"refresh_after_consolidation": True}
)

# Delete
client.delete_mental_model(bank_id="my-assistant", mental_model_id="mm_abc123")

Async Support

import asyncio
from hindsight_client import Hindsight

async def main():
    client = Hindsight(
        base_url="https://api.hindsight.vectorize.io",
        api_key="your-api-key"
    )

    await client.aretain(bank_id="my-assistant", content="Async memory storage")

    result = await client.arecall(bank_id="my-assistant", query="async test")
    for memory in result.results:
        print(memory.text)

    response = await client.areflect(bank_id="my-assistant", query="What do you know?")
    print(response.text)

    await client.aclose()

asyncio.run(main())

Concurrent Operations

async def store_multiple(client, bank_id, contents):
    tasks = [client.aretain(bank_id=bank_id, content=c) for c in contents]
    return await asyncio.gather(*tasks)

Error Handling

try:
    result = client.recall(bank_id="invalid-bank", query="test")
except Exception as e:
    print(f"Error: {e}")

Status	Cause	Solution
401	Invalid API key	Check your API key
402	Insufficient credits	Add credits
404	Invalid bank_id	Verify bank exists
400	Invalid request	Check parameters

Best Practices

• Reuse the client instance across your application
• Close the client when done (client.close() or use try/finally)
• Enable logging for debugging: logging.basicConfig(level=logging.DEBUG)
• Use environment variables for API keys — never hardcode