# xmudeeplit/memgraphrag architecture

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

- Interactive diagram: https://gitdiagram.com/xmudeeplit/memgraphrag
- Repository: https://github.com/xmudeeplit/memgraphrag

## Overview

1. **Repository purpose**
   - MemGraphRAG is an offline/CLI-driven GraphRAG system that builds a persistent “memory” from a text corpus and then uses that memory to answer questions with graph-aware retrieval.

2. **Top-level execution paths**
   - `code/index.py` is the indexing entrypoint: it ingests a corpus, extracts structured knowledge, builds memory artifacts, and writes graph/embedding stores.
   - `code/retrieval_dataset_test.py` is the evaluation/QA entrypoint: it loads the saved artifacts, retrieves evidence for questions, generates answers, and records metrics and traces.

3. **Primary pipeline boundary**
   - The architecture is split into two phases:
     - **Indexing/construction**: corpus → extracted facts/schemas → persistent memory and graph.
     - **Retrieval/QA**: question → candidate evidence from memory/graph → reranking and reasoning → answer + evaluation output.
   - The saved `save-dir` is the boundary between these phases.

4. **Three-layer memory model**
   - `code/src/Memory.py` and `code/src/MemGraphRAG.py` organize the core representation into three linked layers:
     - **Passage layer**: original text chunks.
     - **Fact layer**: extracted relation triples.
     - **Schema layer**: abstract ontology triples generalized from facts.
   - The design keeps bidirectional links among these layers so retrieval can move between raw text, concrete facts, and abstract patterns.

5. **Knowledge extraction subsystem**
   - `code/src/information_extraction/` contains OpenIE implementations for:
     - **Online extraction** through an OpenAI-compatible LLM.
     - **Offline extraction** through local vLLM-based generation.
   - This subsystem turns corpus passages into structured triples and associated evidence, using prompts from `code/src/prompts/`.

6. **Prompt and schema management**
   - `code/src/prompts/` contains task-specific templates for triple extraction, linking, NER, query formulation, and retrieval QA.
   - `prompt_template_manager.py` centralizes template selection, which matters because the same pipeline can be run with different model backends and prompt styles.

7. **Graph construction and conflict handling**
   - `code/src/MemGraphRAG.py` is the orchestrator for building the memory graph from extracted information.
   - The README indicates the pipeline performs ontology induction, low-frequency schema filtering, and conflict-aware resolution of hard contradictory evidence before final graph creation.
   - The resulting graph is persisted as JSON/GraphML artifacts under the output directory.

8. **Embedding and vector storage**
   - `code/src/embedding_model/` abstracts multiple embedding backends such as BGE, Contriever, GritLM, and NVEmbedV2.
   - `code/src/embedding_store.py` persists embeddings for chunks, entities, and facts so retrieval can reuse them without recomputation.
   - Embedding model identity is part of the saved artifact path, so indexing and retrieval must use compatible model settings.

9. **Retrieval engine**
   - `code/src/rerank.py` and retrieval logic inside the main pipeline combine embedding similarity with graph-based expansion.
   - The README describes a graph-enhanced retrieval strategy using similarity scoring plus Personalized PageRank, with optional fact reranking and threshold filtering.
   - This means retrieval is not purely vector search; it is a hybrid of dense retrieval and graph traversal over the constructed memory graph.

10. **LLM and backend abstraction**
   - `code/src/llm/` provides a backend interface for:
     - **OpenAI-compatible APIs**
     - **local vLLM-based models**
   - These backends are used both for extraction and for answer generation, so the repository treats the LLM as a replaceable service boundary.

11. **Evaluation and experiment harness**
   - `code/src/evaluation/` includes retrieval and QA evaluators, with separate modules for scoring retrieval quality and answer quality.
   - `code/src/evaluation/README.md` suggests this layer is meant to standardize benchmarking rather than drive core indexing behavior.
   - `retrieval_dataset_test.py` produces structured outputs containing answers, retrieved documents, metadata, latency, and token usage for batch experiments.

12. **Data and artifact layout**
   - `dataset/` contains example corpora and QA sets for HotpotQA, Musique, 2WikiMultiHopQA, and a medical dataset.
   - Output artifacts typically include:
     - OpenIE results
     - initial memory with schema
     - final memory JSON
     - memory graph files
     - embedding directories for chunks/entities/facts
   - These artifacts are the durable state of the system and are what make reruns and evaluation reproducible.

13. **Utilities and runtime support**
   - `code/src/utils/` handles configuration, logging, embedding helpers, evaluation helpers, QA helpers, and general typing/misc support.
   - `_bootstrap_sys_path.py` indicates the CLI scripts are designed to run from the repo root while still importing the local `src` package cleanly.

14. **External dependencies that shape the architecture**
   - The system assumes an **OpenAI-compatible LLM endpoint** for online operation and a **local Hugging Face embedding model** for dense retrieval.
   - Optional offline extraction depends on local inference tooling such as `vllm` or `llama-factory`.
   - These external model services are architectural dependencies, not just implementation details, because they define how extraction, retrieval, and generation are executed.

Main entry points: [`code/src/Memory.py`](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/Memory.py) (Memory model), [`code/retrieval_dataset_test.py`](https://github.com/xmudeeplit/memgraphrag/blob/main/code/retrieval_dataset_test.py) (Retrieval CLI), [`code/src/rerank.py`](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/rerank.py) (Reranker), [`code/src/MemGraphRAG.py`](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/MemGraphRAG.py) (MemGraphRAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Pipeline"]
  node_index_entry["Index CLI<br/>entrypoint<br/>[index.py]"]
  node_retrieval_entry["Retrieval CLI<br/>entrypoint"]
  node_save_dir[("Save dir<br/>artifact boundary")]
end

subgraph group_core["Core memory"]
  node_memgraphrag["MemGraphRAG<br/>orchestrator<br/>[MemGraphRAG.py]"]
  node_memory[("Memory model<br/>3-layer memory<br/>[Memory.py]")]
  node_passages["Passages<br/>text chunks"]
  node_facts{{"Facts<br/>triples"}}
  node_schemas{{"Schemas<br/>ontology triples"}}
end

subgraph group_models["Model backends"]
  node_ie_online["Online IE<br/>openie llm<br/>[openie_openai.py]"]
  node_ie_offline["Offline IE<br/>openie vllm"]
  node_prompt_mgr["Prompt manager<br/>template selector"]
  node_llm_api["LLM API<br/>backend interface<br/>[openai_gpt.py]"]
  node_llm_local["Local LLM<br/>backend interface<br/>[vllm_offline.py]"]
  node_embed_backends["Embedding backends<br/>embedding adapters"]
  node_embed_store[("Embedding store<br/>persistent vectors<br/>[embedding_store.py]")]
end

subgraph group_ops["Operations"]
  node_rerank["Reranker<br/>hybrid retrieval<br/>[rerank.py]"]
  node_eval["Evaluators<br/>benchmarking"]
  node_utils["Utils<br/>support library"]
end

node_index_entry -->|"builds"| node_memgraphrag
node_retrieval_entry -->|"loads"| node_memgraphrag
node_index_entry -->|"writes"| node_save_dir
node_retrieval_entry -->|"reads"| node_save_dir
node_memgraphrag -->|"organizes"| node_memory
node_memory -->|"contains"| node_passages
node_memory -->|"contains"| node_facts
node_memory -->|"contains"| node_schemas
node_passages -->|"extracts"| node_ie_online
node_passages -->|"extracts"| node_ie_offline
node_ie_online -->|"uses"| node_prompt_mgr
node_ie_offline -->|"uses"| node_prompt_mgr
node_ie_online -->|"calls"| node_llm_api
node_ie_offline -->|"calls"| node_llm_local
node_facts -->|"induces"| node_schemas
node_memgraphrag -->|"persists"| node_embed_store
node_embed_store -->|"computed by"| node_embed_backends
node_retrieval_entry -->|"queries"| node_rerank
node_rerank -->|"scores"| node_embed_store
node_rerank -->|"expands"| node_memory
node_rerank -->|"feeds"| node_eval
node_retrieval_entry -.->|"supports"| node_utils
node_index_entry -.->|"supports"| node_utils

click node_index_entry "https://github.com/xmudeeplit/memgraphrag/blob/main/code/index.py"
click node_retrieval_entry "https://github.com/xmudeeplit/memgraphrag/blob/main/code/retrieval_dataset_test.py"
click node_memgraphrag "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/MemGraphRAG.py"
click node_memory "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/Memory.py"
click node_ie_online "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/information_extraction/openie_openai.py"
click node_ie_offline "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/information_extraction/openie_vllm_offline.py"
click node_prompt_mgr "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/prompts/prompt_template_manager.py"
click node_llm_api "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/llm/openai_gpt.py"
click node_llm_local "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/llm/vllm_offline.py"
click node_embed_backends "https://github.com/xmudeeplit/memgraphrag/tree/main/code/src/embedding_model"
click node_embed_store "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/embedding_store.py"
click node_rerank "https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/rerank.py"
click node_eval "https://github.com/xmudeeplit/memgraphrag/tree/main/code/src/evaluation"
click node_utils "https://github.com/xmudeeplit/memgraphrag/tree/main/code/src/utils"

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_index_entry,node_retrieval_entry,node_save_dir toneBlue
class node_memgraphrag,node_memory,node_passages,node_facts,node_schemas toneAmber
class node_ie_online,node_ie_offline,node_prompt_mgr,node_llm_api,node_llm_local,node_embed_backends,node_embed_store toneMint
class node_rerank,node_eval,node_utils toneRose
```

## Components

### Pipeline

Indexing and retrieval phases separated by the saved memory artifacts.

- [Index CLI](https://github.com/xmudeeplit/memgraphrag/blob/main/code/index.py): entrypoint · Builds memory artifacts from a corpus. · `code/index.py`
- [Retrieval CLI](https://github.com/xmudeeplit/memgraphrag/blob/main/code/retrieval_dataset_test.py): entrypoint · Runs batch QA over saved artifacts and records outputs. · `code/retrieval_dataset_test.py`
- **Save dir**: artifact boundary · Persistent output boundary between indexing and retrieval.

### Core memory

Three-layer memory representation and graph orchestration.

- [MemGraphRAG](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/MemGraphRAG.py): orchestrator · Coordinates graph construction, retrieval, and answer assembly. · `code/src/MemGraphRAG.py`
- [Memory model](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/Memory.py): 3-layer memory · Passage, fact, and schema layers with links among them. · `code/src/Memory.py`
- **Passages**: text chunks · Original corpus chunks used as evidence.
- **Facts**: triples · Extracted relation triples grounded in passages.
- **Schemas**: ontology triples · Generalized schema-level knowledge induced from facts.

### Model backends

LLM, extraction, and embedding backends.

- [Online IE](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/information_extraction/openie_openai.py): openie llm · OpenAI-compatible triple extraction. · `code/src/information_extraction/openie_openai.py`
- [Offline IE](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/information_extraction/openie_vllm_offline.py): openie vllm · Local vLLM-based triple extraction. · `code/src/information_extraction/openie_vllm_offline.py`
- [Prompt manager](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/prompts/prompt_template_manager.py): template selector · Selects task prompts for extraction, linking, NER, and QA. · `code/src/prompts/prompt_template_manager.py`
- [LLM API](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/llm/openai_gpt.py): backend interface · OpenAI-compatible generation backend. · `code/src/llm/openai_gpt.py`
- [Local LLM](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/llm/vllm_offline.py): backend interface · Local vLLM generation backend. · `code/src/llm/vllm_offline.py`
- [Embedding backends](https://github.com/xmudeeplit/memgraphrag/tree/main/code/src/embedding_model): embedding adapters · BGE, Contriever, GritLM, and NVEmbedV2 adapters. · `code/src/embedding_model`
- [Embedding store](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/embedding_store.py): persistent vectors · Stores chunk, entity, and fact embeddings for reuse. · `code/src/embedding_store.py`

### Operations

Reranking, evaluation, and shared utilities.

- [Reranker](https://github.com/xmudeeplit/memgraphrag/blob/main/code/src/rerank.py): hybrid retrieval · Combines similarity, graph expansion, and filtering. · `code/src/rerank.py`
- [Evaluators](https://github.com/xmudeeplit/memgraphrag/tree/main/code/src/evaluation): benchmarking · Retrieval and QA scoring modules. · `code/src/evaluation`
- [Utils](https://github.com/xmudeeplit/memgraphrag/tree/main/code/src/utils): support library · Configuration, logging, embedding, QA, and typing helpers. · `code/src/utils`

## Connections

- Index CLI → MemGraphRAG: builds · Indexing entrypoint drives graph construction.
- Retrieval CLI → MemGraphRAG: loads · Retrieval entrypoint loads the saved memory graph.
- Index CLI → Save dir: writes · Produces durable artifacts under the output directory.
- Retrieval CLI → Save dir: reads · Consumes persisted artifacts for QA and evaluation.
- MemGraphRAG → Memory model: organizes · Core orchestration organizes the memory layers.
- Memory model → Passages: contains · Passage layer stores original chunks.
- Memory model → Facts: contains · Fact layer stores extracted triples.
- Memory model → Schemas: contains · Schema layer stores generalized ontology triples.
- Passages → Online IE: extracts · Online extraction turns passages into triples.
- Passages → Offline IE: extracts · Offline extraction turns passages into triples.
- Online IE → Prompt manager: uses · Extraction uses task-specific prompts.
- Offline IE → Prompt manager: uses · Extraction uses task-specific prompts.
- Online IE → LLM API: calls · Online extraction depends on API LLMs.
- Offline IE → Local LLM: calls · Offline extraction depends on local LLMs.
- Facts → Schemas: induces · Facts are generalized into schema knowledge.
- MemGraphRAG → Embedding store: persists · Stores embeddings for later retrieval.
- Embedding store → Embedding backends: computed by · Vectors are produced by selectable embedding models.
- Retrieval CLI → Reranker: queries · QA retrieval uses hybrid reranking and expansion.
- Reranker → Embedding store: scores · Uses dense similarity from persisted embeddings.
- Reranker → Memory model: expands · Traverses graph-linked memory for evidence.
- Reranker → Evaluators: feeds · Retrieval outputs are evaluated in batch runs.
- Retrieval CLI → Utils: supports · Shared helpers support configuration, logging, and QA formatting.
- Index CLI → Utils: supports · Shared helpers support configuration and logging.