### Control Plane Examples

Source: https://hindsight.vectorize.io/developer/installation

Examples demonstrating how to run the Control Plane with different configurations.

```bash
# Run on custom port
npx @vectorize-io/hindsight-control-plane --port 9999 --api-url http://localhost:8888
# Using environment variables
export HINDSIGHT_CP_DATAPLANE_API_URL=http://api.example.com
npx @vectorize-io/hindsight-control-plane
# Production deployment
PORT=80 HINDSIGHT_CP_DATAPLANE_API_URL=https://api.hindsight.io npx @vectorize-io/hindsight-control-plane
```

--------------------------------

### CLI Installation

Source: https://hindsight.vectorize.io/developer/api/quickstart

Command to install the Hindsight CLI by downloading and executing a script.

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

--------------------------------

### Start API Server with pip

Source: https://hindsight.vectorize.io/developer/api/quickstart

Installs the Hindsight API and starts the server using pip. Includes environment variables for API key.

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

--------------------------------

### Command Line Interface (CLI) Examples

Source: https://hindsight.vectorize.io/developer/api/quickstart

Examples of using the Hindsight CLI to retain, recall, and reflect on memories.

```bash
hindsight memory retain my-bank "Alice works at Google as a software engineer"
hindsight memory recall my-bank "What does Alice do?"
hindsight memory reflect my-bank "Tell me about Alice"
```

--------------------------------

### Install Hindsight Docs Skill

Source: https://hindsight.vectorize.io/developer/api/quickstart

Command to install the Hindsight docs skill using npx.

```bash
npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docs
```

--------------------------------

### Python Client Example

Source: https://hindsight.vectorize.io/developer/api/quickstart

Example of using the Hindsight Python client to retain, recall, and reflect on information.

```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 Client Example

Source: https://hindsight.vectorize.io/developer/api/quickstart

Example of using the Hindsight Node.js client to retain, recall, and reflect on information.

```javascript
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 Options

Source: https://hindsight.vectorize.io/developer/installation

Examples of common CLI commands for the Hindsight API server.

```bash
hindsight-api --port 9000          # Custom port (default: 8888)
hindsight-api --host 127.0.0.1     # Bind to localhost only
hindsight-api --workers 4          # Multiple worker processes
hindsight-api --log-level debug    # Verbose logging
```

--------------------------------

### Run Control Plane Standalone

Source: https://hindsight.vectorize.io/developer/installation

Starts the Hindsight Control Plane (Web UI) using npx.

```bash
npx @vectorize-io/hindsight-control-plane --api-url http://localhost:8888
```

--------------------------------

### Minimal setup and Custom model with tuning

Source: https://hindsight.vectorize.io/llms-full.txt

Examples of setting environment variables for the llama.cpp provider, including minimal setup and a more customized configuration with a specific model, context size, grammar enforcement, and extra arguments.

```bash
# Minimal setup (auto-downloads model, uses GPU)
export HINDSIGHT_API_LLM_PROVIDER=llamacpp

# Custom model with tuning
export HINDSIGHT_API_LLM_PROVIDER=llamacpp
export HINDSIGHT_API_LLM_MAX_CONCURRENT=2
export HINDSIGHT_API_LLAMACPP_MODEL_PATH=~/.hindsight/models/my-model.gguf
export HINDSIGHT_API_LLAMACPP_CONTEXT_SIZE=16384
export HINDSIGHT_API_LLAMACPP_NO_GRAMMAR=true  # faster, less reliable JSON
export HINDSIGHT_API_LLAMACPP_EXTRA_ARGS="--n_threads 8"
```

--------------------------------

### Quick Start

Source: https://hindsight.vectorize.io/llms-full.txt

A basic example demonstrating how to initialize the client, retain a memory, recall memories, and generate a contextual answer using reflect.

```python
from hindsight_client import Hindsight

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

# Retain a memory
client.retain(bank_id="my-bank", content="Alice works at Google")

# Recall memories
results = client.recall(bank_id="my-bank", query="What does Alice do?")
for r in results.results:
    print(r.text)

# Reflect - generate a contextual answer
answer = client.reflect(bank_id="my-bank", query="Tell me about Alice")
print(answer.text)
```

--------------------------------

### Run with Embedded Database

Source: https://hindsight.vectorize.io/developer/installation

Starts Hindsight with an embedded PostgreSQL database for development and testing.

```bash
export HINDSIGHT_API_LLM_PROVIDER=groqexport HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxxhindsight-api
```

--------------------------------

### Install Hindsight-all

Source: https://hindsight.vectorize.io/developer/installation

Install the full Hindsight package for programmatic use in Python.

```python
pip install hindsight-all        # Full — works out of the box
```

--------------------------------

### Hindsight API Initial Setup (Windows)

Source: https://hindsight.vectorize.io/llms-full.txt

Environment variables and command to start the Hindsight API server, configuring OpenAI as the LLM provider.

```powershell
pip install hindsight-api

set HINDSIGHT_API_DATABASE_URL=postgresql://postgres@localhost:5432/hindsight
set HINDSIGHT_API_LLM_PROVIDER=openai
set HINDSIGHT_API_LLM_API_KEY=sk-xxx
set HINDSIGHT_API_LLM_MODEL=gpt-4o-mini

hindsight-api
```

--------------------------------

### Pip Install Full API

Source: https://hindsight.vectorize.io/developer/installation

Installs the full Hindsight API package using pip.

```shell
pip install hindsight-api        # Full — works out of the box
```

--------------------------------

### Observations Mission Example

Source: https://hindsight.vectorize.io/developer/observations

Examples of how to set the observations_mission to define what gets synthesized into observations.

```text
e.g. Observations are stable facts about people and projects.     Always include preferences, skills, and recurring patterns.     Ignore one-off events and ephemeral state.
```

```text
Observations are weekly summaries of sprint outcomes and blockers
```

```text
Observations are stable facts about named individuals only
```

```text
Observations are recurring patterns in customer support interactions
```

--------------------------------

### Go Client API Usage

Source: https://hindsight.vectorize.io/developer/api/quickstart

Demonstrates how to use the Hindsight Go client to interact with the memory API for retaining, recalling, and reflecting.

```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: "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())
```

--------------------------------

### Installation with uvx

Source: https://hindsight.vectorize.io/llms-full.txt

Install the hindsight-embed SDK using uvx, which ensures you get the latest version.

```bash
# Run directly without installation
uvx hindsight-embed@latest configure

# Or use pipx for persistent installation
pipx install hindsight-embed
```

--------------------------------

### Start API Server with Docker

Source: https://hindsight.vectorize.io/developer/api/quickstart

Runs the Hindsight API server using Docker, mapping ports and setting environment variables for LLM API key and worker ID.

```bash
export OPENAI_API_KEY=sk-xxxdocker run --rm -it --pull always -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
```

--------------------------------

### Chinese Reflection Example

Source: https://hindsight.vectorize.io/llms-full.txt

Example of performing a reflection operation with Chinese queries to get Chinese responses.

```python
# Store facts about team members (in Chinese)
hindsight.retain(
    bank_id="team-eval",
    content="张伟是一位优秀的软件工程师，完成了五个重大项目。他总是按时交付，代码整洁有良好的文档。",
    context="绩效评估"
)

hindsight.retain(
    bank_id="team-eval",
    content="李明最近加入团队。他错过了第一个截止日期，代码有很多bug。",
    context="绩效评估"
)

# Reflect in Chinese
result = hindsight.reflect(
    bank_id="team-eval",
    query="谁是更可靠的工程师？"
)

# Response is in Chinese:
# "我认为张伟更可靠。张伟完成了五个重大项目，按时交付，代码质量高..."

```

--------------------------------

### Example: Using a custom schema

Source: https://hindsight.vectorize.io/developer/configuration

Demonstrates how to set environment variables for a custom PostgreSQL schema.

```bash
export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@host:5432/dbname
export HINDSIGHT_API_DATABASE_SCHEMA=hindsight
```

--------------------------------

### Response Sample: Get Operation Status (200)

Source: https://hindsight.vectorize.io/api-reference

Example JSON response for a successful request to get the status of an operation.

```json
{
  "bank_id": "user123",
  "limit": 20,
  "offset": 0,
  "operations": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "task_type": "retain"
    }
  ],
  "total": 150
}
```

--------------------------------

### Python example for using response_schema

Source: https://hindsight.vectorize.io/developer/api/reflect

This example demonstrates how to use the `response_schema` parameter with Pydantic to get structured output from the Reflect API.

```python
from pydantic import BaseModel

# Define your response structure with Pydantic
class HiringRecommendation(BaseModel):
    recommendation: str
    confidence: str  # "low", "medium", "high"
    key_factors: list[str]
    risks: list[str] = []

response = client.reflect(
    bank_id="hiring-team",
    query="Should we hire Alice for the ML team lead position?",
    response_schema=HiringRecommendation.model_json_schema(),
)

# Parse structured output into Pydantic model
result = HiringRecommendation.model_validate(response.structured_output)
print(f"Recommendation: {result.recommendation}")
print(f"Confidence: {result.confidence}")
print(f"Key factors: {result.key_factors}")
```

--------------------------------

### Windows - Create Database and Enable Vector Extension

Source: https://hindsight.vectorize.io/developer/installation

Commands to create the PostgreSQL database and enable the vector extension on Windows.

```bash
# Create the database and enable the vector extension
psql -U postgres -c "CREATE DATABASE hindsight;"
psql -U postgres -d hindsight -c "CREATE EXTENSION vector;"
```

--------------------------------

### Get Document Example

Source: https://hindsight.vectorize.io/developer/api/documents

Retrieves a specific document from the Hindsight API.

```Go
doc, _, err := client.DocumentsAPI.GetDocument(ctx, "my-bank", "meeting-2024-03-15").Execute()
if err != nil {
	log.Fatalf("Failed to get document: %v", err)
}
fmt.Printf("Document ID: %s\n", doc.GetId())
fmt.Printf("Memory units: %d\n", doc.GetMemoryUnitCount())
```

--------------------------------

### Go SDK Example

Source: https://hindsight.vectorize.io/developer/api/documents

Demonstrates how to list documents using the Go SDK, including basic error handling and iterating through results.

```go
// List all documents
docs, _, err := client.DocumentsAPI.ListDocuments(ctx, "my-bank").Execute()
if err != nil {
	log.Fatalf("Failed to list documents: %v", err)
}

for _, d := range docs.Items {
	id, _ := d["id"].(string)
	memCount, _ := d["memory_unit_count"].(float64)
	fmt.Printf("%s: %d memories\n", id, int(memCount))
}
```

--------------------------------

### LM Studio Provider Example

Source: https://hindsight.vectorize.io/developer/configuration

Configuration for using LM Studio for local LLM inference, including the base URL and model name. No API key is required.

```bash
export HINDSIGHT_API_LLM_PROVIDER=lmstudio
export HINDSIGHT_API_LLM_BASE_URL=http://localhost:1234/v1
export HINDSIGHT_API_LLM_MODEL=your-local-model
```

--------------------------------

### Groq Provider Example

Source: https://hindsight.vectorize.io/developer/configuration

Configuration for using Groq as the LLM provider, including API key and model selection. It also shows how to set the service tier.

```bash
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-20b
# For free tier users: override to on_demand if you get service_tier errors
# export HINDSIGHT_API_LLM_GROQ_SERVICE_TIER=on_demand
```

--------------------------------

### Get Document (CLI)

Source: https://hindsight.vectorize.io/developer/api/documents

Example of retrieving a document's original text and metadata using the CLI.

```bash
hindsight document get my-bank meeting-2024-03-15
```

--------------------------------

### Get Document (Node.js)

Source: https://hindsight.vectorize.io/developer/api/documents

Example of retrieving a document's original text and metadata using the SDK.

```JavaScript
// Get document to expand context from recall results
const { data: doc, error } = await sdk.getDocument({
    client: apiClient,
    path: { bank_id: 'my-bank', document_id: 'meeting-2024-03-15-section-1' }
});
if (error) {
    throw new Error(`Failed to get document: ${JSON.stringify(error)}`);
}
console.log(`Document: ${doc.id}`);
console.log(`Original text: ${doc.original_text}`);
console.log(`Memory count: ${doc.memory_unit_count}`);
console.log(`Created: ${doc.created_at}`);
```

--------------------------------

### LiteLLM Router Configuration Example

Source: https://hindsight.vectorize.io/developer/configuration

Example environment variables for setting up the LiteLLM Router provider with a default and fallback model.

```bash
export HINDSIGHT_API_LLM_PROVIDER=litellmrouter
export HINDSIGHT_API_LLM_LITELLMROUTER_CONFIG='{
  "model_list": [
    {"model_name": "default",  "litellm_params": {"model": "openai/gpt-4o-mini", "api_key": "sk-..."}},
    {"model_name": "fallback", "litellm_params": {"model": "anthropic/claude-sonnet-4-5", "api_key": "sk-ant-..."}}
  ],
  "fallbacks": [{"default": ["fallback"]}]}'
```

--------------------------------

### Example Usage

Source: https://hindsight.vectorize.io/llms-full.txt

Demonstrates starting a Hindsight server, retaining and recalling information, and stopping the server.

```typescript
const server = new HindsightServer({
  profile: 'my-app',
  port: 9077,
  env: {
    HINDSIGHT_API_LLM_PROVIDER: 'anthropic',
    HINDSIGHT_API_LLM_API_KEY: process.env.ANTHROPIC_API_KEY,
    HINDSIGHT_API_LLM_MODEL: 'claude-sonnet-4-20250514',
    HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT: '0',
  },
  logger: consoleLogger,
});

await server.start();

const client = new HindsightClient({ baseUrl: server.getBaseUrl() });
await client.retain('user-123', 'User prefers dark mode.');
const recall = await client.recall('user-123', 'what are the user preferences?');

await server.stop();
```

--------------------------------

### llama.cpp Provider Example

Source: https://hindsight.vectorize.io/developer/configuration

Configuration for using the built-in llama.cpp inference engine. No API key, base URL, or external server is needed. It mentions auto-downloading models.

```bash
export HINDSIGHT_API_LLM_PROVIDER=llamacpp
# No API key, base URL, or external server required.
# Auto-downloads Gemma 4 E2B (~3.5 GB GGUF) on first run.
# See "Built-in llama.cpp" section below for all configuration options.
```

--------------------------------

### Response Sample for Getting Chunk Details

Source: https://hindsight.vectorize.io/api-reference

Example JSON response containing details of a specific chunk.

```json
{
  "bank_id": "user123",
  "chunk_id": "user123_session_1_0",
  "chunk_index": 0,
  "chunk_text": "This is the first chunk of the document...",
  "created_at": "2024-01-15T10:30:00Z",
  "document_id": "session_1"
}
```

--------------------------------

### Get Document (Python)

Source: https://hindsight.vectorize.io/developer/api/documents

Example of retrieving a document's original text and metadata using the Documents API.

```Python
from hindsight_client_api import ApiClient, Configuration
from hindsight_client_api.api import DocumentsApi

async def get_document_example():
    config = Configuration(host="http://localhost:8888")
    api_client = ApiClient(config)
    api = DocumentsApi(api_client)
    # Get document to expand context from recall results
    doc = await api.get_document(
        bank_id="my-bank",
        document_id="meeting-2024-03-15"
    )
    print(f"Document: {doc.id}")
    print(f"Original text: {doc.original_text}")
    print(f"Memory count: {doc.memory_unit_count}")
    print(f"Created: {doc.created_at}")

asyncio.run(get_document_example())
```

--------------------------------

### llama.cpp Minimal Setup

Source: https://hindsight.vectorize.io/developer/configuration

Minimal environment variables to set up the built-in llama.cpp provider, which auto-downloads a default model.

```bash
# Minimal setup (auto-downloads model, uses GPU)
export HINDSIGHT_API_LLM_PROVIDER=llamacpp
```

--------------------------------

### Groq Provider Example

Source: https://hindsight.vectorize.io/llms-full.txt

Example configuration for using Groq as the LLM provider, recommended for fast inference.

```bash
# Groq (recommended for fast inference)
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-20b
# For free tier users: override to on_demand if you get service_tier errors
# export HINDSIGHT_API_LLM_GROQ_SERVICE_TIER=on_demand
```

--------------------------------

### Retain Chinese Content

Source: https://hindsight.vectorize.io/llms-full.txt

Example of retaining Chinese content and querying in Chinese to get Chinese results.

```python
from hindsight import Hindsight

hindsight = Hindsight()

# Retain Chinese content
hindsight.retain(
    bank_id="user-123",
    content="""
    张伟是一位资深软件工程师，在腾讯工作了五年。
    他专门研究分布式系统，并领导了公司微服务架构的开发。
    """,
    context="团队概述"
)

# Query in Chinese - get Chinese results
results = hindsight.recall(
    bank_id="user-123",
    query="告诉我关于张伟的信息"
)

# Facts are returned in Chinese:
# - 张伟是一位资深软件工程师，在腾讯工作了五年
# - 张伟专门研究分布式系统，并领导了公司微服务架构的开发

```

--------------------------------

### LM Studio Provider Example

Source: https://hindsight.vectorize.io/llms-full.txt

Example configuration for using LM Studio for local LLM inference.

```bash
# LM Studio (local, no API key)
export HINDSIGHT_API_LLM_PROVIDER=lmstudio
export HINDSIGHT_API_LLM_BASE_URL=http://localhost:1234/v1
export HINDSIGHT_API_LLM_MODEL=your-local-model
```

--------------------------------

### Configuration Examples

Source: https://hindsight.vectorize.io/developer/models

Environment variable configurations for various reranking providers supported by LiteLLM.

```bash
# Local provider (default)
export HINDSIGHT_API_RERANKER_PROVIDER=local
export HINDSIGHT_API_RERANKER_LOCAL_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2

# Cohere
export HINDSIGHT_API_RERANKER_PROVIDER=cohere
export HINDSIGHT_API_RERANKER_COHERE_API_KEY=your-api-key
export HINDSIGHT_API_RERANKER_COHERE_MODEL=rerank-english-v3.0

# Cohere-compatible endpoint (Azure AI Foundry, Jina, Voyage, self-hosted BGE, ...)
# Setting COHERE_BASE_URL switches the provider off the Cohere SDK and onto a
# plain HTTP client that speaks the standard rerank wire format:
#   POST {base_url}  Authorization: Bearer <key>
#   {"model","query","documents","return_documents":false}
#   -> {"results":[{"index","relevance_score"}, ...]}
export HINDSIGHT_API_RERANKER_PROVIDER=cohere
export HINDSIGHT_API_RERANKER_COHERE_API_KEY=your-api-key
export HINDSIGHT_API_RERANKER_COHERE_MODEL=rerank-v3.5  # whatever model the endpoint serves
export HINDSIGHT_API_RERANKER_COHERE_BASE_URL=https://your-endpoint.example/rerank

# ZeroEntropy (state-of-the-art accuracy)
export HINDSIGHT_API_RERANKER_PROVIDER=zeroentropy
export HINDSIGHT_API_RERANKER_ZEROENTROPY_API_KEY=your-api-key
export HINDSIGHT_API_RERANKER_ZEROENTROPY_MODEL=zerank-2  # default, can omit

# SiliconFlow (Cohere-compatible /rerank endpoint)
export HINDSIGHT_API_RERANKER_PROVIDER=siliconflow
export HINDSIGHT_API_RERANKER_SILICONFLOW_API_KEY=your-api-key
export HINDSIGHT_API_RERANKER_SILICONFLOW_MODEL=BAAI/bge-reranker-v2-m3  # default, can omit

# Alibaba Cloud DashScope (qwen3-rerank)
export HINDSIGHT_API_RERANKER_PROVIDER=alibaba
export HINDSIGHT_API_RERANKER_ALIBABA_API_KEY=your-dashscope-api-key
export HINDSIGHT_API_RERANKER_ALIBABA_MODEL=qwen3-rerank  # default, can omit

# TEI (self-hosted)
export HINDSIGHT_API_RERANKER_PROVIDER=tei
export HINDSIGHT_API_RERANKER_TEI_URL=http://localhost:8081

# FlashRank (lightweight)
export HINDSIGHT_API_RERANKER_PROVIDER=flashrank

# LiteLLM proxy
export HINDSIGHT_API_RERANKER_PROVIDER=litellm
export HINDSIGHT_API_LITELLM_API_BASE=http://localhost:4000
export HINDSIGHT_API_RERANKER_LITELLM_MODEL=cohere/rerank-english-v3.0

# RRF-only (no neural reranking)
export HINDSIGHT_API_RERANKER_PROVIDER=rrf
```

--------------------------------

### Response Sample: Get Operation Status (200) - Detailed

Source: https://hindsight.vectorize.io/api-reference

Detailed example JSON response for a completed operation.

```json
{
  "completed_at": "2024-01-15T10:31:30Z",
  "created_at": "2024-01-15T10:30:00Z",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "refresh_mental_models",
  "status": "completed",
  "updated_at": "2024-01-15T10:31:30Z"
}
```

--------------------------------

### Quick Start: Use Memory Operations

Source: https://hindsight.vectorize.io/llms-full.txt

Examples of storing, querying, and reflecting on memories using the hindsight-embed CLI.

```bash
# Store a memory
hindsight-embed memory retain default "User prefers dark mode"

# Query memories
hindsight-embed memory recall default "user preferences"

# Reasoning with memory
hindsight-embed memory reflect default "What color scheme should I use?"
```

--------------------------------

### Windows - Build pgvector

Source: https://hindsight.vectorize.io/developer/installation

Steps to build the pgvector extension on Windows.

```bash
# Install PostgreSQL
winget install PostgreSQL.PostgreSQL.17
# Build pgvector (requires Visual Studio Build Tools)
git clone https://github.com/pgvector/pgvector.git
cd pgvector
# Open "x64 Native Tools Command Prompt for VS" and run:
set PGROOT=C:\Program Files\PostgreSQL\17
nmake /F Makefile.winnmake /F Makefile.win install
```

--------------------------------

### Hindsight Managed Subprocess Embedding (HindsightEmbedded)

Source: https://hindsight.vectorize.io/developer/installation

Example of using Hindsight programmatically with HindsightEmbedded, where the server runs as a background daemon process.

```python
from hindsight import HindsightEmbedded
client = HindsightEmbedded(llm_provider="openai", llm_api_key="sk-xxx")
client.retain(bank_id="alice", content="Alice prefers concise answers.")
results = client.recall(bank_id="alice", query="How should I respond to Alice?")
```

--------------------------------

### CLI Example

Source: https://hindsight.vectorize.io/developer/api/memory-banks

Example of creating a bank with specific configuration using the command-line interface, including mission and disposition settings.

```bash
hindsight bank create architect-bank \
  --mission "You're a senior software architect - keep track of system designs, technology decisions, and architectural patterns. Prefer simplicity over cutting-edge." \
  --skepticism 4 \
  --literalism 4 \
  --empathy 2
```

--------------------------------

### Hindsight In-process Embedding (HindsightServer)

Source: https://hindsight.vectorize.io/developer/installation

Example of using Hindsight programmatically with the HindsightServer, where the server runs in a background thread within the application.

```python
from hindsight import HindsightServer, HindsightClient
with HindsightServer(llm_provider="openai", llm_api_key="sk-xxx") as server:
    client = HindsightClient(base_url=server.url)
    client.retain(bank_id="alice", content="Alice prefers concise answers.")
    results = client.recall(bank_id="alice", query="How should I respond to Alice?")
```

--------------------------------

### OpenTelemetry Tracing Configuration Example

Source: https://hindsight.vectorize.io/developer/configuration

Example environment variables to enable and configure OpenTelemetry tracing, including endpoint, headers, service name, and deployment environment.

```bash
# Enable tracing
export HINDSIGHT_API_OTEL_TRACES_ENABLED=true
# Configure endpoint (example: OpenLIT Cloud)
export HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.openlit.io
export HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer olit-xxx"
# Optional: Custom service name and environment
export HINDSIGHT_API_OTEL_SERVICE_NAME=hindsight-production
export HINDSIGHT_API_OTEL_DEPLOYMENT_ENVIRONMENT=production
```

--------------------------------

### Get Entity Details - 200 Response Sample

Source: https://hindsight.vectorize.io/api-reference

Example JSON response for a successful request to retrieve entity details.

```json
{
  "canonical_name": "John",
  "first_seen": "2024-01-15T10:30:00Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "last_seen": "2024-02-01T14:00:00Z",
  "mention_count": 15,
  "observations": [
    {
      "mentioned_at": "2024-01-15T10:30:00Z",
      "text": "John works at Google"
    }
  ]
}
```

--------------------------------

### Environment Variables: Groq Provider Example

Source: https://hindsight.vectorize.io/llms-full.txt

Example of setting environment variables for the Groq LLM provider.

```bash
# Groq (fast inference)
export HINDSIGHT_EMBED_LLM_PROVIDER=groq
export HINDSIGHT_EMBED_LLM_API_KEY=gsk_xxxxxxxxxxxx
export HINDSIGHT_EMBED_LLM_MODEL=llama-3.3-70b-versatile
```

--------------------------------

### Example: Reset to defaults

Source: https://hindsight.vectorize.io/developer/configuration

This example shows how to reset a bank's configuration to its defaults using a cURL command.

```shell
curl -X DELETE http://localhost:8888/v1/default/banks/my-bank/config
```

--------------------------------

### Get Entity Co-occurrence Graph - 200 Response Sample

Source: https://hindsight.vectorize.io/api-reference

Example JSON response for a successful request to retrieve an entity co-occurrence graph.

```json
{
  "edges": [
    {
      "data": {
        "color": "#ffd700",
        "id": "uuid-1-uuid-2",
        "lastCooccurred": "2024-02-01T14:00:00Z",
        "lineStyle": "solid",
        "linkType": "cooccurrence",
        "source": "uuid-1",
        "target": "uuid-2",
        "weight": 5
      }
    }
  ],
  "limit": 1000,
  "nodes": [
    {
      "data": {
        "color": "#42a5f5",
        "id": "uuid-1",
        "label": "Alice",
        "mentionCount": 12
      }
    },
    {
      "data": {
        "color": "#42a5f5",
        "id": "uuid-2",
        "label": "Google",
        "mentionCount": 8
      }
    }
  ],
  "total_edges": 1,
  "total_entities": 2
}
```

--------------------------------

### Get Bank Profile Response Sample (200)

Source: https://hindsight.vectorize.io/api-reference

Example JSON response for a successful request to retrieve a memory bank's profile.

```json
{
  "bank_id": "user123",
  "disposition": {
    "empathy": 3,
    "literalism": 3,
    "skepticism": 3
  },
  "mission": "I am a software engineer helping my team stay organized and ship quality code",
  "name": "Alice"
}
```

--------------------------------

### OpenAI Provider Example

Source: https://hindsight.vectorize.io/developer/configuration

Configuration for using OpenAI as the LLM provider, including API key and model selection. It also shows the option to use Flex Processing for cost savings.

```bash
export HINDSIGHT_API_LLM_PROVIDER=openaiexport HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=gpt-4o
# Optional: Use Flex Processing for 50% cost savings (with variable latency)# export HINDSIGHT_API_LLM_OPENAI_SERVICE_TIER=flex
```

--------------------------------

### Install Dependencies

Source: https://hindsight.vectorize.io/llms-full.txt

Command to install project dependencies using uv.

```bash
uv sync
```

--------------------------------

### Response Sample for Get Document Details (200 OK)

Source: https://hindsight.vectorize.io/api-reference

Example JSON response for retrieving document details, including metadata and retain parameters.

```json
{
  "bank_id": "user123",
  "content_hash": "abc123",
  "created_at": "2024-01-15T10:30:00Z",
  "document_metadata": {
    "channel": "#general",
    "source": "slack"
  },
  "id": "session_1",
  "memory_unit_count": 15,
  "original_text": "Full document text here...",
  "retain_params": {
    "context": "Team meeting notes",
    "event_date": "2024-01-15"
  },
  "tags": [
    "user_a",
    "session_123"
  ],
  "updated_at": "2024-01-15T10:30:00Z"
}
```

--------------------------------

### Configure Environment

Source: https://hindsight.vectorize.io/llms-full.txt

Commands to copy the environment example file and edit it.

```bash
cp .env.example .env
```

```bash
# Database (connects to Docker postgres)
HINDSIGHT_API_DATABASE_URL=postgresql://hindsight:hindsight_dev@localhost:5432/hindsight

# LLM Provider (choose one)
HINDSIGHT_API_LLM_PROVIDER=groq
HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
HINDSIGHT_API_LLM_MODEL=llama-3.1-70b-versatile
```

--------------------------------

### Successful Response Sample for Get Bank Configuration

Source: https://hindsight.vectorize.io/api-reference

Example JSON response showing the bank ID, fully resolved configuration, and bank-specific overrides.

```json
{
  *   "bank_id": "my-bank",
      *   "config": {
          *   "llm_model": "gpt-4",
              *   "llm_provider": "openai",
              *   "retain_extraction_mode": "verbose"
                   },
      *   "overrides": {
          *   "llm_model": "gpt-4",
              *   "retain_extraction_mode": "verbose"
                   }
       }
```