# varshith4611c/hindsight architecture

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

- Interactive diagram: https://gitdiagram.com/varshith4611c/hindsight
- Repository: https://github.com/varshith4611c/hindsight

## Overview

Hindsight is a long-term memory system for AI agents, exposing retain, recall, and reflect operations through an API and client libraries. The documented main workflow sends agent information to retain, searches it with recall, and generates disposition-aware responses with reflect. Internally, retention extracts facts and persists memory; recall retrieves relevant memories; reflection builds on memory for a response. The README also documents banks, knowledge pages, mental models, integrations, and multiple LLM providers. Several subsystem links are documented rather than verified from sampled implementation, so those edges are marked dashed.

Main entry points: [`hindsight-api-slim/hindsight_api/api/http.py`](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/http.py) (HTTP API), [`hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py`](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py) (Retain Orchestrator), [`hindsight-api-slim/hindsight_api/engine/memories/pg/writes.py`](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memories/pg/writes.py) (Memory Store), [`hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py`](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py) (Fact & Chunk Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent Interfaces"]
  node_clients["Client Libraries"]
  node_integrations["Agent Integrations"]
  node_cli["CLI<br/>[main.rs]"]
end

subgraph group_api["API Operations"]
  node_api_service["HTTP API<br/>[http.py]"]
  node_banks["Memory Banks<br/>[models.py]"]
  node_webhooks["Webhooks<br/>[manager.py]"]
end

subgraph group_memory["Memory Engine"]
  node_retain["Retain Orchestrator<br/>[orchestrator.py]"]
  node_fact_extract["Fact Extraction<br/>[fact_extraction.py]"]
  node_fact_store["Fact &amp; Chunk Storage<br/>[fact_storage.py]"]
  node_recall["Recall Retrieval<br/>[retrieval.py]"]
  node_reflect["Reflect Agent<br/>[agent.py]"]
  node_mental_models["Mental Models"]
  node_knowledge["Knowledge Pages<br/>[importer.py]"]
  node_memory_engine["Memory Engine<br/>[memory_engine.py]"]
  node_graph["Graph Maintenance"]
end

subgraph group_platform["Persistence &amp; Providers"]
  node_store[("Memory Store<br/>[writes.py]")]
  node_database[("Database Access<br/>[base.py]")]
  node_llm["LLM Providers<br/>[llm_wrapper.py]"]
end

node_agent(("AI Agent"))

node_agent -->|"uses"| node_clients
node_agent -.->|"connects through"| node_integrations
node_agent -.->|"operates via"| node_cli
node_clients -->|"calls API"| node_api_service
node_cli -.->|"calls API"| node_api_service
node_api_service -.->|"dispatches retain"| node_retain
node_api_service -.->|"dispatches recall"| node_recall
node_api_service -.->|"dispatches reflect"| node_reflect
node_api_service -.->|"manages banks"| node_banks
node_api_service -.->|"serves models"| node_mental_models
node_api_service -.->|"serves pages"| node_knowledge
node_retain -.->|"extracts facts"| node_fact_extract
node_retain -.->|"stores content"| node_fact_store
node_fact_store -->|"inserts facts"| node_store
node_fact_store -->|"queues relinking"| node_graph
node_recall -.->|"retrieves memories"| node_store
node_reflect -.->|"uses recall"| node_recall
node_retain -.->|"requests extraction"| node_llm
node_reflect -.->|"generates response"| node_llm
node_memory_engine -.->|"coordinates storage"| node_store
node_store -.->|"reads and writes"| node_database
node_webhooks -->|"stores deliveries"| node_database

click node_clients "https://github.com/varshith4611c/hindsight/blob/main/hindsight-clients/python/hindsight_client/hindsight_client.py"
click node_integrations "https://github.com/varshith4611c/hindsight/tree/main/hindsight-integrations"
click node_cli "https://github.com/varshith4611c/hindsight/blob/main/hindsight-cli/src/main.rs"
click node_api_service "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/http.py"
click node_banks "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/models.py"
click node_retain "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py"
click node_fact_extract "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/fact_extraction.py"
click node_fact_store "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py"
click node_recall "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/search/retrieval.py"
click node_reflect "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/reflect/agent.py"
click node_mental_models "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/mental_model_refresh.py"
click node_knowledge "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/transfer/importer.py"
click node_memory_engine "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memory_engine.py"
click node_graph "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/graph_maintenance.py"
click node_store "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memories/pg/writes.py"
click node_database "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/db/base.py"
click node_llm "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/llm_wrapper.py"
click node_webhooks "https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/webhooks/manager.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_integrations,node_cli toneBlue
class node_api_service,node_banks,node_webhooks toneAmber
class node_retain,node_fact_extract,node_fact_store,node_recall,node_reflect,node_mental_models,node_knowledge,node_memory_engine,node_graph toneMint
class node_store,node_database,node_llm toneRose
class node_agent toneIndigo
```

## Components

### Agent Interfaces

- [Client Libraries](https://github.com/varshith4611c/hindsight/blob/main/hindsight-clients/python/hindsight_client/hindsight_client.py): `hindsight-clients/python/hindsight_client/hindsight_client.py`
- [Agent Integrations](https://github.com/varshith4611c/hindsight/tree/main/hindsight-integrations): `hindsight-integrations`
- [CLI](https://github.com/varshith4611c/hindsight/blob/main/hindsight-cli/src/main.rs): `hindsight-cli/src/main.rs`

### API Operations

- [HTTP API](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/http.py): `hindsight-api-slim/hindsight_api/api/http.py`
- [Memory Banks](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/models.py): `hindsight-api-slim/hindsight_api/models.py`
- [Webhooks](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/webhooks/manager.py): `hindsight-api-slim/hindsight_api/webhooks/manager.py`

### Memory Engine

- [Retain Orchestrator](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py): `hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py`
- [Fact Extraction](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/fact_extraction.py): `hindsight-api-slim/hindsight_api/engine/retain/fact_extraction.py`
- [Fact & Chunk Storage](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py): `hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py`
- [Recall Retrieval](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/search/retrieval.py): `hindsight-api-slim/hindsight_api/engine/search/retrieval.py`
- [Reflect Agent](https://github.com/varshith4611c/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/varshith4611c/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/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/transfer/importer.py): `hindsight-api-slim/hindsight_api/engine/transfer/importer.py`
- [Memory Engine](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memory_engine.py): `hindsight-api-slim/hindsight_api/engine/memory_engine.py`
- [Graph Maintenance](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/graph_maintenance.py): `hindsight-api-slim/hindsight_api/engine/graph_maintenance.py`

### Persistence & Providers

- [Memory Store](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memories/pg/writes.py): `hindsight-api-slim/hindsight_api/engine/memories/pg/writes.py`
- [Database Access](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/db/base.py): `hindsight-api-slim/hindsight_api/engine/db/base.py`
- [LLM Providers](https://github.com/varshith4611c/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/llm_wrapper.py): `hindsight-api-slim/hindsight_api/engine/llm_wrapper.py`

### Other components

- **AI Agent**

## Connections

- AI Agent → Client Libraries: uses (evidence: `README.md`)
- AI Agent → Agent Integrations: connects through (evidence: `README.md`)
- AI Agent → CLI: operates via (evidence: `README.md`)
- Client Libraries → HTTP API: calls API (evidence: `README.md`)
- CLI → HTTP API: calls API (evidence: `hindsight-cli/src/main.rs`)
- HTTP API → Retain Orchestrator: dispatches retain
- HTTP API → Recall Retrieval: dispatches recall
- HTTP API → Reflect Agent: dispatches reflect
- HTTP API → Memory Banks: manages banks (evidence: `README.md`)
- HTTP API → Mental Models: serves models (evidence: `README.md`)
- HTTP API → Knowledge Pages: serves pages (evidence: `README.md`)
- Retain Orchestrator → Fact Extraction: extracts facts
- Retain Orchestrator → Fact & Chunk Storage: stores content
- Fact & Chunk Storage → Memory Store: inserts facts (evidence: `hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py`)
- Fact & Chunk Storage → Graph Maintenance: queues relinking (evidence: `hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py`)
- Recall Retrieval → Memory Store: retrieves memories
- Reflect Agent → Recall Retrieval: uses recall (evidence: `README.md`)
- Retain Orchestrator → LLM Providers: requests extraction
- Reflect Agent → LLM Providers: generates response
- Memory Engine → Memory Store: coordinates storage
- Memory Store → Database Access: reads and writes
- Webhooks → Database Access: stores deliveries (evidence: `hindsight-api-slim/hindsight_api/webhooks/manager.py`)
