# Hindsight

> Agent Memory that Works Like Human Memory

Hindsight is an agent memory system that gives AI agents persistent, structured memory across sessions. It extracts facts, entities, and relationships from conversations and enables temporal reasoning, opinion formation, and multi-strategy retrieval.

## Links

- [Full Documentation (llms-full.txt)](https://hindsight.vectorize.io/llms-full.txt): Complete documentation for LLM consumption
- [Quick Start](https://hindsight.vectorize.io/developer/api/quickstart): Get started in 60 seconds
- [Python SDK](https://hindsight.vectorize.io/sdks/python): Python client library
- [TypeScript SDK](https://hindsight.vectorize.io/sdks/nodejs): Node.js/TypeScript client
- [API Reference](https://hindsight.vectorize.io/api-reference): REST API documentation
- [OpenAPI Spec](https://hindsight.vectorize.io/openapi.json): Machine-readable API specification
- [MCP Server](https://hindsight.vectorize.io/sdks/mcp): Model Context Protocol integration
- [GitHub](https://github.com/vectorize-io/hindsight): Source code and issues

## Core Operations

- **Retain**: Store memories (extracts facts, entities, relationships automatically)
- **Recall**: Retrieve memories (semantic, keyword, graph, temporal search)
- **Reflect**: Deep analysis to form opinions and insights

## Quick Start

```bash
pip install hindsight-client
```

```python
from hindsight import HindsightClient

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

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

# Query
results = client.recall(bank_id="my-agent", query="What does Alice do?")

# Reflect
response = client.reflect(bank_id="my-agent", query="Tell me about Alice")
```

## Key Concepts

### Memory Banks
Each bank is an isolated memory store. One bank per user/agent. Banks contain facts, entities, documents, and their relationships.

### Memory Types
- World facts: General knowledge
- Experience facts: Personal experiences
- Opinion facts: Beliefs with confidence scores

### Document ID for Evolving Conversations
Use `document_id` to group messages in a conversation. Retaining with the same `document_id` replaces the previous version (upsert), keeping memory consistent as conversations evolve.

```python
client.retain(
    bank_id="user-123",
    content=messages,
    document_id="session_abc"  # Same ID = replace old version
)
```

## API Endpoints

Base URL: `http://localhost:8888`

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/v1/default/banks/{bank_id}/memories` | Store memories |
| POST | `/v1/default/banks/{bank_id}/memories/recall` | Retrieve memories |
| POST | `/v1/default/banks/{bank_id}/reflect` | Analyze and form opinions |
| GET | `/v1/default/banks/{bank_id}/profile` | Get bank profile |
| PUT | `/v1/default/banks/{bank_id}/profile` | Update bank profile |
| GET | `/v1/default/banks` | List all banks |
| POST | `/v1/default/banks` | Create a bank |

## Architecture Patterns

### Per-User Memory
One bank per user. Simplest pattern for chatbots and assistants.
[Guide](https://hindsight.vectorize.io/cookbook/per-user-memory)

### Support Agent + Shared Knowledge
User bank + shared docs bank. Client orchestrates queries to both banks and merges results.
[Guide](https://hindsight.vectorize.io/cookbook/support-agent-with-shared-knowledge)

## Installation

### Docker (recommended)
```bash
docker run -p 8888:8888 -e HINDSIGHT_API_LLM_PROVIDER=openai -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY ghcr.io/vectorize-io/hindsight
```

### Python (embedded)
```bash
pip install hindsight-all
```

### Clients
```bash
pip install hindsight-client          # Python
npm install @vectorize-io/hindsight-client  # TypeScript
```

## MCP Integration

Hindsight provides a Model Context Protocol server for direct AI agent integration:

```bash
pip install hindsight-mcp-server
hindsight-mcp-server --api-url http://localhost:8888
```

Tools exposed: `retain`, `recall`, `reflect`, `list_banks`, `create_bank`