KGRAG — Knowledge Compiler and Federated Retrieval Layer for Ontologically Grounded Domains
Author: Eric G. Suchanek, PhD · Flux-Frontiers, Liberty TWP, OH
Overview
KGRAG is a federation and orchestration layer for structural knowledge graphs derived from heterogeneous source domains. It integrates PyCodeKG (Python codebase analysis), DocKG (semantic document indexing), MetaboKG (metabolic pathways), DiaryKG (personal diary corpora), AgentKG (conversational memory), FTreeKG (file system trees), and a growing family of domain-specific backends under a single five-method adapter protocol.
KGRAG treats derived structure as ground truth and uses semantic embeddings strictly as an acceleration layer for locating entry points into that structure. All graph traversal, ranking, and snippet extraction is deterministic. When KGRAG output is passed to a language model for synthesis, the model receives verified facts with full source provenance — not approximate embeddings.
How this differs from RAG and KG-RAG:
RAG embeds text chunks and retrieves by approximate similarity — no structure, no provenance. KG-RAG (GraphRAG, LlamaIndex KG) uses an LLM to extract entities and edges from text: the graph is inferred, inheriting the extractor's hallucinations. KGRAG derives its graphs from formal source structure — ASTs for code, parse trees for prose, reaction schemas for biochemistry — with no language model in the pipeline. The graph is correct by construction. Embeddings are disposable; the graph is not. The retrieval layer cannot hallucinate.
→ Technical paper · Manifesto
KG Types
Fully Implemented
| Kind | Backend | Description |
|---|
code | PyCodeKG | Python codebase — AST-extracted modules, classes, functions, call graphs |
doc | DocKG | Document corpus — Markdown/RST/text indexed by topic, section, and entity |
meta | MetaboKG | Metabolic pathways — biochemical reaction networks (KEGG, BioCyc) |
diary | DiaryKG | Personal diary entries — timestamped chunk graphs with temporal edges |
agent | AgentKG | Conversational memory — Turn/Topic/Task/Summary graph (live session) |
filetree | FTreeKG | File system tree — directory/file/module/dependency structure |
memory | MemoryKG | Episodic memory — hybrid semantic + structural graph for conversation/event corpora |
gutenberg | GutenbergKG | Project Gutenberg book corpus — literature indexed by author, genre, and chapter via DocKG-compatible indices |
genealogy | GenealogyKG | Genealogical records — person/family graph with relational edges (genealogy-kg; install it alongside kg-rag, or the adapter reports unavailable) |
connectome | ConnectomeKG | Synapse-resolution connectome (FlyWire FAFB v783): neurons, cell types, neuropils and labels, searched by their descriptions (connectome-kg; kg-rag[connectome]. Needs a store built with its vector index) |
swift | SwiftKG | Swift codebases -- classes, structs, protocols, extensions, methods, and their calls (swift-kg) |
typescript | TypeScriptKG | TypeScript and JavaScript codebases -- modules, classes, functions, methods, and their calls (tscode-kg) |
vault | VaultKG | Obsidian-style Markdown vaults -- notes, sections, tags, and the wikilinks, embeds and typed links (supports:: [[X]]) their authors wrote (vault-kg; kg-rag[vault]) |
Stub Adapters (protocol boundary, backends under development)
| Kind | Backend | Description |
|---|
ia | IABookKG | Internet Archive book corpus — public-domain books indexed by genre and topic |
pdbfile | — | PDB structure files — 3D atomic coordinates and protein metadata |
disulfide | — | Disulfide bond data — cysteine connectivity in protein structures |
verse | — | Scripture/verse — Book → Chapter → Verse hierarchy and cross-references |
person | — | Personal knowledge — biographical and relational graphs |
legal | — | Legal corpus — statutory codes and regulations (TBD) |
Corpus Abstractions
Generic Corpus — A named collection of any KG instances grouped for scoped federated queries. Useful for project-level or thematic groupings (e.g., "KGRAG_repos" combining code + doc KGs).
Person Corpus — A corpus enriched with personal metadata representing an individual. Aggregates all KGs relevant to a person — diaries, memories, documents, agent sessions, and more — alongside structured personal data (birth year, address, email, contact info).
Features
- Document ingestion —
kgrag ingest turns loose PDFs, Word documents, EPUBs, spreadsheets, slide decks and Markdown into a staged corpus, builds a KG over it, and registers the result in one command
- Multi-domain federation — Query code, docs, metabolic pathways, diary entries, and conversation history simultaneously
- Five-method adapter protocol —
is_available, query, pack, stats, analyze; add a new domain by implementing five methods
- Unified registry — Persistent SQLite-backed storage of KG locations, metadata, corpora, and person records
- Corpus abstraction — Group KGs into named corpora for scoped federated queries
- Person corpus — Model individuals with personal metadata and their associated KG collections
- Hybrid querying — Semantic seeding via sqlite-vec (legacy LanceDB stores still readable) + structural BFS traversal
- Context packing — Extract source-grounded snippets with line numbers for direct LLM ingestion
- MCP server — the fleet's five canonical tools across every registered KG, plus registry, corpus and person tools (24 in all), for any MCP-compatible agent
- CLI tooling — Full CRUD for KGs, corpora, and person corpora; query, pack, analyze, synthesize
- Streamlit dashboard — Interactive browser for exploring and querying registered knowledge graphs
- Deterministic retrieval — Auditable, source-grounded results; zero hallucination at the knowledge layer
Quick Start
pip install kg-rag
# With Streamlit dashboard
pip install 'kg-rag[viz]'
# With the common adapter backends (PyCodeKG, DocKG, MemoryKG).
# DocKG also backs every GutenbergKG corpus, which queries through it.
pip install 'kg-rag[kg]'
# DiaryKG, FileTreeKG, ConnectomeKG and VaultKG back kinds most registries
# never hold, so they have their own extras rather than riding along with [kg].
pip install 'kg-rag[diary]'
pip install 'kg-rag[filetree]'
pip install 'kg-rag[connectome]'
pip install 'kg-rag[vault]'
# With multi-format document ingestion (PDF, Word, PowerPoint, Excel, EPUB, ...)
pip install 'kg-rag[ingest]'
# Every extra
pip install 'kg-rag[all]'
# Ingest a folder of mixed-format documents: convert → build → register
kgrag ingest ~/Documents/specs --into ~/corpora/specs
# Register a Python codebase
kgrag register my-code code /path/to/my-repo
# Federated query across all registered KGs
kgrag query "authentication flow"
# Snippet pack for LLM ingestion
kgrag pack "database connection setup" --out context.md
# Launch the dashboard
kgrag viz
→ Full installation guide · Usage guide · CLI reference
MCP Integration
KGRAG ships a built-in MCP server, on the fleet's shared base kg_utils.mcp, for any MCP-compatible agent (Claude Code, Cursor, GitHub Copilot, Claude Desktop):
kgrag mcp
{
"mcpServers": {
"kgrag": {
"command": "kgrag",
"args": ["mcp"]
}
}
}
It answers the fleet's five canonical tools (stats, query, pack, get_node, neighbors) across every registered KG, with node ids of the form <kg>::<node id>, plus list_kgs and kg_info, 8 corpus tools and 9 person-corpus tools: 24 in all. kgrag mcp --manifest prints them.
→ Full MCP reference
Documentation
Related Projects
| Project | Description |
|---|
| PyCodeKG | Deterministic knowledge graph for Python codebases |
| DocKG | Semantic knowledge graph for document corpora |
| MetaboKG | Metabolic pathway knowledge graph |
| DiaryKG | Diary and personal journal corpus knowledge graph |
| AgentKG | Conversational memory knowledge graph |
| FTreeKG | File system tree knowledge graph |
| GutenbergKG | Project Gutenberg book corpus knowledge graph |
| MemoryKG (coming soon) | Episodic memory knowledge graph for conversation and event corpora |
| IABookKG (coming soon) | Internet Archive book corpus knowledge graph |
License
Elastic License 2.0 — see LICENSE.
Free to use, modify, and distribute. You may not offer the software as a hosted or managed service to third parties. Commercial internal use is permitted.
The Knowledge Compiler concept and its execution are the subject of a pending U.S. provisional patent application.
Citation
If you use KGRAG in your research or project, please cite it:
Suchanek, E. G. (2026). KGRAG: Knowledge Compiler and Federated Retrieval Layer (Version 0.18.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.20018524
@software{suchanek_kgrag,
author = {Suchanek, Eric G.},
title = {{KGRAG}: Knowledge Compiler and Federated Retrieval Layer},
version = {0.18.0},
year = {2026},
publisher = {Flux-Frontiers},
url = {https://github.com/Flux-Frontiers/KGRAG},
doi = {10.5281/zenodo.20018524},
}
