README.md

---
language:
- en
tags:
- knowledge-graph
- question-answering
- multi-hop-reasoning
- training-free
- zero-shot
- graph-traversal
- explainable-ai
- crystal-box
- kgqa
- information-retrieval
license: agpl-3.0
library_name: cerebrum-kg
pipeline_tag: question-answering
---

# CEREBRUM, Training-Free Knowledge Graph Reasoning

**Every answer is a citable graph path. Not a prediction.**

[![GitHub](https://img.shields.io/badge/GitHub-BrutalByte%2FCEREBRUM-181717?logo=github)](https://github.com/BrutalByte/CEREBRUM)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Version](https://img.shields.io/badge/version-v2.92.0-indigo)](https://github.com/BrutalByte/CEREBRUM)

---

## Model Description

CEREBRUM is a **training-free knowledge graph question answering (KGQA) framework** that performs multi-hop reasoning via deterministic beam-search traversal guided by a 10-parameter Community-Structured Attention (CSA) formula.

Unlike supervised KGQA systems (EmbedKGQA, UniKGQA, NSM), CEREBRUM requires **no labeled question-answer pairs, no gradient steps, and no dataset-specific configuration**. Load any knowledge graph formatted as `(head, relation, tail)` triples and query it immediately.

Every answer includes the complete hop-by-hop reasoning path, every edge traversed, every score assigned, making the full reasoning process auditable, reproducible, and provable. The accuracy numbers (60.6% H@1 on MetaQA 3-hop, 87.9% H@10, 100% on Hetionet `disease_associates_gene`) are evidence for the above properties, not the headline.

---

**What matters depends on who you are.**

| | The claim | The evidence |
|--|-----------|-------------|
| **Researchers** | Your result is falsifiable. Every one. | Full hop-by-hop path, CSA weight per edge, community votes, pruned candidates — every answer is a complete reasoning record. Deterministic: same query, same graph → same path every time. |
| **Scientists** | You can't cite a hallucination. We don't make them. | Structural impossibility: answers can only be entities reachable via real graph edges. On Hetionet: 100% H@1 on `disease_associates_gene`, 95.3% 1-hop average, full provenance per answer. |
| **Engineers** | Load a CSV. Query immediately. Zero configuration. | `ParameterInitializer` derives all 9 scoring parameters from graph statistics in one O(E) pass. Adapters for CSV, Neo4j, RDF/SPARQL, NetworkX. |
| **Students** | $0.001 per 1K queries. No API key. No GPU. | Compute only. Runs on a laptop. Zero-config baseline: 56.8% H@1 on MetaQA 3-hop with no tuning. AGPL-3.0 — free for academic use. |

---

### Key Properties

| Property | Value |
|----------|-------|
| Training required | **None** |
| Hallucination risk | **0%** (deterministic graph traversal) |
| Reasoning transparency | **Full hop-by-hop trace** |
| Knowledge graph formats | CSV, Neo4j, RDF/SPARQL, NetworkX |
| Cost per 1K queries | **~$0.001** (compute only) |
| GPU required | Optional (CPU-capable, GPU-accelerated) |

---

## Benchmark Results

### MetaQA, 3-hop (14,274 test questions)

| System | 3-hop H@1 | 3-hop H@10 | MRR | Training |
|--------|-----------|------------|-----|----------|
| **CEREBRUM v2.88.0 (full pipeline)** | **60.6%** | **87.9%** | **0.703** | **None** |
| CEREBRUM (search only) | 12.5% | 50.3% | — | None |
| UniKGQA (Jiang et al., 2023) † | 99.1% | — | — | Supervised |
| EmbedKGQA (Saxena et al., 2020) † | ~94% | — | — | Supervised |
| MINERVA (Das et al., 2018) † | — | 45.6% | — | RL-trained |
| GraftNet (Sun et al., 2018) † | 22.8% | — | — | Supervised |

> **†** Black-box model: no auditable reasoning path; can produce confident wrong answers.

**Note on the H@1 gap:** The gap to supervised H@1 (99% vs 60.6%) is a *ranking* challenge, not a retrieval failure. CEREBRUM places the correct answer in its top-10 candidates **87.9% of the time**, matching supervised recall, while requiring zero training data and returning a full reasoning trace.

### MetaQA Dataset Stats

- 43,234 entities · 9 relation types · 186,217 triples
- Test split: 14,274 3-hop questions (full evaluation)
- Graph regime: `hub_homogeneous` (all seeds are movie entities)

---

### Hetionet, Biomedical KG (998 QA pairs, 6 templates)

Hetionet is a biomedical knowledge graph with 47,031 entities, 2,250,197 edges, and 24 relation types. Phase 209 full canonical validation (200q/template, sentence-transformers).

| Hop | H@1 | Notes |
|-----|-----|-------|
| 1-hop | **95.3%** | disease→gene, gene→pathway, compound→disease |
| 2-hop | **53.0%** | disease→gene→pathway (+10pp vs random with sentence embeddings) |
| 3-hop | 49.2% | disease→compound→gene (cross-type ceiling†) |

Per-template: `disease_associates_gene` **100%** · `gene_participates_pathway` 98.5% · `compound_treats_disease` 89.0% · `disease_gene_pathway` 81.1% · `compound_gene_disease` 34.5%

> **†** Cross-type 3-hop ceiling: cosine-similarity bias suppresses valid cross-type paths. Documented known limitation, not addressable by structural parameter tuning.

**fANOVA finding:** `branch_bonus` accounts for **81.9% of scoring variance** on Hetionet, the highest single-parameter dominance across all benchmarks.

### Hetionet Dataset Stats

- 47,031 nodes · 2,250,197 edges · 24 relation types
- 998 unique QA pairs across 6 templates
- Graph regime: `typed_heterogeneous` (biomedical ontology)

---

### WebQSP, Freebase 2-hop (1,628 test questions)

WebQSP is the standard benchmark for 2-hop open-world KGQA. The graph contains 3.79M entity-name triples from Freebase, 989 distinct relation types, typed-heterogeneous regime.

**Phase 259 result, 1,628 questions, full evaluation:** H@1=**11.92%**, H@10=**20.47%**, MRR=0.1516 (zero training data; zero-config baseline H@1=1.41%, +746% relative). Key milestones: Phase 255 Guaranteed 1-hop Pass (G1P) injects beam-pruned 1-hop neighbors back into the candidate pool; Phase 257 schema_top_k=32 (68.4% fANOVA dominance) expands PathSchemaIndex 2-hop coverage; Phase 259 idf_weight=0.073 + beta=0.649 + DPW=1.836 applies triple hub-suppression.

**Why WebQSP is hard for training-free systems:** Freebase uses CVT (compound-value-type) mediator nodes with opaque MID identifiers that break semantic attention on indirect 2-hop paths. The hop-reachability diagnostic showed 43.5% of beam misses are direct 1-hop neighbors pruned at beam_width — G1P targets this entire population.

### WebQSP Dataset Stats

- 3.79M triples · 989 relation types · Freebase open-world KB
- Test split: 1,628 questions (full evaluation)
- Graph regime: `typed_heterogeneous` (Freebase ontology, 2-hop)

---

## How It Works

CEREBRUM reasons over a knowledge graph in three stages:

**1. Graph Profiling**, At build time, `GraphProfiler` analyzes the loaded graph: degree distribution, hub score, community modularity Q, and relation fan-out statistics. This auto-configures traversal strategy (`hub_homogeneous`, `typed_heterogeneous`, or `mixed`).

**2. Community-Structured Attention**, During traversal, each candidate edge is scored by the 10-parameter CSA formula, a sigmoid over a weighted sum of graph-structural features:

| Feature | Role |
|---------|------|
| Semantic similarity | Cosine distance between query and candidate entity |
| Community score | Structural membership in the traversal's target community |
| Edge-type weight | Per-relation importance derived from graph schema |
| Distance penalty | Penalizes edges that move away from the target |
| Hop decay | Reduces score as depth increases |
| PageRank | Global node importance prior |
| Temporal decay | Recency of the edge in time-stamped graphs |
| Node recency | How recently the node was visited in the beam |
| Synthesis-density penalty | Discounts over-reliance on synthesized edges |
| Grounding confidence | Provenance confidence of the underlying triple |

**3. Beam Traversal + Answer Extraction**, Beam search (default width 10) follows the highest-scoring paths up to `max_hop` steps. The Schema-Derived Relation Boost (SDRB) dynamically upweights relations with high fan-out based on graph statistics, without any dataset-specific tuning.

---

## Novel Contributions

CEREBRUM introduces six original algorithmic contributions:

1. **Community-Structured Attention (CSA)**, 10-parameter training-free attention formula using graph community topology as discrete attention heads.

2. **Schema-Derived Relation Boost (SDRB)**, Derives per-relation scoring weights analytically from triple statistics: `boost(r) = γ × fan_out(r)^β`. Eliminates KB-specific configuration entirely.

3. **Principled Hyperparameter Initialization (ParameterInitializer)**, Maps all 9 scoring parameters to measurable graph statistics via Bayesian evidence combination (branch_bonus ≈ 0.17), IDF theory (idf_weight = cv_d × 0.01), and Newman-Girvan modularity (vote_weight = 0.72 + 0.15·Q).

4. **Experience-Dependent Graph Plasticity (Bridge Twins + STDP)**, Relay nodes form automatically on frequently-traversed inter-community paths, mimicking synaptic potentiation without training.

5. **fANOVA Variance Decomposition Finding**, Systematic fANOVA analysis of 200 tuner trials reveals `branch_bonus` accounts for **46.2%** of scoring variance vs. 1.2% for beam width, 39× more influential. Per-relation tuning was masking this signal entirely.

6. **PathSchemaIndex, Training-Free Pre-Traversal Schema Prediction (Phase 236)**, The first *predictive* reasoning signal in CEREBRUM. All prior signals steer or re-rank *after* beam traversal. PathSchemaIndex predicts the most likely (r1, r2) 2-hop relation path *before* any traversal begins, by encoding all graph schemas as natural-language embeddings and finding the closest match to the question embedding. Predicted schemas execute as targeted 2-hop traversals in parallel with the beam, adding high-precision candidates the beam may have pruned. The seed-filter (only schemas whose r1 is actually present on the seed entity) eliminates structurally inapplicable matches. On WebQSP: **+3.5pp H@1** (6.0% → 9.5%), **+4.0pp H@10**.

7. **BeamCheckpoint, Parameter-Free Structural Expansion Cache (Phase 241)**, Inspired by Behrouz et al. (2026) Memory Caching (arXiv:2602.24281), which proposes caching RNN hidden-state checkpoints so that recurrent models gain growing memory without re-processing the full input sequence. BeamCheckpoint applies the dual principle to graph traversal: the raw neighbor expansion at each hop is parameter-free (graph structure is fixed), so it is cached per entity and reused across any re-traversals with different CSA parameters. The scoring pass is then applied on the cached structural expansion, cleanly separating *structure* (what nodes are reachable) from *attention* (which ones to select). This eliminates redundant graph I/O for repeated seeds across tuner trials. The companion **Sparse Selective Engram Consolidation** (`EngramConsolidator.sparse_consolidate()`) applies the same sparsity principle to the Engram cache: instead of promoting all relation sequences above a count threshold, patterns are ranked by `usage × confidence` and only the top-k are materialized as canonical engrams.

---

## Installation

```bash
# Core engine with API and embeddings
pip install cerebrum-kg-core[api,embeddings]

# Full install including Studio UI
pip install cerebrum-kg-core[all]
pip install cerebrum-kg-studio
```

**Requirements:** Python ≥ 3.10, PyTorch ≥ 2.0, sentence-transformers (optional but recommended)

---

## Quick Start

```python
from core.cerebrum_graph import CerebrumGraph

# Load any knowledge graph
graph = CerebrumGraph.build("my_graph.csv")

# Query with full trace
results = graph.query("What compound treats Diabetes?", max_hop=3)

for r in results:
    print(f"Answer: {r.entity} Score: {r.score:.3f}")
    for hop in r.path:
        print(f" → {hop.relation} → {hop.entity}")
```

---

## Supported Knowledge Graph Formats

| Format | Adapter | Notes |
|--------|---------|-------|
| CSV `(head, relation, tail)` | `CSVAdapter` | Default; zero config |
| Neo4j | `Neo4jAdapter` | Bolt protocol |
| RDF / SPARQL | `SPARQLAdapter` | Any SPARQL endpoint |
| NetworkX | `NetworkXAdapter` | In-memory graphs |
| Hetionet (biomedical) | `CSVAdapter` | Validated: 47,031 nodes, 24 relation types |

---

## Use Cases

- **Healthcare / Pharma**, Drug-disease reasoning over biomedical KGs (Hetionet). Every conclusion citable to a specific graph edge.
- **Legal**, Case law and regulatory graphs. Full audit trail built-in.
- **Financial**, Entity relationship graphs for compliance. Reproducible reasoning.
- **Scientific Research**, Autonomous hypothesis generation with literature validation.
- **Any domain**, Load your own `(head, relation, tail)` CSV and query immediately.

---

## Architecture Overview

```
THALAMUS (Ingestion)
└─ IngestionPipeline → EmbeddingEngine → StructuralEncoder → CommunityEngine

CORTEX (Reasoning)
└─ PathSchemaIndex (pre-traversal schema prediction)
└─ CSAEngine (10-param) → BeamTraversal → SDRB → AnswerExtractor
└─ Schema channel merge (high-precision parallel traversal)

SDRB (Schema-Derived Relation Boost)
└─ fan_out(r) computed at load time → boost(r) = γ × fan_out(r)^β

Output
└─ Ranked answers + full hop-by-hop ReasoningTrace
```

---

## Citation

```bibtex
@misc{buchorn2026cerebrum,
  title = {CEREBRUM: Training-Free Multi-Hop Knowledge Graph Reasoning
           via Community-Structured Graph Attention},
  author = {Buchorn, Bryan Alexander},
  year = {2026},
  note = {arXiv preprint [ARXIV_ID_PLACEHOLDER]},
  url = {https://github.com/BrutalByte/CEREBRUM}
}

@misc{buchorn2026sdrb,
  title = {Schema-Derived Relation Boost and Principled Hyperparameter
           Initialization for Training-Free Multi-Hop Knowledge Graph Reasoning},
  author = {Buchorn, Bryan Alexander},
  year = {2026},
  note = {arXiv preprint [ARXIV_SDRB_ID_PLACEHOLDER]},
  url = {https://github.com/BrutalByte/CEREBRUM}
}
```

---

## References

Behrouz, A., Li, Z., Deng, Y., Zhong, P., Razaviyayn, M., & Mirrokni, V. (2026). Memory Caching: RNNs with Growing Memory. *arXiv preprint arXiv:2602.24281*. https://doi.org/10.48550/arXiv.2602.24281

Das, R., Dhuliawala, S., Zaheer, M., Vilnis, L., Durugkar, I., Krishnamurthy, A., Smola, A., & McCallum, A. (2018). Go for a walk and arrive at the answer. *ICLR 2018*. https://openreview.net/forum?id=Syg-YfWCW

Himmelstein, D. S., et al. (2017). Systematic integration of biomedical knowledge prioritizes drugs for repurposing. *eLife, 6*, e26726. https://doi.org/10.7554/eLife.26726

Hutter, F., Hoos, H., & Leyton-Brown, K. (2014). An efficient approach for assessing hyperparameter importance. *ICML 2014*. https://proceedings.mlr.press/v32/hutter14.html

Jiang, J., et al. (2023). UniKGQA. *ICLR 2023*. https://openreview.net/forum?id=Z63RvyAZ2Vh

Newman, M. E. J., & Girvan, M. (2004). Finding and evaluating community structure in networks. *Physical Review E, 69*(2), 026113. https://doi.org/10.1103/PhysRevE.69.026113

Saxena, A., Tripathi, A., & Talukdar, P. (2020). Improving multi-hop QA over KGs. *ACL 2020*. https://aclanthology.org/2020.acl-main.412

Sun, H., et al. (2018). Open domain QA using early fusion of KBs and text. *EMNLP 2018*. https://aclanthology.org/D18-1455

Zhang, Y., et al. (2018). Variational reasoning for QA with knowledge graphs. *AAAI 2018*. https://arxiv.org/abs/1709.04071

---

## License

CEREBRUM is released under the [GNU Affero General Public License v3.0 (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0).

Organizations that cannot comply with the AGPL's source-disclosure obligations (e.g., proprietary SaaS deployments) may obtain a commercial exception license. Inquiries: bryan.buchorn@gmail.com

---

*Built by one person. Open to the world.*
**© 2026 Bryan Alexander Buchorn**