ReMindRAG: Low-Cost LLM-Guided Knowledge Graph Traversal for Efficient RAG

ReMindRAG (Retrieve and Memorize)​​ enhances RAG systems by leveraging LLM-guided knowledge graph traversal for efficient, fine-grained retrieval.

Unlike traditional methods, it resolves long dependencies and multi-hop reasoning while minimizing computational overhead. By memorizing traversal paths without additional training, ReMindRAG boosts accuracy and reduces retrieval costs for similar queries. Experiments show superior performance in complex tasks—especially multi-hop reasoning and long-range dependencies—with improved robustness, adaptability, and cost efficiency compared to existing approaches.

CS 5542 — Lab 7 Reproducibility Submission Team: Tony Nguyen · Daniel Evans· Joel Vinas Repository: mosomo82/ReMindRAG_Week7 📺 Demo Video: Watch on YouTube

Quick Start — Single Command

Option A: Docker (no setup required)

docker build -t remindrag:latest .
docker run --rm remindrag:latest
# Expected: SUCCESS: RAG pipeline successfully retrieved chunks from the database.

Option B: Smoke Test (native Python)

pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu126
python tests/smoke_test.py
# Writes result to: artifacts/smoke_test_result.json

Option C: Makefile

make setup       # Install dependencies
make smoke       # Run smoke test
make test        # Run full 17-test audit suite
make streamlit   # Run the standalone Streamlit interface

See RUN.md for complete run instructions including evaluation scripts and WebUI.

Lab 7 Required Documents

Reproducibility Fixes (17 Issues Resolved)

All fixes verified by automated test suite and Streamlit runtime validations.

Installation

Initialize Environment

conda create -n ReMindRag python==3.13.2
conda activate ReMindRag
pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu126

Note: The --extra-index-url flag is required because PyTorch CUDA 12.6 wheels (torch==2.6.0+cu126) are hosted on PyTorch's own server, not PyPI. For CPU-only, omit the flag or use +cpu suffix.

Note: The embedding model (nomic-ai/nomic-embed-text-v2-moe) requires trust_remote_code=True. This is set automatically inside the library. Set TRUST_REMOTE_CODE=1 if you encounter a hang in non-interactive shells.

Setup

1. API Key

Fill in api_key.json:

[{ "base_url": "https://api.openai.com/v1", "api_key": "sk-proj-..." }]

2. HuggingFace Token

# Persistent (recommended)
huggingface-cli login

# Or per-session
export HF_TOKEN="hf_YourTokenHere"           # Linux/Mac
$env:HF_TOKEN = "hf_YourTokenHere"           # Windows PowerShell

3. Download Embedding Model

Download nomic-ai/nomic-embed-text-v2-moe into ./model_cache/.

For a lightweight smoke test, use sentence-transformers/all-MiniLM-L6-v2 (384-dim, no HF token needed).

Run Example

python example/example.py

Evaluation

Step 1: Download preprocessed LooGLE dataset from Google Drive and extract to eval/dataset_cache/LooGLE-rewrite-data/.

Step 2: Run evaluation:

python eval/eval_LooGLE.py \
  --title_index 0 --data_type longdep_qa \
  --question_type origin --seed 42 \
  --judge_model_name gpt-4o-mini

python eval/eval_Hotpot.py --seed 42 --judge_model_name gpt-4o-mini

--seed ensures deterministic results. --judge_model_name lets you use a cheaper judge (e.g. gpt-4o-mini instead of gpt-4o).

Parameter Configuration

All parameters can be set in config.yaml instead of CLI flags:

python eval/eval_LooGLE.py --config config.yaml

Use Your Own Core Components

from ReMindRag.llms import OpenaiAgent
agent = OpenaiAgent("your_api_key_url", "your_api_key", "your model name")

from ReMindRag.embeddings import HgEmbedding
embedding = HgEmbedding("your model name", "your model cache dir")

from ReMindRag.chunking import NaiveChunker
chunker = NaiveChunker("your tokenizer name", "your tokenizer cache dir", max_token_length=200)

Code Structure

ReMindRAG/
├── ReMindRag/                    # Core library
│   ├── rag_main.py               # Main entry point
│   ├── chunking/                 # Text chunking strategies
│   ├── llms/                     # LLM agent interfaces
│   ├── embeddings/               # Embedding model interfaces
│   ├── database/                 # ChromaDB + entity extraction
│   ├── generator/                # Query preprocessing + KG traversal
│   ├── kg/                       # Knowledge graph visualization
│   ├── utils/                    # Utility components
│   └── webui/                    # Flask WebUI
├── eval/                         # Evaluation scripts (LooGLE, HotpotQA)
├── example/                      # Demo script + example data
├── tests/
│   ├── smoke_test.py             # Quick smoke test (no API key needed)
│   └── test_reproducibility.py  # 17-test audit suite
├── artifacts/
│   └── smoke_test_result.json   # Smoke test output artifact
├── logs/                         # Runtime logs
├── Dockerfile                    # Reproducible container build
├── .dockerignore                 # Excludes stale cache from image
├── config.yaml                   # Config-driven execution
├── reproduce.sh                  # Cross-platform automation script
├── Makefile                      # Convenience targets
├── requirements.txt              # Pinned dependencies (146 packages)
├── environment.yml               # Conda environment spec
├── RUN.md                        # Complete run instructions
├── REPRO_AUDIT.md                # 14-issue reproducibility audit
└── RELATED_WORK_REPRO.md         # Related work reproduction report