kg-rag 0.17.0

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

Stub Adapters (protocol boundary, backends under development)

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 — 22 tools exposing registry, corpus, and person operations to 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 exposing 22 tools to any MCP-compatible agent (Claude Code, Cursor, GitHub Copilot, Claude Desktop):

kgrag mcp

{
  "mcpServers": {
    "kgrag": {
      "command": "/path/to/venv/bin/kgrag",
      "args": ["mcp"]
    }
  }
}

Tools span three groups: core KG (kgrag_stats, kgrag_list, kgrag_info, kgrag_query, kgrag_pack), corpus (8 tools), and person corpus (9 tools).

→ Full MCP reference

Documentation

Related Projects

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.17.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.17.0},
  year      = {2026},
  publisher = {Flux-Frontiers},
  url       = {https://github.com/Flux-Frontiers/KGRAG},
  doi       = {10.5281/zenodo.20018524},
}