Official implementation of "RAG Meets Temporal Graphs: Time-Sensitive Modeling and Retrieval for Evolving Knowledge".
Temporal-GraphRAG (TG-RAG) addresses the temporal blindness in conventional RAG systems by modeling knowledge as a bi-level temporal graph. This enables precise time-aware retrieval and efficient incremental updates as corpora evolve.
Key Advantages:
- π Explicit temporal fact representation
- π Multi-granularity temporal summaries
- π Efficient incremental updates
- π― Dynamic time-aware retrieval
git clone https://github.com/hanjiale/Temporal-GraphRAG.git cd Temporal-GraphRAG # Create virtual environment python3.12 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt
1. Set up API keys (required for LLM and embedding providers):
# Create .env file or set environment variables export OPENAI_API_KEY="your-openai-key-here" # For OpenAI provider export GOOGLE_API_KEY="your-google-key-here" # For Gemini provider (or use GEMINI_API_KEY)
2. Build and query:
# Build a graph from documents python build_graph.py --output_dir ./graph_output --corpus_path ./my_documents/ # Query the graph python query_graph.py --question "Your question here" --working_dir ./graph_output --mode global
Entity Types
Customize which entity types are extracted by editing tgrag/configs/prompts.yaml:
defaults: entity_types: - "financial concept" - "business segment" - "event" - "company" - "person" - "product" - "location"
The system will only extract entities matching these configured types.
LLM and Embedding Providers
Configure in tgrag/configs/config.yaml:
building: provider: "gemini" # Options: openai, azure, bedrock, gemini, ollama model: "gemini-2.5-flash-lite" embedding_provider: "openai"
Supported Providers:
- OpenAI - Requires
OPENAI_API_KEY - Azure OpenAI - Requires Azure credentials (set via Azure SDK)
- Amazon Bedrock - Requires AWS credentials and
aioboto3 - Google Gemini - Requires
GOOGLE_API_KEYorGEMINI_API_KEY - Ollama - Requires local Ollama server (default:
http://localhost:11434)
Set API keys via environment variables or .env file:
export OPENAI_API_KEY="your-key-here" export GOOGLE_API_KEY="your-key-here" # or GEMINI_API_KEY
Building the Graph
The build_graph.py script automatically detects input type:
ECT-QA corpus (JSONL.gz):
python build_graph.py --output_dir ./graph_output --corpus_path ./ect-qa/corpus/base.jsonl.gz --num_docs 10
Single text file:
python build_graph.py --output_dir ./graph_output --corpus_path ./my_document.txt
Directory of text files (recursive):
python build_graph.py --output_dir ./graph_output --corpus_path ./my_documents/
Supported text formats: .txt, .md, .rst, .text, .log, and files without extensions.
Query Modes
# Local mode - for specific facts python query_graph.py --question "What was Company X's revenue in Q3 2023?" --mode local # Global mode - for trends and summarization python query_graph.py --question "How did tech companies navigate 2023 challenges?" --mode global # Naive mode - simple RAG python query_graph.py --question "What is artificial intelligence?" --mode naive
Python API Examples
from tgrag import create_temporal_graphrag_from_config # Build the graph graph_rag = create_temporal_graphrag_from_config( config_path="tgrag/configs/config.yaml", config_type="building" ) # Insert documents graph_rag.insert([{"title": "Doc 1", "doc": "content..."}]) # Query the graph graph_rag = create_temporal_graphrag_from_config( config_path="tgrag/configs/config.yaml", config_type="querying" ) answer = graph_rag.query("Your question here", mode="global")
High-quality benchmark for time-sensitive question answering:
- Corpus: 480 earnings call transcripts (24 companies, 2020-2024)
- Questions: 1,005 specific + 100 abstract temporal queries
The dataset is also available on Hugging Face: austinmyc/ECT-QA
You can load it using:
from datasets import load_dataset # Load questions dataset questions = load_dataset("austinmyc/ECT-QA", "questions") # Load corpus dataset corpus = load_dataset("austinmyc/ECT-QA", "corpus")
Temporal-GraphRAG/
βββ tgrag/
β βββ configs/
β β βββ config.yaml # Main configuration
β β βββ prompts.yaml # prompts for indexing and querying
β βββ src/
β βββ temporal_graphrag.py
β βββ ...
βββ ect-qa/ # ECT-QA dataset
β βββ corpus/
β β βββ base.jsonl.gz # 2020 - 2023
β β βββ new.jsonl.gz # 2024
β βββ questions/
β βββ local_base.jsonl
β βββ local_new.jsonl
β βββ global_base.jsonl
β βββ global_new.jsonl
βββ graph_storage/
β βββ ... # Output graphs
βββ build_graph.py # Script to build knowledge graph
βββ query_graph.py # Script to query the graph
βββ requirements.txt
βββ README.md
βββ LICENSE
βββ .gitignore
@article{han2025rag, title={RAG Meets Temporal Graphs: Time-Sensitive Modeling and Retrieval for Evolving Knowledge}, author={Han, Jiale and Cheung, Austin and Wei, Yubai and Yu, Zheng and Wang, Xusheng and Zhu, Bing and Yang, Yi}, journal={arXiv preprint arXiv:2510.13590}, year={2025} }
Paper available at: arXiv:2510.13590