Causality-Aware Retrieval-Augmented Generation
Find what keyword search can't — by understanding why things are connected.

Problem • Solution • Quick Start • Search Modes • API • Benchmarks

Research Context: In June 2025, researchers at the University of Illinois Urbana-Champaign published "CC-RAG: Structured Multi-Hop Reasoning via Theme-Based Causal Graphs" — a breakthrough paper that brought causal reasoning into RAG systems. The academic world was excited: RAG could finally "understand and connect," not just "find and fetch."

We had already been doing this for two months. NeuroCausal RAG v5.0 was deployed to production in April 2025. The causal engine, multi-hop retrieval, and chain injection were already running in real enterprise environments.

This is how we work: we build for real clients first, battle-test in production, then open-source. Our personal AI system JARVIS has been alive for 5 years and operating as an autonomous agent for 3 years — months before platforms like OpenClaw existed. We plan to open-source that too.

Read more: Our 2025 AI R&D: NeuroCausal RAG, DSGMv2, and 100+ SaaS Projects

Classic RAG systems retrieve documents by keyword similarity. Search for "stress" and you get documents containing the word "stress."

But real-world knowledge doesn't work that way:

Stress → Cortisol rises → Sleep disrupted → Attention drops → Workplace accident risk increases

If your system can't see this chain, it misses critical connections.

The academic world noticed this in June 2025 when UIUC researchers published CC-RAG, introducing causal graphs into RAG.

We deployed this to production in April 2025. Two months earlier.

NeuroCausal RAG builds a causal knowledge graph on top of your documents and retrieves information by understanding why things are connected — not just what words they share.

NeuroCausal RAG v6.0
├── Core Layer
│   ├── Causal Knowledge Graph (NetworkX / Neo4j)
│   ├── Multilingual Embeddings (Sentence-BERT)
│   └── Vector Index (BruteForce / FAISS / Milvus)
│
├── Search & Retrieval
│   ├── Hybrid Retriever (Similarity + Causal + Importance)
│   ├── Multi-Hop Search (N-hop path finding + bridge docs)
│   ├── Search Optimizer (6 adaptive modes)
│   └── Query Decomposer (complex → sub-queries)
│
├── Reasoning
│   ├── Contradiction Detector
│   ├── Temporal Reasoner
│   └── Entity Linker (alias resolution)
│
├── Learning
│   ├── Causal Discovery (semantic + NLI + funnel)
│   ├── Feedback Loop (RLHF)
│   └── Persistent Memory (SQLite)
│
├── Agentic RAG
│   └── LangGraph Self-Correcting Agent
│
└── API & UI
    ├── FastAPI REST API
    └── Streamlit Dashboard

Final Score = α × Similarity + β × Causal + γ × Importance

Multi-Hop Decay: hop_score = base_score × (0.7 ^ hop_distance)

git clone https://github.com/ertugrulakben/NeuroCausal-RAG.git
cd NeuroCausal-RAG
pip install -r requirements.txt

from neurocausal_rag import NeuroCausalRAG

rag = NeuroCausalRAG()

# Add documents
rag.add_document("cement", "Cement production is responsible for 8% of global CO2 emissions.")
rag.add_document("co2", "CO2 is the primary greenhouse gas driving climate change.")
rag.add_document("warming", "Global warming causes sea level rise and extreme weather.")

# Add causal links
rag.add_causal_link("cement", "co2", "causes")
rag.add_causal_link("co2", "warming", "causes")

# Search — finds cement even though query doesn't mention it
results = rag.search("What causes global warming?")
# → Returns: co2, warming, AND cement (via causal chain)

from neurocausal_rag.search import create_multi_hop_retriever

retriever = create_multi_hop_retriever(graph, embedding, max_hops=3)
results = retriever.search("How does cement affect sea levels?")

# Discovered chain:
# Cement Production → CO2 Emissions → Global Warming → Sea Level Rise
explanation = retriever.explain_connection("cement", "warming")

docker-compose up -d
# API: http://localhost:8000
# UI: http://localhost:8501

6 preset modes for different retrieval strategies:

from neurocausal_rag.search import create_optimizer

optimizer = create_optimizer(graph, embedding)
results = optimizer.search("Why did the bridge collapse?", mode="DETECTIVE")

Full REST API via FastAPI:

uvicorn neurocausal_rag.api.app:create_app --factory --host 0.0.0.0 --port 8000

curl -X POST http://localhost:8000/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "What causes global warming?", "top_k": 5, "mode": "DETECTIVE"}'

Query: "How do greenhouse gases cause global warming?"

Discovered chain:

Cement Production → CO2 Emissions → Greenhouse Gas → Global Warming

The word "cement" appears nowhere in the query — but the causal chain reveals the connection.

pytest tests/ -v

# With coverage
pytest tests/ --cov=neurocausal_rag --cov-report=html

Test Distribution (v6.1)
├── Core (graph, node, edge): 35 tests
├── Search (retriever, multi_hop, optimizer, decomposer): 66 tests
├── Learning (discovery, entity, temporal, contradiction): 42 tests
├── Memory: 24 tests
├── Integration: 20 tests
├── API Routes: 58 tests
├── Config Validation: 70 tests
├── LLM Client: 34 tests
└── Imports & Exports: 33 tests
─────────────────────────────
Total: 382 tests, 0 failures

neurocausal_rag/
├── core/           # Graph engine, nodes, edges
├── embedding/      # Sentence-BERT multilingual
├── search/         # Retriever, multi-hop, optimizer, decomposer
├── learning/       # Causal discovery, feedback, pipeline
├── entity/         # Entity linking, NER
├── reasoning/      # Contradiction detection, temporal reasoning
├── memory/         # Persistent memory store
├── agents/         # LangGraph agentic RAG
├── api/            # FastAPI REST endpoints
├── llm/            # LLM client (OpenAI)
├── visualization/  # Graph visualization (PyVis)
└── ui/             # Streamlit components

cp .env.example .env
# Set your API keys in .env

• Causal knowledge graph
• Multi-hop retrieval
• 6 search modes
• Contradiction detection
• Temporal reasoning
• Entity linking
• Persistent memory (RLHF)
• REST API (FastAPI)
• Agentic RAG (LangGraph)
• Enterprise backends (Neo4j, Milvus)
• 187 tests
• Batch processing
• Advanced UI
• PyPI package

Ertugrul Akben — AI & Systems Strategist

MIT

Because knowing "what" is not enough — you need to know "why."