# osu-nlp-group/hipporag architecture

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

- Interactive diagram: https://gitdiagram.com/osu-nlp-group/hipporag
- Repository: https://github.com/osu-nlp-group/hipporag

## Overview

HippoRAG 2 is a persistent memory and retrieval-augmented generation framework. The principal workflow is to index documents, then answer queries using retrieval over the resulting memory; the README demonstrates `index(docs)` followed by `rag_qa(queries)`. The graph also preserves the documented standard-RAG, model-provider, storage, evaluation, and MCP capabilities. Some subsystem links are based on SOURCE INDEX references rather than inspected call sites, so those links are marked dashed with no evidence path.

Main entry points: [`src/hipporag/HippoRAG.py`](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/HippoRAG.py) (HippoRAG engine), [`src/hipporag/llm/base.py`](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/llm/base.py) (LLM interface), [`src/hipporag/information_extraction/openie_openai.py`](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/information_extraction/openie_openai.py) (OpenIE extraction), [`src/hipporag/embedding_store.py`](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/embedding_store.py) (Embedding store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_memory["Memory indexing"]
  node_hipporag["HippoRAG engine<br/>[HippoRAG.py]"]
  node_preprocessing["Text preprocessing<br/>[preprocessing.py]"]
  node_openie["OpenIE extraction<br/>[openie_openai.py]"]
  node_offline_openie["Offline OpenIE"]
  node_linking["Entity linking<br/>[linking.py]"]
end

subgraph group_retrieval["Retrieval and answers"]
  node_standard["Standard RAG<br/>[StandardRAG.py]"]
  node_rerank["Reranking<br/>[rerank.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

subgraph group_models["Model integrations"]
  node_prompt_manager["Prompt templates"]
  node_embedding_model["Embedding models<br/>[base.py]"]
  node_llm_base["LLM interface<br/>[base.py]"]
  node_llm_providers["LLM providers<br/>[openai_gpt.py]"]
  node_gateways["LLM gateways<br/>[gateways.py]"]
end

subgraph group_platform["Storage and evaluation"]
  node_embedding_store[("Embedding store<br/>[embedding_store.py]")]
  node_vector_stores[("Vector backends")]
  node_evaluation["Evaluation<br/>[qa_eval.py]"]
  node_config["Configuration<br/>[config_utils.py]"]
end

node_user(("Application user"))

node_user -->|"indexes and queries"| node_hipporag
node_hipporag -.->|"uses"| node_preprocessing
node_hipporag -.->|"extracts facts"| node_openie
node_hipporag -.->|"uses"| node_linking
node_hipporag -.->|"embeds text"| node_embedding_model
node_hipporag -.->|"stores vectors"| node_embedding_store
node_hipporag -.->|"reranks results"| node_rerank
node_hipporag -.->|"evaluates retrieval"| node_evaluation
node_hipporag -.->|"loads settings"| node_config
node_standard -.->|"uses"| node_embedding_store
node_standard -.->|"generates answers"| node_llm_base
node_openie -->|"renders prompts"| node_prompt_manager
node_openie -->|"requests extraction"| node_llm_providers
node_offline_openie -->|"uses offline model"| node_llm_base
node_llm_providers -->|"implements"| node_llm_base
node_gateways -.->|"routes through"| node_llm_base
node_embedding_store -->|"delegates storage"| node_vector_stores
node_mcp -.->|"exposes operations"| node_hipporag

click node_hipporag "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/HippoRAG.py"
click node_standard "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/StandardRAG.py"
click node_preprocessing "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/preprocessing.py"
click node_openie "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/information_extraction/openie_openai.py"
click node_offline_openie "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/information_extraction/openie_vllm_offline.py"
click node_linking "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/prompts/linking.py"
click node_prompt_manager "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/prompts/prompt_template_manager.py"
click node_embedding_model "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/embedding_model/base.py"
click node_llm_base "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/llm/base.py"
click node_llm_providers "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/llm/openai_gpt.py"
click node_gateways "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/llm/gateways.py"
click node_embedding_store "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/embedding_store.py"
click node_vector_stores "https://github.com/osu-nlp-group/hipporag/tree/main/src/hipporag/vector_stores"
click node_rerank "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/rerank.py"
click node_evaluation "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/evaluation/qa_eval.py"
click node_mcp "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/mcp_server.py"
click node_config "https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/utils/config_utils.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_preprocessing,node_openie,node_offline_openie,node_linking,node_user toneBlue
class node_standard,node_rerank,node_mcp toneAmber
class node_prompt_manager,node_embedding_model,node_llm_base,node_llm_providers,node_gateways toneMint
class node_embedding_store,node_vector_stores,node_evaluation,node_config toneRose
```

## Components

### Memory indexing

- [HippoRAG engine](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/HippoRAG.py): `src/hipporag/HippoRAG.py`
- [Text preprocessing](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/preprocessing.py): `src/hipporag/preprocessing.py`
- [OpenIE extraction](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/information_extraction/openie_openai.py): `src/hipporag/information_extraction/openie_openai.py`
- [Offline OpenIE](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/information_extraction/openie_vllm_offline.py): `src/hipporag/information_extraction/openie_vllm_offline.py`
- [Entity linking](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/prompts/linking.py): `src/hipporag/prompts/linking.py`

### Retrieval and answers

- [Standard RAG](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/StandardRAG.py): `src/hipporag/StandardRAG.py`
- [Reranking](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/rerank.py): `src/hipporag/rerank.py`
- [MCP server](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/mcp_server.py): `src/hipporag/mcp_server.py`

### Model integrations

- [Prompt templates](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/prompts/prompt_template_manager.py): `src/hipporag/prompts/prompt_template_manager.py`
- [Embedding models](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/embedding_model/base.py): `src/hipporag/embedding_model/base.py`
- [LLM interface](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/llm/base.py): `src/hipporag/llm/base.py`
- [LLM providers](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/llm/openai_gpt.py): `src/hipporag/llm/openai_gpt.py`
- [LLM gateways](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/llm/gateways.py): `src/hipporag/llm/gateways.py`

### Storage and evaluation

- [Embedding store](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/embedding_store.py): `src/hipporag/embedding_store.py`
- [Vector backends](https://github.com/osu-nlp-group/hipporag/tree/main/src/hipporag/vector_stores): `src/hipporag/vector_stores`
- [Evaluation](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/evaluation/qa_eval.py): `src/hipporag/evaluation/qa_eval.py`
- [Configuration](https://github.com/osu-nlp-group/hipporag/blob/main/src/hipporag/utils/config_utils.py): `src/hipporag/utils/config_utils.py`

### Other components

- **Application user**

## Connections

- Application user → HippoRAG engine: indexes and queries
- HippoRAG engine → Text preprocessing: uses (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG engine → OpenIE extraction: extracts facts
- HippoRAG engine → Entity linking: uses (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG engine → Embedding models: embeds text
- HippoRAG engine → Embedding store: stores vectors (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG engine → Reranking: reranks results (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG engine → Evaluation: evaluates retrieval (evidence: `src/hipporag/HippoRAG.py`)
- HippoRAG engine → Configuration: loads settings (evidence: `src/hipporag/HippoRAG.py`)
- Standard RAG → Embedding store: uses (evidence: `src/hipporag/StandardRAG.py`)
- Standard RAG → LLM interface: generates answers
- OpenIE extraction → Prompt templates: renders prompts (evidence: `src/hipporag/information_extraction/openie_openai.py`)
- OpenIE extraction → LLM providers: requests extraction (evidence: `src/hipporag/information_extraction/openie_openai.py`)
- Offline OpenIE → LLM interface: uses offline model (evidence: `src/hipporag/information_extraction/openie_vllm_offline.py`)
- LLM providers → LLM interface: implements (evidence: `src/hipporag/llm/openai_gpt.py`)
- LLM gateways → LLM interface: routes through
- Embedding store → Vector backends: delegates storage (evidence: `src/hipporag/embedding_store.py`)
- MCP server → HippoRAG engine: exposes operations
