kglite - Moses Yebei

The Problem

Modern LLM agents need fast, queryable knowledge graphs that can be embedded in an application without deploying a separate database service. Existing solutions either require a running Neo4j instance or expose only a REST API, adding latency and operational overhead. A self‑contained, Cypher‑queryable graph that ships with both Rust and Python bindings eliminates those bottlenecks.

What This Does

KGLite implements an embedded graph engine that can be used directly from Rust or Python. The engine stores vertices, relationships, and properties in memory or on disk, supports Cypher queries, and exposes a lightweight MCP server for agent interactions. The same binary can be bundled in a Python wheel or a Rust crate, letting developers embed the graph in any distribution.

Key components:

crates/kglite-c/src/lib.rs – Rust library exposing the core graph API.
crates/kglite-bolt-server/src/main.rs – Bolt‑compatible server that serves Cypher over TCP.
crates/kglite-cli/src/main.rs – CLI tool for graph manipulation and querying.
kglite/ – Python package providing a thin wrapper around the Rust library (kglite.KnowledgeGraph).
kglite-mcp-server – bundled MCP server that can be started from the wheel (kglite-mcp-server --graph path.kgl).

How It Is Wired

Execution begins in the CLI or MCP binary.

CLI: crates/kglite-cli/src/main.rs parses arguments, loads a graph file via kglite::Graph::load, then calls kglite::Graph::cypher which delegates to kglite::Engine::execute.
MCP: crates/kglite-mcp-server/src/main.rs starts an async runtime, registers HTTP routes, and on a request to /cypher calls kglite::Graph::cypher in the same way.
Rust Library: crates/kglite-c/src/lib.rs contains pub fn execute(&self, query: &str) -> ResultView, which parses Cypher, walks the graph structure, and returns a lazy ResultView.
Bolt Server: crates/kglite-bolt-server/src/main.rs listens on a TCP port, accepts Bolt frames, and forwards Cypher strings to kglite::Engine::execute.
Persistence: kglite::Graph::save writes a binary format via kglite::engine::Serializer. Reading uses the same serializer.

The widest blast radius is the execute function in kglite-c/src/lib.rs; it is the single point where query parsing, graph traversal, and result materialization occur. Changing it affects all consumers. The kglite-mcp-server/src/main.rs is a thin wrapper that only routes HTTP/Bolt requests to that function.

How To Use It

Setup

# Clone
git clone https://github.com/moses-y/kglite
cd kglite

# Build Rust crates (requires Rust 1.75+)
cargo build --release

# Install Python wheel
pip install --no-build-isolation kglite  # uses prebuilt wheel

Configuration No external config files are required. The MCP server reads the graph path from the command line (--graph). The Rust library has no env vars.

Running

# Start MCP server with a pre‑built graph
kglite-mcp-server --graph examples/demo.kgl

# Or use the CLI to query a graph
kglite-cli --graph examples/demo.kgl cypher "MATCH (p:Person) RETURN p.name"

Python usage follows the README example: instantiate kglite.KnowledgeGraph(), load data, and run graph.cypher(...).

Real-World Use

A data‑science platform can ship a lightweight knowledge base with analytics notebooks. The notebook author writes Python code that loads a pre‑built demo.kgl and performs Cypher queries, all in‑process. An LLM agent can be given the same file and use the bundled MCP server to answer user questions without setting up Neo4j on the host.

Code Health & Issues

Severity (Low) – No structural red flags detected – tests/CI/license/lockfile present.
Severity (Low) – MIT license applies – all crates and Python wheel are MIT‑licensed.
Severity (Low) – No hard dependencies on external services – the core engine has no network calls except the optional MCP server.

No critical bugs or missing documentation were detected by the static analysis. Automated tests cover 1974 test files across Rust and Python.

The Bottom Line

KGLite offers a pragmatic, zero‑dependency graph engine for Rust and Python. Its bundled MCP server and CLI make it easy to embed or run as a lightweight service. The codebase is well‑structured, heavily tested, and MIT‑licensed, making it suitable for production workloads that require fast, in‑process graph queries.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

3,113 files

Rust1066
Python808
JSON292
Markdown242
Java103
YAML23

ReactFlaskExpressSpringDockerTransformerspandasNeo4j

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["tests 538 modules"] g1["dev-docs 60 modules"] g2["scripts 38 modules"] g3["crates 25 modules"] g4["benchmarks 18 modules"] g5["kglite 11 modules"] g6["examples 11 modules"] g0 -->|16| g5 g0 -->|9| g2 g0 -->|4| g4 g1 -->|3| g5

Module dependencies

The 10 most depended-upon modules of 702, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_kglite_blueprint___init__["__init__"] n1_kglite_node___test___helpers["helpers"] n2__competitive_graphsuite_base["base"] n3_ipts_benchmark_qualification["benchmark_qualification"] n4_mpetitive_graphsuite_dataset["dataset"] n5_petitive_graphsuite___init__["__init__"] n6_tests_value_assertions["value_assertions"] n7_tests_bolt_raw["bolt_raw"] n8_ipts_check_cypher_clean_room["check_cypher_clean_room"] n9_tests_test_retrieval_options["test_retrieval_options"] n2__competitive_graphsuite_base --> n4_mpetitive_graphsuite_dataset

Dependencies

18 declared dependencies, none a major version behind. Resolved 0 of 18 against the registry.

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium3

Upgrade the pinned dependency carrying a published advisoryhigh2 occurrences

rustls@0.23.22 GHSA-2mjx-qc3c-rqvc (medium) +1 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Stop discarding the exit code of steps whose failure mattershigh

.github/workflows/ci.yml

lines 399 discard failure

The job reports green while the artifact it was supposed to produce was never produced, so a crash becomes a successful run built on stale data.

Fix: Let the step fail, or test the specific expected condition instead of discarding all exit codes.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/release.yml

line 445 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium2 occurrences

crates/kglite-bolt-server/Dockerfile

rust:bookworm, debian:bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.