/hindsight-docs

Quick Start

Get up and running with Hindsight in 60 seconds.

{/* Import raw source files */}

Clients

Start the API Server

pip (API only)

pip install hindsight-api
export OPENAI_API_KEY=sk-xxx
export HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY

hindsight-api

API available at http://localhost:8888

Docker (Full Experience)

export OPENAI_API_KEY=sk-xxx

docker run -it --pull always --name hindsight --restart unless-stopped --shm-size=1g -p 8888:8888 -p 9999:9999 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest

• API: http://localhost:8888
• Control Plane (Web UI): http://localhost:9999

💡 Set a stable HINDSIGHT_API_WORKER_ID in production

The worker uses the container hostname as its identity, which Docker sets to the container ID by default. That value changes on every restart, so any task that was being processed when the container went down stays parked under the old ID with no way for the new container to recognize it as its own.

Set HINDSIGHT_API_WORKER_ID to a stable value (e.g., -e HINDSIGHT_API_WORKER_ID=hindsight-prod) so the worker keeps the same identity across restarts. This is recommended even for single-container deployments. For diagnosis and recovery commands, see Admin CLI - Recovering stuck operations.

💡 LLM Provider

Hindsight requires an LLM with structured output support. Recommended: Groq with gpt-oss-20b for fast, cost-effective inference. See LLM Providers for more details.

Use the Client

Python

pip install hindsight-client

from hindsight_client import Hindsight

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

# Retain: Store information
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")

# Recall: Search memories
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect: Generate disposition-aware response
client.reflect(bank_id="my-bank", query="Tell me about Alice")

Node.js

npm install @vectorize-io/hindsight-client

import { HindsightClient } from '@vectorize-io/hindsight-client';

const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });

// Retain: Store information
await client.retain('my-bank', 'Alice works at Google as a software engineer');

// Recall: Search memories
await client.recall('my-bank', 'What does Alice do?');

// Reflect: Generate response
await client.reflect('my-bank', 'Tell me about Alice');

CLI

curl -fsSL https://hindsight.vectorize.io/get-cli | bash

# Retain: Store information
hindsight memory retain my-bank "Alice works at Google as a software engineer"

# Recall: Search memories
hindsight memory recall my-bank "What does Alice do?"

# Reflect: Generate response
hindsight memory reflect my-bank "Tell me about Alice"

Go

go get github.com/vectorize-io/hindsight/hindsight-clients/go

cfg := hindsight.NewConfiguration()
cfg.Servers = hindsight.ServerConfigurations{
	{URL: "http://localhost:8888"},
}
client := hindsight.NewAPIClient(cfg)
ctx := context.Background()

// Retain a memory
retainReq := hindsight.RetainRequest{
	Items: []hindsight.MemoryItem{
		{Content: hindsight.TextContent("Alice works at Google")},
	},
}
client.MemoryAPI.RetainMemories(ctx, "my-bank").RetainRequest(retainReq).Execute()

// Recall memories
recallReq := hindsight.RecallRequest{
	Query: "What does Alice do?",
}
resp, _, _ := client.MemoryAPI.RecallMemories(ctx, "my-bank").RecallRequest(recallReq).Execute()
for _, r := range resp.Results {
	fmt.Println(r.Text)
}

// Reflect - generate response
reflectReq := hindsight.ReflectRequest{
	Query: "Tell me about Alice",
}
answer, _, _ := client.MemoryAPI.Reflect(ctx, "my-bank").ReflectRequest(reflectReq).Execute()
fmt.Println(answer.GetText())

What's Happening

Integrations

Browse all supported integrations in the Integrations Hub.

Next Steps

• Retain — Advanced options for storing memories
• Recall — Search and retrieval strategies
• Reflect — Disposition-aware reasoning
• Memory Banks — Configure disposition and mission
• Server Deployment — Docker Compose, Helm, and production setup