# dami904/lethe architecture

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

- Interactive diagram: https://gitdiagram.com/dami904/lethe
- Repository: https://github.com/dami904/lethe

## Overview

Lethe stores timestamped facts as HydraDB graph nodes, marks contradictory updates with SUPERSEDES edges, and answers time-bounded recall by graph query rather than similarity alone. Its principal workflow is fact ingestion and conflict handling followed by recall; graph-chain and connectivity queries support exploration, while a vector baseline provides comparison. Optional LLM extraction and conflict classification are documented capabilities. The static demo exercises recall, chain, and connect; source excerpts for several route implementations were not provided, so uncertain internal wiring is omitted.

Main entry points: [`src/server.ts`](https://github.com/dami904/lethe/blob/main/src/server.ts) (Express server), [`public/app.js`](https://github.com/dami904/lethe/blob/main/public/app.js) (Demo browser), [`src/db/graph.ts`](https://github.com/dami904/lethe/blob/main/src/db/graph.ts) (Graph operations), [`src/routes/facts.ts`](https://github.com/dami904/lethe/blob/main/src/routes/facts.ts) (Fact ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and demo"]
  node_server["Express server<br/>[server.ts]"]
  node_facts["Fact ingestion<br/>[facts.ts]"]
  node_recall["Temporal recall<br/>[recall.ts]"]
  node_chain["Supersession chain<br/>[chain.ts]"]
  node_connect["Graph connectivity<br/>[connect.ts]"]
  node_demo["Demo scenarios<br/>[demo.ts]"]
end

subgraph group_memory["Fact memory"]
  node_extract["Fact extraction<br/>[extractFacts.ts]"]
  node_classifier["Conflict classifier"]
end

subgraph group_graph["Graph storage"]
  node_graphops["Graph operations<br/>[graph.ts]"]
  node_hydra["HydraDB client<br/>[hydraClient.ts]"]
end

subgraph group_comparison["Baseline comparison"]
  node_baseline["Baseline API<br/>[baseline.ts]"]
  node_vector["Vector memory<br/>[vectorMemory.ts]"]
  node_embeddings["Text embeddings<br/>[embeddings.ts]"]
end

node_user(("Agent or user"))
node_browser["Demo browser<br/>[app.js]"]
node_llm{{"LLM provider"}}
node_hydradb[("HydraDB")]

node_user -->|"submits requests"| node_server
node_server -->|"mounts route"| node_facts
node_server -->|"mounts route"| node_recall
node_server -->|"mounts route"| node_chain
node_server -->|"mounts route"| node_connect
node_server -->|"mounts route"| node_demo
node_server -->|"mounts route"| node_baseline
node_server -->|"serves static app"| node_browser
node_browser -->|"loads scenarios"| node_demo
node_browser -->|"requests chain"| node_chain
node_browser -->|"requests recall"| node_recall
node_browser -->|"requests paths"| node_connect
node_facts -->|"classifies updates"| node_classifier
node_classifier -.->|"requests classification"| node_llm
node_facts -->|"writes facts and edges"| node_graphops
node_recall -->|"queries facts"| node_graphops
node_chain -->|"traverses chain"| node_graphops
node_connect -->|"finds paths"| node_graphops
node_graphops -->|"runs graph queries"| node_hydra
node_hydra -->|"queries HTTP API"| node_hydradb
node_baseline -->|"searches memory"| node_vector
node_vector -->|"embeds text"| node_embeddings
node_extract -.->|"extracts fact triples"| node_llm

click node_server "https://github.com/dami904/lethe/blob/main/src/server.ts"
click node_facts "https://github.com/dami904/lethe/blob/main/src/routes/facts.ts"
click node_recall "https://github.com/dami904/lethe/blob/main/src/routes/recall.ts"
click node_chain "https://github.com/dami904/lethe/blob/main/src/routes/chain.ts"
click node_connect "https://github.com/dami904/lethe/blob/main/src/routes/connect.ts"
click node_demo "https://github.com/dami904/lethe/blob/main/src/routes/demo.ts"
click node_browser "https://github.com/dami904/lethe/blob/main/public/app.js"
click node_extract "https://github.com/dami904/lethe/blob/main/src/ingest/extractFacts.ts"
click node_classifier "https://github.com/dami904/lethe/blob/main/src/lib/conflictClassifier.ts"
click node_graphops "https://github.com/dami904/lethe/blob/main/src/db/graph.ts"
click node_hydra "https://github.com/dami904/lethe/blob/main/src/db/hydraClient.ts"
click node_baseline "https://github.com/dami904/lethe/blob/main/src/routes/baseline.ts"
click node_vector "https://github.com/dami904/lethe/blob/main/src/baseline/vectorMemory.ts"
click node_embeddings "https://github.com/dami904/lethe/blob/main/src/baseline/embeddings.ts"

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_server,node_facts,node_recall,node_chain,node_connect,node_demo,node_user,node_browser toneBlue
class node_extract,node_classifier,node_hydradb toneAmber
class node_graphops,node_hydra toneMint
class node_baseline,node_vector,node_embeddings toneRose
class node_llm toneIndigo
```

## Components

### API and demo

- [Express server](https://github.com/dami904/lethe/blob/main/src/server.ts): `src/server.ts`
- [Fact ingestion](https://github.com/dami904/lethe/blob/main/src/routes/facts.ts): `src/routes/facts.ts`
- [Temporal recall](https://github.com/dami904/lethe/blob/main/src/routes/recall.ts): `src/routes/recall.ts`
- [Supersession chain](https://github.com/dami904/lethe/blob/main/src/routes/chain.ts): `src/routes/chain.ts`
- [Graph connectivity](https://github.com/dami904/lethe/blob/main/src/routes/connect.ts): `src/routes/connect.ts`
- [Demo scenarios](https://github.com/dami904/lethe/blob/main/src/routes/demo.ts): `src/routes/demo.ts`

### Fact memory

- [Fact extraction](https://github.com/dami904/lethe/blob/main/src/ingest/extractFacts.ts): `src/ingest/extractFacts.ts`
- [Conflict classifier](https://github.com/dami904/lethe/blob/main/src/lib/conflictClassifier.ts): `src/lib/conflictClassifier.ts`

### Graph storage

- [Graph operations](https://github.com/dami904/lethe/blob/main/src/db/graph.ts): `src/db/graph.ts`
- [HydraDB client](https://github.com/dami904/lethe/blob/main/src/db/hydraClient.ts): `src/db/hydraClient.ts`

### Baseline comparison

- [Baseline API](https://github.com/dami904/lethe/blob/main/src/routes/baseline.ts): `src/routes/baseline.ts`
- [Vector memory](https://github.com/dami904/lethe/blob/main/src/baseline/vectorMemory.ts): `src/baseline/vectorMemory.ts`
- [Text embeddings](https://github.com/dami904/lethe/blob/main/src/baseline/embeddings.ts): `src/baseline/embeddings.ts`

### Other components

- **Agent or user**
- [Demo browser](https://github.com/dami904/lethe/blob/main/public/app.js): `public/app.js`
- **LLM provider**
- **HydraDB**

## Connections

- Agent or user → Express server: submits requests
- Express server → Fact ingestion: mounts route
- Express server → Temporal recall: mounts route
- Express server → Supersession chain: mounts route
- Express server → Graph connectivity: mounts route
- Express server → Demo scenarios: mounts route
- Express server → Baseline API: mounts route
- Express server → Demo browser: serves static app
- Demo browser → Demo scenarios: loads scenarios
- Demo browser → Supersession chain: requests chain
- Demo browser → Temporal recall: requests recall
- Demo browser → Graph connectivity: requests paths
- Fact ingestion → Conflict classifier: classifies updates
- Conflict classifier → LLM provider: requests classification
- Fact ingestion → Graph operations: writes facts and edges
- Temporal recall → Graph operations: queries facts
- Supersession chain → Graph operations: traverses chain
- Graph connectivity → Graph operations: finds paths
- Graph operations → HydraDB client: runs graph queries
- HydraDB client → HydraDB: queries HTTP API
- Baseline API → Vector memory: searches memory
- Vector memory → Text embeddings: embeds text
- Fact extraction → LLM provider: extracts fact triples