KGLite — Knowledge graph for Python, built for LLM agents

KGLite is an embedded, Cypher-queryable knowledge graph for Python,
built so you can hand it to an LLM agent. pip install kglite and
point kglite.code_tree.build(".") at any source directory — your
first queryable graph in seconds. It ships with a bundled MCP server,
a describe() method that emits a system-prompt-shaped schema, and
structural validators that compose with Cypher.

kglite is a pure-Rust knowledge graph engine
(crates/kglite)
packaged for Python via pip install kglite. The interactive shell,
Bolt-server, and MCP-server binaries are sibling Rust crates wrapping
the same engine. If you want kglite as a Rust library — without the
Python wheel in your build — see Use from Rust below.

Interactive shell. pip install kglite-cli (or cargo install kglite-cli) gives you kglite — a sqlite3-style REPL: kglite app.kgl
opens a Cypher prompt with .import, .dump, .schema, multi-line input,
and tab-completion. It's a separate lightweight package, so the core
kglite wheel stays library-only.

Codebase → Claude

examples/codebase_to_claude_mcp.ipynb
clones a GitHub repo, parses it into a code knowledge graph, and
registers a workspace MCP server in Claude Desktop.

SEC filings → graph

from kglite.datasets.sec import SEC
g = SEC.fetch("./sec", "13F-HR", "TSLA", years=2,
              user_agent="Your Name [email protected]")

SEC.fetch downloads the named forms for the named companies and
returns a Cypher-queryable graph — Form 4 insider transactions,
13F holdings, SC 13D stakes, DEF 14A board composition, 8-K events.
→ examples/sec_to_claude_mcp.ipynb
· SEC guide.

Use cases

The same agent-facing surface works whether the graph holds legal
precedents, a Wikidata slice, a SQL warehouse, a RAG corpus, or a
parsed codebase.

• 🏦 SEC EDGAR. SEC.fetch(path, forms, companies, years=2)
  builds a US-public-company graph from the SEC's free data: insider
  transactions (Form 4), institutional holdings (13F), activist
  stakes (SC 13D), board composition (DEF 14A), 8-K events — with
  XBRL financials and Exhibit 21 subsidiaries via SEC.open. →
  SEC guide.
• 🏛️ Domain knowledge for agents. Legal precedents + citations,
  regulatory rules, medical ontologies, manufacturing BOMs, scientific
  catalogues — anything with structure becomes a queryable graph an
  MCP-capable agent can reason over. See the
  legal-graph example
  for a Norwegian-Supreme-Court walk-through (laws + decisions +
  citation edges + judge metadata).
• 📊 Business data → queryable graph. Any tabular source — SQL,
  CSV, Parquet, REST API responses, pandas DataFrames — goes straight
  in via add_nodes(df, ...) and add_connections(df, ...). Layer a
  graph on top of your warehouse and the agent reasons over the
  relationships without you writing a server. →
  Data Loading guide.
• 🌐 Public datasets. wikidata.open(path) and sodir.open(path)
  handle the fetch + build + cache cycle. Mapped and disk storage
  query graphs that don't fit in RAM — a billion-edge Wikidata graph
  on a 16 GB laptop. → See Bundled datasets
  below.
• 📚 RAG with structure. Documents, chunks, entities, and the
  edges between them in one graph. Combine text_score() vector
  similarity with Cypher traversal — "find court cases semantically
  similar to my fact pattern, then walk one hop to related
  precedents" — hybrid retrieval in one query, no second vector DB.
  Scale to large corpora with an opt-in HNSW index
  (build_vector_index()).
  → Semantic Search guide.
• 📂 Codebase analysis. kglite.code_tree.build(".") parses 13
  languages into Function / Class / Module / Route nodes with
  web-framework route detection (Flask, FastAPI, Django). Build from
  any git revision, or merge several into one multi-revision graph for
  structural diffs (rev= / revs=[…], code_tree.diff). See the
  notebook above
  for the full code → Claude Desktop workflow. →
  Code analysis guide.
• 🤝 A shared graph as an agent contract. One .kgl can be the
  two-way contract between collaborating agents (e.g. a research agent
  that batch-rebuilds specs and coding agents that plan and mutate
  status live). The primitives that make this safe are first-class:
  ownership layers (define_schema(layer='managed'|'runtime') +
  add_nodes(managed_reload=True) so a rebuild provably can't clobber
  agent-owned nodes), role-scoped writes
  (cypher(..., write_scope=[...]) rejects out-of-scope CREATE/SET), a
  verbatim instructions slot at the top of describe()
  (set_instructions(text)), native list properties, JSON-native
  ingestion (from_records(spec)), and a dependency frontier
  (CALL ready_set(...)) to find the next actionable work. Keep the
  graph general — these are small, opt-in building blocks, not a baked-in
  workflow.
• 🧠 Markdown knowledge bases & agent memory. kglite.okf.build(dir)
  ingests an Open Knowledge Format
  bundle — or a Claude memory dir, skills folder, or Obsidian vault — into a
  graph: frontmatter → node properties, markdown links → typed edges. Then
  cluster it (CALL leiden), find orphaned or stale notes, and surface dangling
  references — the query engine OKF itself doesn't ship. →
  OKF guide.

Why Cypher?

Questions over connected data — which insiders sold this stock, who
sits on two boards, what cites this case — are pattern matches. In
SQL they become multi-table joins; in Cypher the pattern is the
query:

-- Insider sells, most recent first
MATCH (t:InsiderTransaction {direction: 'sale'})-[:BY_INSIDER]->(p:Person)
MATCH (t)-[:IN_COMPANY]->(c:Company)
RETURN p.title, c.title, t.shares, t.price_per_share
ORDER BY t.transaction_date DESC LIMIT 10

Cypher pays off most when the data has real structure and your
questions traverse it.

How it compares

Pick KGLite when you want Cypher + Python ergonomics + LLM-agent
plumbing in one wheel — embedded, in-process, with the Cypher
surface (subqueries, path-finding,
vector + text search, graph algorithms) you'd expect from a columnar
graph DB, plus a code-graph parser, bundled datasets, and an MCP
server none of them ship. Pick a columnar OLAP graph engine if
your workload is heavy analytical scans over a mostly-static graph and
you don't need the Python/agent ergonomics. Pick NetworkX when you
need its enormous graph-algorithm library and your data fits in RAM.
Pick rustworkx when you want NetworkX's API in Rust with no query
language. Pick Neo4j Embedded when you've standardised on
server-mode Cypher and want the in-process driver for tests.

📊 Benchmarks → — wall-to-wall time per topic (load,
filter/aggregate, traversal, pathfinding, algorithms, mutations) against
other embedded graph engines, NetworkX, rustworkx, igraph, and DuckDB on
one shared synthetic graph. Reproduce with python benchmarks/benchmark.py.

Quick Start

# Python (the headline distribution path)
pip install kglite

# Optional extras
pip install 'kglite[pandas]'   # DataFrame loading used in the walkthrough below
pip install fastembed            # (or sentence-transformers) embedding models for text_score() — bring your own
pip install 'kglite[neo4j]'      # Neo4j Python driver for Bolt-server tests

import pandas as pd
import kglite

# Three storage modes — pick by graph size:
#   default (in-memory)   — small/medium graphs, fastest queries
#   storage="mapped"      — mmap columns, RAM-friendly as you grow
#   storage="disk", path=…  — 100M+ nodes, Wikidata-scale, loaded lazily
graph = kglite.KnowledgeGraph()

# Bulk-load nodes from a DataFrame.
people = pd.DataFrame({
    "id":   ["alice", "bob", "eve"],
    "name": ["Alice", "Bob", "Eve"],
    "age":  [28, 35, 41],
    "city": ["Oslo", "Bergen", "Trondheim"],
})
graph.add_nodes(people, node_type="Person", unique_id_field="id", node_title_field="name")

# Bulk-load relationships the same way.
knows = pd.DataFrame({"src": ["alice", "bob"], "tgt": ["bob", "eve"]})
graph.add_connections(knows, connection_type="KNOWS",
                      source_type="Person", source_id_field="src",
                      target_type="Person", target_id_field="tgt")

# Query — returns a ResultView (lazy; data stays in Rust until accessed).
for row in graph.cypher("""
    MATCH (p:Person) WHERE p.age > 30
    RETURN p.name AS name, p.city AS city
    ORDER BY p.age DESC
"""):
    print(row['name'], row['city'])

# Or get a pandas DataFrame directly.
df = graph.cypher("MATCH (p:Person) RETURN p.name, p.age ORDER BY p.age", to_df=True)

# Persist to disk and reload. save() is atomic + fsync by default (crash-safe —
# no torn file); load() raises a typed kglite.FileFormatError on a corrupt file.
graph.save("my_graph.kgl")
loaded = kglite.load("my_graph.kgl")

# Or serialize to/from bytes (no filesystem path):
blob = graph.to_bytes(); loaded = kglite.from_bytes(blob)

# Share read-only across threads with an immutable, lock-free snapshot:
snapshot = graph.freeze()        # concurrent snapshot.cypher(...) from many threads

# No data yet? Generate a realistic demo graph in one line (bundled, no extra deps):
demo = kglite.graphgen("medium")               # ~25k nodes, ready to query
# kglite.graphgen("huge", out="/tmp/g")        # stream millions of nodes to CSV, bounded memory

→ Getting Started guide ·
Cypher reference ·
API reference.

Prefer a runnable file? examples/csv_to_graph.py
loads real CSVs end to end.

Serve it to an agent

Three levels of effort, three levels of capability.

1. One command — any .kgl becomes an MCP server

kglite-mcp-server --graph path/to/graph.kgl

The server exposes cypher_query, graph_overview, schema
introspection, structural validators, and source-file tools over MCP
stdio. Drop it into Claude Desktop / Cursor / any MCP-capable client
and your graph is queryable. Works on every graph kglite can build —
your own, Wikidata, Sodir, code-tree.

When you register it, point command at the absolute path to the
binary (/abs/path/to/venv/bin/kglite-mcp-server), not a bare name — a
bare command can silently launch an older PATH-shadowing install. Then
confirm it with kglite-mcp-server --selftest --graph path/to/graph.kgl,
which drives a real handshake and prints green/red per capability.

Two ready-made code-intelligence recipes ship in
examples/:

• Clone-and-explore GitHub repos —
  open_source_workspace_mcp.yaml:
  the agent calls repo_management('org/repo') to clone and build a
  code-tree graph on demand.
• Review a local directory —
  local_code_review_mcp.yaml:
  point it at a checked-out tree, set_root_dir(path) to swap roots,
  watch-mode auto-rebuild.

2. Customise with a YAML manifest

Drop <basename>_mcp.yaml next to the graph (e.g. wikidata_mcp.yaml
beside wikidata.kgl) and the server auto-loads it at boot.

name: Wikidata Explorer
source_root: /path/to/related/source        # exposes read/grep/list
trust:
  allow_embedder: true
extensions:
  embedder: { library: fastembed, model: BAAI/bge-small-en-v1.5 }  # enables text_score()
  csv_http_server: true                              # bulk CSV exports
tools:                                               # inline parameterised Cypher
  - name: who_invented
    cypher: |
      MATCH (i:Q5)-[:P61]->(t {label:$thing})
      RETURN i.label LIMIT 5

No fork required for most customisation. →
MCP server guide.

3. Teach the agent with bundled skills

Markdown skill files (<basename>.skills/*.md) ship methodology for
each tool. The agent reads cypher_query.md at session start to learn
your schema conventions, read_code_source.md to know when to drill
into source vs. query the graph, etc. Three layers compose:
kglite-bundled defaults + your project's .skills/ overrides +
operator-declared domain packs. Skills with applies_when: predicates
only activate when the graph contains the relevant node types — so a
non-code graph never sees read_code_source methodology.

Net effect: the agent comes pre-loaded with how to use your graph,
rather than discovering it through trial-and-error. →
AI Agents guide.

Bundled datasets

Three wrappers turn well-known public sources into queryable graphs
without writing a loader. Each handles the fetch + build + cache
cycle, returns a KnowledgeGraph you can cypher() against, and
respects a per-dataset cooldown so re-running just reloads the cached
graph in seconds. KGLite is independent of the upstream
organisations — see each module docstring for non-affiliation notes.
→ Datasets guide.

SEC EDGAR

US-public-company knowledge graph from the SEC's free public data —
all 14M historical filings + per-filing payload parsing for Form 4
(insider transactions), 13F-HR (institutional holdings), SC 13D
(activist stakes), DEF 14A (board composition), XBRL company facts
(financial metrics), 10-K Exhibit 21 (subsidiaries), 8-K cover pages
(material event Item codes):

from kglite.datasets.sec import SEC

# SEC.fetch — name the forms, the companies, a span; get a graph back.
g = SEC.fetch("/data/sec", ["4", "8-K", "DEF 14A"], ["AAPL", "TSLA"],
              years=2, user_agent="Your Name [email protected]")

# SEC.open — full control: separate filing-index vs. payload spans,
# storage mode, and the include_* flags (XBRL financials, Exhibit 21
# subsidiaries).
g = SEC.open("/data/sec", years=10, detailed=2,
             user_agent="Your Name [email protected]")

# Full universe — drop `companies`; auto-escalates to mode="disk".
g = SEC.open("/data/sec", years="all", detailed=5,
             user_agent="Your Name [email protected]")

Two dozen-plus typed node types — Company, Person, Filing,
InsiderTransaction, Holding, InstitutionalHolding, CorporateEvent,
Compensation, Role, MetricFact, Subsidiary and more — wired by typed
edges, every fact node tracing back to its source filing. Three-tier
raw / processed / graph/{mode} cache
— raw is immutable, processed regenerates only when its raw
source changes, graph/{mode}/ reuses on reopen unless
force_rebuild=True. SEC's 10 req/s fair-access policy is enforced
by an internal token-bucket rate limiter; the user_agent arg is
mandatory (SEC returns 403 without it).

Source data is public domain (US Govt work) — redistribute the built
.kgl however you like. →
SEC guide.

Wikidata

Single-stream latest-truthy.nt.bz2 from
dumps.wikimedia.org —
parallel-decoded with a bit-level block scanner, parsed, built into a
queryable graph in one call:

from kglite.datasets import wikidata

g = wikidata.open("/data/wd")                                    # full graph
g = wikidata.open("/data/wd", entity_limit_millions=100)         # 100M slice
g = wikidata.open("/data/wd", storage="memory",                  # in-memory, fast tests
                  entity_limit_millions=10)

Sodir (Norwegian Offshore Directorate)

Petroleum-domain example dataset — sodir.open("/data/sodir") returns
a queryable graph of fields, wellbores, discoveries, licences,
stratigraphy and 28 more node types from the public ArcGIS REST
FeatureServer at factmaps.sodir.no.
Built in ~30 s on first run, cached after. Useful as a worked example
of complement_blueprint (extend a baseline schema without touching
the canonical types) — → Datasets guide.

Recipes

Short patterns for the most-common shapes. Each is self-contained.

Hybrid semantic + structural retrieval

Combine vector similarity (text_score()) with Cypher pattern
matching in one query:

graph.cypher("""
    MATCH (c:Chunk)-[:IN_DOC]->(d:Document)
    RETURN c.text, d.title,
           text_score(c.embedding, $query_vec) AS score
    ORDER BY score DESC LIMIT 5
""", params={"query_vec": query_embedding})

Vector embeddings via a bring-your-own embedder — pip install fastembed (or
sentence-transformers) and pass it to g.set_embedder(...). → Semantic Search guide.

Structural validators — surface data-integrity gaps

Fourteen built-in CALL procedures find the gaps that aren't visible
from normal queries: orphan nodes, missing-required-edge violations,
two-step cycles, duplicate titles, parallel edges, cardinality
violations, more. They compose with the rest of Cypher.

# Wellbores in our sodir graph that lack a production licence
graph.cypher("""
    CALL missing_required_edge({type: 'Wellbore', edge: 'IN_LICENCE'}) YIELD node
    RETURN node.id, node.title
""")

missing_required_edge and missing_inbound_edge validate the
(type, edge) direction against the graph's actual schema and refuse
to execute when misused. → Full procedure list in the
Cypher reference.

Graph algorithms

Shortest path (BFS or Dijkstra), centrality, community detection,
clustering — all in Cypher:

graph.cypher("""
    MATCH path = shortestPath((a:User {name:'Alice'})-[*]-(b:User {name:'Eve'}))
    RETURN path
""")

→ Graph algorithms guide ·
Traversal patterns ·
Recipes index.

Use from Rust

The same engine is available as a pure-Rust crate — embed it in a
Rust binary without the Python wheel in your build:

# Cargo.toml
[dependencies]
kglite = "0.10"

use kglite::api::{load_file, session, Value};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let graph = load_file("my_graph.kgl")?;     // same .kgl as Python writes
    let params = HashMap::new();
    let opts = session::ExecuteOptions {
        params: &params, deadline: None, max_rows: None,
        lazy_eligible: false, disabled_passes: None, embedder: None,
    };
    let outcome = session::execute_read(
        &graph,
        "MATCH (p:Person) RETURN p.name LIMIT 5",
        &opts,
    )?;
    for row in &outcome.result.rows {
        if let Some(Value::String(name)) = row.first() {
            println!("{}", name);
        }
    }
    Ok(())
}

Zero PyO3 in the dependency tree:
cargo tree -p your-crate | grep pyo3 → empty.

• Rust quickstart
  — load + query + transaction examples.
• Embedding guide
  — workspace layout, the kglite::api::* surface, cgo / napi /
  JNI sketches.
• Session abstraction
  — binding-implementer reference for the canonical Cypher pipeline.
• API reference (docs.rs) — per-symbol Rust API docs.

The Bolt server (crates/kglite-bolt-server) and the Rust MCP
server (crates/kglite-mcp-server) are standalone binaries built
on the same engine — see the
Operators guide
for deployment.

For non-Rust language bindings (Go via cgo, JavaScript via napi,
JVM via JNI, .NET via P/Invoke), the
crates/kglite-c
crate exposes the engine through a stable C ABI — 30 extern "C"
functions covering lifecycle / Cypher / datasets / embedder, plus a
cbindgen-generated kglite.h. See
docs/rust/c-abi.md
for the design and
docs/rust/implementing-a-binding.md
for cgo / napi / JNI worked examples.

Examples

The examples/
directory has runnable, self-contained artifacts:

• codebase_to_claude_mcp.ipynb
  — clone an open-source repo, parse it into a code knowledge graph,
  register a workspace MCP server in Claude Desktop.
• sec_to_claude_mcp.ipynb
  — build a graph of SEC filings with SEC.fetch, query it, register
  it as a Claude Desktop MCP server.
• open_source_workspace_mcp.yaml
  — annotated workspace-mode manifest for the github-clone-tracker
  pattern. Walked through in the
  workspace manifest example.
• csv_to_graph.py
  — minimal pd.read_csv → add_nodes / add_connections walkthrough
  on a tiny org chart, with a few Cypher queries. The fastest way in.
• incremental_update.py
  — merge a second data snapshot into an existing graph with
  add_nodes(conflict_handling='update').
• legal_graph.py
  — end-to-end add_nodes / add_connections from pandas DataFrames,
  covering laws, regulations, court decisions with citation edges.
• code_graph.py
  — build a code knowledge graph from a source directory via
  code_tree.build.
• spatial_graph.py
  — declarative CSV→graph loading via a JSON blueprint; lat/lon
  coordinates and pipeline-path traversal queries.
• crates/kglite-mcp-server/
  — Rust-native single-binary MCP server (built on rmcp + the
  mcp-methods framework). Reach for it when the manifest doesn't
  express what you need; the binary is the reference for layering
  domain-specific tools on top of the generic surface.

Benchmarks

KGLite builds and queries Wikidata-scale graphs on a laptop. Measured
with benchmarks/wiki_benchmark.py
on an M-series MacBook.

Ingest — full pipeline from compressed N-Triples to a queryable graph:

Reloading a saved 1 B-triple graph from disk (7 GB on-disk): 3.5 s.

Query latency on the 1 B-triple graph (mapped storage):

Disk and mapped storage build at the same speed; mapped wins on
small-result queries (in-memory inverted index), disk wins on
unbounded typed traversals (sorted-CSR mmap I/O). No server, no
tuning, same Python process as your code.

Key Features

Quick reference. Each links into the appropriate guide.

Documentation

Full docs at kglite.readthedocs.io
— five tracks by audience.

Python track — pip install kglite

• Getting Started — installation, first graph, core concepts
• Cypher Guide — MATCH, MERGE, mutations, parameters, validators
• Data Loading — DataFrames in, DataFrames out
• Graph algorithms — shortest path, PageRank, community detection
• Semantic Search — embeddings, vector search, hybrid retrieval
• Code analysis — code_tree.build, framework route detection
• OKF ingestion — okf.build, markdown knowledge bases & agent memory
• Datasets — SEC, Wikidata, Sodir wrappers
• MCP server config — manifests, skills, extensions
• Spatial · Timeseries · Blueprints · Import/Export · Traversal & hierarchy · AI Agents
• Recipes index — copy-paste patterns for common shapes

Rust track — cargo add kglite

• Rust quickstart — load, query, transactions
• Embedding kglite — surface tour, language-binding sketches
• Session abstraction — pipeline + CoW transactions
• API manifest + per-symbol docs.rs

Operators — running the protocol servers

• Bolt server — Neo4j wire compat for cluster-aware drivers

Reference — cross-binding

• Cypher reference — the supported Cypher subset
• Fluent API reference — programmatic graph construction
• Python API (auto) — auto-generated from stubs

Concepts — architecture + contributor docs

• Architecture · Design decisions · Cypher conformance · Concurrency

Requirements

CPython 3.10+ | macOS (arm64/x86_64), Linux (glibc/musl; x86_64 and
best-effort aarch64), Windows (x86_64). The base wheel has no Python runtime
dependencies; integrations install their named extras. See the
artifact support policy
for the tested/build-only tiers, libc floors, PyPy status, and source-build
fallback.

Stability

KGLite is Beta software, versioned under SemVer.
The Python API surface and the supported Cypher dialect have been
largely stable across the 0.9 → 0.10 line; the occasional breaking
change (e.g. the 0.10.10 node-id semantics unification) is called out
prominently in the changelog. The Beta label reflects API maturity, not
engine reliability — the storage and query engine are covered by parity
oracles and a differential Cypher corpus on every change. Breaking changes
are announced in
CHANGELOG.md.

License

MIT — see LICENSE for details.