# vectorize-io/hindsight architecture

> Architecture diagram of the GitHub repository vectorize-io/hindsight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vectorize-io/hindsight
- Repository: https://github.com/vectorize-io/hindsight
- Video tour (about a minute): https://gitdiagram.com/vectorize-io/hindsight/video

## Overview

Hindsight is a long-term memory system for AI agents. Its principal workflow is to retain information in a bank, then recall relevant memories or reflect on them to produce a disposition-aware response. The repository also documents bank management, mental models, knowledge pages, MCP access, and webhook delivery. The graph reflects these product capabilities and the API/engine layers visible in the tree; some feature-level wiring is not shown because the corresponding route and engine source was not sampled.

Main entry points: [`hindsight-api-slim/hindsight_api/engine/memory_engine.py`](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memory_engine.py) (Memory engine), [`hindsight-api-slim/hindsight_api/engine/memories/postgres.py`](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memories/postgres.py) (Memory database), [`hindsight-api-slim/hindsight_api/engine/search/retrieval.py`](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/search/retrieval.py) (Recall retrieval), [`hindsight-api-slim/hindsight_api/api/http.py`](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/http.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Access surfaces"]
  node_clients["Client SDKs<br/>[client.go]"]
  node_cli["Command-line client<br/>[main.rs]"]
end

subgraph group_api["API and operations"]
  node_server["API server<br/>[main.py]"]
  node_http["HTTP API<br/>[http.py]"]
  node_memory_engine["Memory engine<br/>[memory_engine.py]"]
  node_bank["Memory banks<br/>[bank_aliases.py]"]
  node_worker["Operation worker<br/>[main.py]"]
  node_task_queue["Operation tasks<br/>[task_backend.py]"]
end

subgraph group_memory["Memory lifecycle"]
  node_retain["Retain orchestration<br/>[orchestrator.py]"]
  node_chunks["Chunk storage<br/>[chunk_storage.py]"]
  node_facts["Fact storage<br/>[fact_storage.py]"]
  node_consolidate["Consolidation<br/>[consolidator.py]"]
  node_transfer["Import and export<br/>[export.py]"]
  node_db[("Memory database<br/>[postgres.py]")]
end

subgraph group_reason["Retrieval and reasoning"]
  node_recall["Recall retrieval<br/>[retrieval.py]"]
  node_query["Query analysis<br/>[query_analyzer.py]"]
  node_reflect["Reflect agent<br/>[agent.py]"]
  node_mental["Mental models"]
  node_knowledge["Knowledge pages<br/>[page_markdown.py]"]
end

subgraph group_integrations["Integrations"]
  node_mcp["MCP API<br/>[mcp.py]"]
  node_providers["LLM providers<br/>[__init__.py]"]
  node_webhooks["Webhook manager<br/>[manager.py]"]
end

node_agent(("Agent or user"))
node_llm_service{{"LLM service"}}
node_webhook_target{{"Webhook endpoint"}}

node_agent -->|"uses"| node_clients
node_agent -->|"uses"| node_cli
node_clients -->|"HTTP requests"| node_http
node_cli -->|"HTTP requests"| node_http
node_server -->|"mounts"| node_http
node_http -->|"dispatches"| node_memory_engine
node_mcp -->|"dispatches"| node_memory_engine
node_memory_engine -->|"manages"| node_bank
node_memory_engine -->|"retains"| node_retain
node_memory_engine -->|"recalls"| node_recall
node_memory_engine -->|"reflects"| node_reflect
node_retain -->|"stores chunks"| node_chunks
node_retain -->|"stores facts"| node_facts
node_facts -->|"writes facts"| node_db
node_chunks -->|"writes chunks"| node_db
node_consolidate -->|"updates memories"| node_db
node_recall -->|"analyzes query"| node_query
node_recall -->|"retrieves memories"| node_db
node_reflect -->|"uses retrieval"| node_recall
node_reflect -->|"requests generation"| node_providers
node_providers -.->|"calls model"| node_llm_service
node_mental -->|"requests generation"| node_providers
node_knowledge -->|"serves page APIs"| node_memory_engine
node_transfer -->|"imports or exports"| node_db
node_memory_engine -->|"submits operations"| node_task_queue
node_worker -->|"processes tasks"| node_task_queue
node_webhooks -->|"reads registrations"| node_db
node_webhooks -->|"queues delivery"| node_task_queue
node_webhook_target -.->|"receives events"| node_webhooks

click node_clients "https://github.com/vectorize-io/hindsight/blob/main/hindsight-clients/go/client.go"
click node_cli "https://github.com/vectorize-io/hindsight/blob/main/hindsight-cli/src/main.rs"
click node_server "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/main.py"
click node_http "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/http.py"
click node_mcp "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/mcp.py"
click node_memory_engine "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memory_engine.py"
click node_bank "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/bank_aliases.py"
click node_retain "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py"
click node_chunks "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/chunk_storage.py"
click node_facts "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py"
click node_consolidate "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py"
click node_recall "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/search/retrieval.py"
click node_query "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/query_analyzer.py"
click node_reflect "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/reflect/agent.py"
click node_mental "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/mental_model_refresh.py"
click node_knowledge "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/page_markdown.py"
click node_transfer "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/transfer/export.py"
click node_db "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memories/postgres.py"
click node_providers "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/providers/__init__.py"
click node_webhooks "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/webhooks/manager.py"
click node_worker "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/worker/main.py"
click node_task_queue "https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/task_backend.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_clients,node_cli,node_agent toneBlue
class node_server,node_http,node_memory_engine,node_bank,node_worker,node_task_queue toneAmber
class node_retain,node_chunks,node_facts,node_consolidate,node_transfer,node_db,node_webhook_target toneMint
class node_recall,node_query,node_reflect,node_mental,node_knowledge toneRose
class node_mcp,node_providers,node_webhooks,node_llm_service toneIndigo
```

## Components

### Access surfaces

- [Client SDKs](https://github.com/vectorize-io/hindsight/blob/main/hindsight-clients/go/client.go): `hindsight-clients/go/client.go`
- [Command-line client](https://github.com/vectorize-io/hindsight/blob/main/hindsight-cli/src/main.rs): `hindsight-cli/src/main.rs`

### API and operations

- [API server](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/main.py): `hindsight-api-slim/hindsight_api/main.py`
- [HTTP API](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/http.py): `hindsight-api-slim/hindsight_api/api/http.py`
- [Memory engine](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memory_engine.py): `hindsight-api-slim/hindsight_api/engine/memory_engine.py`
- [Memory banks](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/bank_aliases.py): `hindsight-api-slim/hindsight_api/engine/bank_aliases.py`
- [Operation worker](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/worker/main.py): `hindsight-api-slim/hindsight_api/worker/main.py`
- [Operation tasks](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/task_backend.py): `hindsight-api-slim/hindsight_api/engine/task_backend.py`

### Memory lifecycle

- [Retain orchestration](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py): `hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py`
- [Chunk storage](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/chunk_storage.py): `hindsight-api-slim/hindsight_api/engine/retain/chunk_storage.py`
- [Fact storage](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py): `hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py`
- [Consolidation](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py): `hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py`
- [Import and export](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/transfer/export.py): `hindsight-api-slim/hindsight_api/engine/transfer/export.py`
- [Memory database](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memories/postgres.py): `hindsight-api-slim/hindsight_api/engine/memories/postgres.py`

### Retrieval and reasoning

- [Recall retrieval](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/search/retrieval.py): `hindsight-api-slim/hindsight_api/engine/search/retrieval.py`
- [Query analysis](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/query_analyzer.py): `hindsight-api-slim/hindsight_api/engine/query_analyzer.py`
- [Reflect agent](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/reflect/agent.py): `hindsight-api-slim/hindsight_api/engine/reflect/agent.py`
- [Mental models](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/mental_model_refresh.py): `hindsight-api-slim/hindsight_api/engine/mental_model_refresh.py`
- [Knowledge pages](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/page_markdown.py): `hindsight-api-slim/hindsight_api/api/page_markdown.py`

### Integrations

- [MCP API](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/mcp.py): `hindsight-api-slim/hindsight_api/api/mcp.py`
- [LLM providers](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/providers/__init__.py): `hindsight-api-slim/hindsight_api/engine/providers/__init__.py`
- [Webhook manager](https://github.com/vectorize-io/hindsight/blob/main/hindsight-api-slim/hindsight_api/webhooks/manager.py): `hindsight-api-slim/hindsight_api/webhooks/manager.py`

### Other components

- **Agent or user**
- **LLM service**
- **Webhook endpoint**

## Connections

- Agent or user → Client SDKs: uses
- Agent or user → Command-line client: uses
- Client SDKs → HTTP API: HTTP requests
- Command-line client → HTTP API: HTTP requests
- API server → HTTP API: mounts
- HTTP API → Memory engine: dispatches
- MCP API → Memory engine: dispatches
- Memory engine → Memory banks: manages
- Memory engine → Retain orchestration: retains
- Memory engine → Recall retrieval: recalls
- Memory engine → Reflect agent: reflects
- Retain orchestration → Chunk storage: stores chunks
- Retain orchestration → Fact storage: stores facts
- Fact storage → Memory database: writes facts
- Chunk storage → Memory database: writes chunks
- Consolidation → Memory database: updates memories
- Recall retrieval → Query analysis: analyzes query
- Recall retrieval → Memory database: retrieves memories
- Reflect agent → Recall retrieval: uses retrieval
- Reflect agent → LLM providers: requests generation
- LLM providers → LLM service: calls model
- Mental models → LLM providers: requests generation
- Knowledge pages → Memory engine: serves page APIs
- Import and export → Memory database: imports or exports
- Memory engine → Operation tasks: submits operations
- Operation worker → Operation tasks: processes tasks
- Webhook manager → Memory database: reads registrations
- Webhook manager → Operation tasks: queues delivery
- Webhook endpoint → Webhook manager: receives events