# yogeswar142/hindsight architecture

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

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

## Overview

Hindsight is an agent-memory system: clients and agents submit information to retain, search it with recall, or generate responses with reflect. The API server exposes these operations, while the engine handles memory processing, search, and persistence. The README also documents memory banks, mental models, knowledge pages, MCP, and multiple client and deployment options; these appear as product branches, though their internal wiring is not established by the sampled excerpts. The graph uses documented workflows and repository structure; some subsystem links are therefore intentionally omitted.

Main entry points: [`hindsight-api-slim/hindsight_api/main.py`](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/main.py) (API server), [`hindsight-api-slim/hindsight_api/engine/memory_engine.py`](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memory_engine.py) (Memory engine), [`hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py`](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py) (Retain processing), [`hindsight-api-slim/hindsight_api/engine/search/retrieval.py`](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/search/retrieval.py) (Recall search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and serving"]
  node_clients["Client SDKs<br/>[client.go]"]
  node_cli["Command-line client<br/>[main.rs]"]
  node_crew["CrewAI storage<br/>[storage.py]"]
  node_server["API server<br/>[main.py]"]
  node_http["HTTP and MCP APIs<br/>[http.py]"]
  node_mcp["MCP tools<br/>[mcp_tools.py]"]
end

subgraph group_memory["Memory operations"]
  node_engine["Memory engine<br/>[memory_engine.py]"]
  node_retain["Retain processing<br/>[orchestrator.py]"]
  node_recall["Recall search<br/>[retrieval.py]"]
  node_reflect["Reflect responses<br/>[agent.py]"]
  node_consolidate["Memory consolidation<br/>[consolidator.py]"]
end

subgraph group_knowledge["Knowledge features"]
  node_banks["Memory banks<br/>[bank_aliases.py]"]
  node_mental["Mental models"]
  node_pages["Knowledge pages"]
  node_transfer["Import and export<br/>[importer.py]"]
end

subgraph group_infrastructure["Storage and integrations"]
  node_database[("Memory database<br/>[postgresql.py]")]
  node_providers["LLM providers"]
  node_webhooks["Webhook delivery<br/>[manager.py]"]
  node_embed["Embedded daemon"]
end

node_agent(("Agent or user"))
node_llmservice(("LLM service"))
node_webhooktarget(("Webhook receiver"))

node_agent -->|"uses"| node_clients
node_agent -->|"uses"| node_cli
node_agent -->|"integrates"| node_crew
node_clients -->|"HTTP requests"| node_server
node_cli -->|"API requests"| node_server
node_crew -->|"retain and recall"| node_server
node_server -->|"creates API"| node_http
node_http -->|"memory operations"| node_engine
node_mcp -->|"agent tools"| node_engine
node_engine -->|"retains content"| node_retain
node_engine -->|"searches memories"| node_recall
node_engine -->|"generates responses"| node_reflect
node_retain -->|"consolidates memories"| node_consolidate
node_retain -->|"stores memory data"| node_database
node_recall -->|"queries memory data"| node_database
node_reflect -->|"retrieves context"| node_recall
node_engine -->|"requests model work"| node_providers
node_providers -.->|"calls model"| node_llmservice
node_server -->|"supports bank operations"| node_banks
node_server -->|"supports refresh"| node_mental
node_server -->|"supports knowledge pages"| node_pages
node_server -->|"supports transfers"| node_transfer
node_webhooks -->|"loads dispatch config"| node_database
node_webhooks -->|"delivers events"| node_webhooktarget
node_embed -->|"starts daemon"| node_server

click node_clients "https://github.com/yogeswar142/hindsight/blob/main/hindsight-clients/go/client.go"
click node_cli "https://github.com/yogeswar142/hindsight/blob/main/hindsight-cli/src/main.rs"
click node_crew "https://github.com/yogeswar142/hindsight/blob/main/hindsight-integrations/crewai/hindsight_crewai/storage.py"
click node_server "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/main.py"
click node_http "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/http.py"
click node_mcp "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/mcp_tools.py"
click node_engine "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memory_engine.py"
click node_retain "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py"
click node_recall "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/search/retrieval.py"
click node_reflect "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/reflect/agent.py"
click node_consolidate "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py"
click node_banks "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/bank_aliases.py"
click node_mental "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/mental_model_refresh.py"
click node_pages "https://github.com/yogeswar142/hindsight/tree/main/hindsight-api-slim/hindsight_api"
click node_transfer "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/transfer/importer.py"
click node_database "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/db/postgresql.py"
click node_providers "https://github.com/yogeswar142/hindsight/tree/main/hindsight-api-slim/hindsight_api/engine/providers"
click node_webhooks "https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/webhooks/manager.py"
click node_embed "https://github.com/yogeswar142/hindsight/blob/main/hindsight-embed/hindsight_embed/daemon_embed_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_cli,node_crew,node_server,node_http,node_mcp,node_agent toneBlue
class node_engine,node_retain,node_recall,node_reflect,node_consolidate toneAmber
class node_banks,node_mental,node_pages,node_transfer,node_webhooktarget toneMint
class node_database,node_providers,node_webhooks,node_embed toneRose
class node_llmservice toneIndigo
```

## Components

### Access and serving

- [Client SDKs](https://github.com/yogeswar142/hindsight/blob/main/hindsight-clients/go/client.go): `hindsight-clients/go/client.go`
- [Command-line client](https://github.com/yogeswar142/hindsight/blob/main/hindsight-cli/src/main.rs): `hindsight-cli/src/main.rs`
- [CrewAI storage](https://github.com/yogeswar142/hindsight/blob/main/hindsight-integrations/crewai/hindsight_crewai/storage.py): `hindsight-integrations/crewai/hindsight_crewai/storage.py`
- [API server](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/main.py): `hindsight-api-slim/hindsight_api/main.py`
- [HTTP and MCP APIs](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/api/http.py): `hindsight-api-slim/hindsight_api/api/http.py`
- [MCP tools](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/mcp_tools.py): `hindsight-api-slim/hindsight_api/mcp_tools.py`

### Memory operations

- [Memory engine](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/memory_engine.py): `hindsight-api-slim/hindsight_api/engine/memory_engine.py`
- [Retain processing](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py): `hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py`
- [Recall search](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/search/retrieval.py): `hindsight-api-slim/hindsight_api/engine/search/retrieval.py`
- [Reflect responses](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/reflect/agent.py): `hindsight-api-slim/hindsight_api/engine/reflect/agent.py`
- [Memory consolidation](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py): `hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py`

### Knowledge features

- [Memory banks](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/bank_aliases.py): `hindsight-api-slim/hindsight_api/engine/bank_aliases.py`
- [Mental models](https://github.com/yogeswar142/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/yogeswar142/hindsight/tree/main/hindsight-api-slim/hindsight_api): `hindsight-api-slim/hindsight_api`
- [Import and export](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/transfer/importer.py): `hindsight-api-slim/hindsight_api/engine/transfer/importer.py`

### Storage and integrations

- [Memory database](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/engine/db/postgresql.py): `hindsight-api-slim/hindsight_api/engine/db/postgresql.py`
- [LLM providers](https://github.com/yogeswar142/hindsight/tree/main/hindsight-api-slim/hindsight_api/engine/providers): `hindsight-api-slim/hindsight_api/engine/providers`
- [Webhook delivery](https://github.com/yogeswar142/hindsight/blob/main/hindsight-api-slim/hindsight_api/webhooks/manager.py): `hindsight-api-slim/hindsight_api/webhooks/manager.py`
- [Embedded daemon](https://github.com/yogeswar142/hindsight/blob/main/hindsight-embed/hindsight_embed/daemon_embed_manager.py): `hindsight-embed/hindsight_embed/daemon_embed_manager.py`

### Other components

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

## Connections

- Agent or user → Client SDKs: uses
- Agent or user → Command-line client: uses
- Agent or user → CrewAI storage: integrates
- Client SDKs → API server: HTTP requests
- Command-line client → API server: API requests
- CrewAI storage → API server: retain and recall
- API server → HTTP and MCP APIs: creates API
- HTTP and MCP APIs → Memory engine: memory operations
- MCP tools → Memory engine: agent tools
- Memory engine → Retain processing: retains content
- Memory engine → Recall search: searches memories
- Memory engine → Reflect responses: generates responses
- Retain processing → Memory consolidation: consolidates memories
- Retain processing → Memory database: stores memory data
- Recall search → Memory database: queries memory data
- Reflect responses → Recall search: retrieves context
- Memory engine → LLM providers: requests model work
- LLM providers → LLM service: calls model
- API server → Memory banks: supports bank operations
- API server → Mental models: supports refresh
- API server → Knowledge pages: supports knowledge pages
- API server → Import and export: supports transfers
- Webhook delivery → Memory database: loads dispatch config
- Webhook delivery → Webhook receiver: delivers events
- Embedded daemon → API server: starts daemon