# plishh/hipporag architecture

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

- Interactive diagram: https://gitdiagram.com/plishh/hipporag
- Repository: https://github.com/plishh/hipporag

## Overview

HippoRAG 2 is an LLM memory and retrieval framework. The principal workflow accepts documents for indexing, extracts entities and relations, builds searchable memory, then answers queries using retrieval and generation; the README Quick Start documents the index-to-QA flow. The graph includes documented evaluation and model-provider capabilities. Several source files were not sampled, so unsourced implementation links are omitted; dashed links mark documented optional endpoint integrations.

Main entry points: [`src/hipporag/HippoRAG.py`](https://github.com/plishh/hipporag/blob/main/src/hipporag/HippoRAG.py) (HippoRAG controller), [`src/hipporag/embedding_store.py`](https://github.com/plishh/hipporag/blob/main/src/hipporag/embedding_store.py) (Embedding store), [`src/hipporag/llm/base.py`](https://github.com/plishh/hipporag/blob/main/src/hipporag/llm/base.py) (LLM interface), [`src/hipporag/llm/gateway_llm.py`](https://github.com/plishh/hipporag/blob/main/src/hipporag/llm/gateway_llm.py) (Gateway LLM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Memory workflow"]
  node_hipporag["HippoRAG controller<br/>[HippoRAG.py]"]
  node_standardrag["Standard RAG<br/>[StandardRAG.py]"]
  node_preprocess["Text preprocessing<br/>[preprocessing.py]"]
  node_openie["OpenIE extraction<br/>[openie_openai.py]"]
  node_offlineopenie["Offline OpenIE"]
  node_rerank["Retrieval reranking<br/>[rerank.py]"]
end

subgraph group_models["Model integrations"]
  node_embedding["Embedding interface<br/>[base.py]"]
  node_openaiembed["OpenAI embeddings<br/>[OpenAI.py]"]
  node_llmbase["LLM interface<br/>[base.py]"]
  node_openai["OpenAI LLM<br/>[openai_gpt.py]"]
  node_gateway["Gateway LLM<br/>[gateway_llm.py]"]
end

subgraph group_storage["Index storage"]
  node_embedstore[("Embedding store<br/>[embedding_store.py]")]
  node_chromastore[("Chroma backend<br/>[chroma_store.py]")]
  node_milvus[("Milvus backend<br/>[milvus_store.py]")]
  node_qdrant[("Qdrant backend<br/>[qdrant_store.py]")]
  node_state[("Index state and identity<br/>[state_utils.py]")]
end

subgraph group_prompts["Prompts and evaluation"]
  node_promptmanager["Prompt templates"]
  node_linking["Entity linking prompts<br/>[linking.py]"]
  node_retrievaleval["Retrieval evaluation<br/>[retrieval_eval.py]"]
  node_qaeval["QA evaluation<br/>[qa_eval.py]"]
end

node_user(("Application user"))
node_llmgateway{{"OpenAI-compatible endpoint"}}

node_user -->|"indexes and queries"| node_hipporag
node_user -->|"runs RAG"| node_standardrag
node_hipporag -->|"extracts facts"| node_openie
node_hipporag -->|"stores embeddings"| node_embedstore
node_hipporag -->|"preprocesses text"| node_preprocess
node_hipporag -->|"reranks results"| node_rerank
node_hipporag -->|"validates index state"| node_state
node_hipporag -->|"evaluates retrieval"| node_retrievaleval
node_hipporag -->|"evaluates answers"| node_qaeval
node_openie -->|"renders prompts"| node_promptmanager
node_offlineopenie -->|"uses offline LLM"| node_llmbase
node_embedding -->|"implements interface"| node_openaiembed
node_embedstore -->|"uses backend"| node_chromastore
node_embedstore -->|"uses backend"| node_milvus
node_embedstore -->|"uses backend"| node_qdrant
node_gateway -->|"implements interface"| node_llmbase
node_gateway -.->|"sends requests"| node_llmgateway
node_openai -->|"implements interface"| node_llmbase
node_openaiembed -.->|"supports compatible endpoint"| node_llmgateway
node_promptmanager -.->|"uses linking prompts"| node_linking

click node_hipporag "https://github.com/plishh/hipporag/blob/main/src/hipporag/HippoRAG.py"
click node_standardrag "https://github.com/plishh/hipporag/blob/main/src/hipporag/StandardRAG.py"
click node_preprocess "https://github.com/plishh/hipporag/blob/main/src/hipporag/preprocessing.py"
click node_openie "https://github.com/plishh/hipporag/blob/main/src/hipporag/information_extraction/openie_openai.py"
click node_offlineopenie "https://github.com/plishh/hipporag/blob/main/src/hipporag/information_extraction/openie_vllm_offline.py"
click node_rerank "https://github.com/plishh/hipporag/blob/main/src/hipporag/rerank.py"
click node_embedding "https://github.com/plishh/hipporag/blob/main/src/hipporag/embedding_model/base.py"
click node_openaiembed "https://github.com/plishh/hipporag/blob/main/src/hipporag/embedding_model/OpenAI.py"
click node_llmbase "https://github.com/plishh/hipporag/blob/main/src/hipporag/llm/base.py"
click node_openai "https://github.com/plishh/hipporag/blob/main/src/hipporag/llm/openai_gpt.py"
click node_gateway "https://github.com/plishh/hipporag/blob/main/src/hipporag/llm/gateway_llm.py"
click node_embedstore "https://github.com/plishh/hipporag/blob/main/src/hipporag/embedding_store.py"
click node_chromastore "https://github.com/plishh/hipporag/blob/main/src/hipporag/vector_stores/chroma_store.py"
click node_milvus "https://github.com/plishh/hipporag/blob/main/src/hipporag/vector_stores/milvus_store.py"
click node_qdrant "https://github.com/plishh/hipporag/blob/main/src/hipporag/vector_stores/qdrant_store.py"
click node_state "https://github.com/plishh/hipporag/blob/main/src/hipporag/utils/state_utils.py"
click node_promptmanager "https://github.com/plishh/hipporag/blob/main/src/hipporag/prompts/prompt_template_manager.py"
click node_linking "https://github.com/plishh/hipporag/blob/main/src/hipporag/prompts/linking.py"
click node_retrievaleval "https://github.com/plishh/hipporag/blob/main/src/hipporag/evaluation/retrieval_eval.py"
click node_qaeval "https://github.com/plishh/hipporag/blob/main/src/hipporag/evaluation/qa_eval.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_hipporag,node_standardrag,node_preprocess,node_openie,node_offlineopenie,node_rerank,node_user toneBlue
class node_embedding,node_openaiembed,node_llmbase,node_openai,node_gateway toneAmber
class node_embedstore,node_chromastore,node_milvus,node_qdrant,node_state toneMint
class node_promptmanager,node_linking,node_retrievaleval,node_qaeval toneRose
class node_llmgateway toneIndigo
```

## Components

### Memory workflow

- [HippoRAG controller](https://github.com/plishh/hipporag/blob/main/src/hipporag/HippoRAG.py): `src/hipporag/HippoRAG.py`
- [Standard RAG](https://github.com/plishh/hipporag/blob/main/src/hipporag/StandardRAG.py): `src/hipporag/StandardRAG.py`
- [Text preprocessing](https://github.com/plishh/hipporag/blob/main/src/hipporag/preprocessing.py): `src/hipporag/preprocessing.py`
- [OpenIE extraction](https://github.com/plishh/hipporag/blob/main/src/hipporag/information_extraction/openie_openai.py): `src/hipporag/information_extraction/openie_openai.py`
- [Offline OpenIE](https://github.com/plishh/hipporag/blob/main/src/hipporag/information_extraction/openie_vllm_offline.py): `src/hipporag/information_extraction/openie_vllm_offline.py`
- [Retrieval reranking](https://github.com/plishh/hipporag/blob/main/src/hipporag/rerank.py): `src/hipporag/rerank.py`

### Model integrations

- [Embedding interface](https://github.com/plishh/hipporag/blob/main/src/hipporag/embedding_model/base.py): `src/hipporag/embedding_model/base.py`
- [OpenAI embeddings](https://github.com/plishh/hipporag/blob/main/src/hipporag/embedding_model/OpenAI.py): `src/hipporag/embedding_model/OpenAI.py`
- [LLM interface](https://github.com/plishh/hipporag/blob/main/src/hipporag/llm/base.py): `src/hipporag/llm/base.py`
- [OpenAI LLM](https://github.com/plishh/hipporag/blob/main/src/hipporag/llm/openai_gpt.py): `src/hipporag/llm/openai_gpt.py`
- [Gateway LLM](https://github.com/plishh/hipporag/blob/main/src/hipporag/llm/gateway_llm.py): `src/hipporag/llm/gateway_llm.py`

### Index storage

- [Embedding store](https://github.com/plishh/hipporag/blob/main/src/hipporag/embedding_store.py): `src/hipporag/embedding_store.py`
- [Chroma backend](https://github.com/plishh/hipporag/blob/main/src/hipporag/vector_stores/chroma_store.py): `src/hipporag/vector_stores/chroma_store.py`
- [Milvus backend](https://github.com/plishh/hipporag/blob/main/src/hipporag/vector_stores/milvus_store.py): `src/hipporag/vector_stores/milvus_store.py`
- [Qdrant backend](https://github.com/plishh/hipporag/blob/main/src/hipporag/vector_stores/qdrant_store.py): `src/hipporag/vector_stores/qdrant_store.py`
- [Index state and identity](https://github.com/plishh/hipporag/blob/main/src/hipporag/utils/state_utils.py): `src/hipporag/utils/state_utils.py`

### Prompts and evaluation

- [Prompt templates](https://github.com/plishh/hipporag/blob/main/src/hipporag/prompts/prompt_template_manager.py): `src/hipporag/prompts/prompt_template_manager.py`
- [Entity linking prompts](https://github.com/plishh/hipporag/blob/main/src/hipporag/prompts/linking.py): `src/hipporag/prompts/linking.py`
- [Retrieval evaluation](https://github.com/plishh/hipporag/blob/main/src/hipporag/evaluation/retrieval_eval.py): `src/hipporag/evaluation/retrieval_eval.py`
- [QA evaluation](https://github.com/plishh/hipporag/blob/main/src/hipporag/evaluation/qa_eval.py): `src/hipporag/evaluation/qa_eval.py`

### Other components

- **Application user**
- **OpenAI-compatible endpoint**

## Connections

- Application user → HippoRAG controller: indexes and queries
- Application user → Standard RAG: runs RAG (evidence: `src/hipporag/StandardRAG.py`)
- HippoRAG controller → OpenIE extraction: extracts facts (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG controller → Embedding store: stores embeddings (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG controller → Text preprocessing: preprocesses text (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG controller → Retrieval reranking: reranks results (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG controller → Index state and identity: validates index state (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG controller → Retrieval evaluation: evaluates retrieval (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG controller → QA evaluation: evaluates answers (evidence: `src/hipporag/HippoRAG.py`)
- OpenIE extraction → Prompt templates: renders prompts (evidence: `src/hipporag/information_extraction/openie_openai.py`)
- Offline OpenIE → LLM interface: uses offline LLM (evidence: `src/hipporag/information_extraction/openie_vllm_offline.py`)
- Embedding interface → OpenAI embeddings: implements interface
- Embedding store → Chroma backend: uses backend (evidence: `src/hipporag/embedding_store.py`)
- Embedding store → Milvus backend: uses backend (evidence: `src/hipporag/embedding_store.py`)
- Embedding store → Qdrant backend: uses backend (evidence: `src/hipporag/embedding_store.py`)
- Gateway LLM → LLM interface: implements interface (evidence: `src/hipporag/llm/gateway_llm.py`)
- Gateway LLM → OpenAI-compatible endpoint: sends requests
- OpenAI LLM → LLM interface: implements interface (evidence: `src/hipporag/llm/openai_gpt.py`)
- OpenAI embeddings → OpenAI-compatible endpoint: supports compatible endpoint
- Prompt templates → Entity linking prompts: uses linking prompts
