Knowledge Graph RDBMS

knowledge-graph-rdbms

An embedded knowledge graph you own completely — in one SQLite file.

SQLite-native · zero-dependency core · MCP-ready · event-sourced · reversible.

Model anything as entities and relationships — agent memory, app ontologies, declarative datasets, "SQLite but my data is a graph" — without running Neo4j, RDF, Docker, or a separate graph service. No Cypher, no JVM, no server: five tables and one file you can copy, inspect, and version.

pip install "knowledge-graph-rdbms[mcp]"

write a fact — auto-creates the graph in one SQLite file

kg node add person:ada --kind Person --name "Ada Lovelace"

every write is logged; tail the log and roll any event back by id

kg events -n 5 kg revert

rebuild the graph as of any past moment — literal time travel

kg replay --upto 2026-01-01T00:00:00

expose the whole graph to an AI agent over MCP

kg serve

Agent / CLI / Python │ gated + logged writes │ SQLite label property graph │ replay · revert · time-travel

Python 3.10+ · MIT · zero-dependency core · library + CLI + MCP

The world isn't rows in a table — it's *things*, the kinds of things they are, and how they relate. A label property graph captures exactly that, and not much more: nodes (entities), typed edges (relationships), labels (sets), and JSON properties (everything else). There's no schema to design up front; meaning accretes as facts, and the shape stays as flexible as the domain it describes.

That flexibility is what makes it a natural substrate for AI agents. Hand an agent an MCP connection to this graph and it can do what agents are uniquely good at: read a domain, model what it learns, connect ideas, and reason over *structure* instead of prose. Every write is gated, attributed, and appended to an event log — so an agent can reshape the graph freely while you keep the receipts: audit it, replay it to any point in time, or roll a change back with one command. A memory that records *why*, not just *what* — in one embeddable file that travels wherever the agent runs: a laptop, a CI job, a serverless function, a Pi.

Small enough to hold in your head. Flexible enough to model anything.

Contents

• Where it fits
• Why not X?
• The idea in 30 seconds
• Design philosophy
• The data model
• Architecture: three front doors, one engine
• Many ontologies: one control plane
• Discovery: read the schema before you query
• Cross-ontology: federation and the backbone
• Event sourcing: the graph is a projection
• The safety gate: invariants vs. policy
• Install
• Quickstart
• Performance
• RDF interop: export, SPARQL, RDF-star
• Command reference
• Project layout
• Development
• License

Where it fits

It's built for graphs you want to own completely — small enough to inspect, fast enough to embed, transparent enough to trust:

• Embedded ontologies — a knowledge graph that ships inside a single app or service, in one file you can copy and version.
• Agent & assistant memory — facts an AI can read and write over MCP, with a full audit trail and one-command rollback.
• Declarative datasets — describe your base graph as YAML/JSON facts and replay them into a queryable graph, deterministically.
• "SQLite, but my data is a graph" — the moment relational rows start describing relationships, this is their natural home.

The design center is read-heavy, single-writer, up to low millions of nodes — the same sweet spot as SQLite itself: one file, in-process, no server to run. That covers a surprising amount of real work. For workloads past that center, Performance maps out exactly where the curve bends and a purpose-built graph engine starts to earn its extra moving parts.

Why not X?

Honest comparisons — reach for the right tool, and know exactly when that tool is this one.

Why not Neo4j?

Use Neo4j when you need deep traversal, complex Cypher pattern matching, concurrent writers, or clustered graph infrastructure. Use kgrdbms when you want a small embedded graph, agent memory, auditability, local-first ownership, and SQLite deployment simplicity.

Why not NetworkX?

NetworkX is great for in-memory algorithms. kgrdbms is for persistent graph state with durable storage, CLI/MCP access, event history, and rollback.

Why not RDFLib?

RDFLib is for RDF graphs and linked-data workflows. kgrdbms is a label property graph with RDF as an export/import boundary, not a triplestore.

Why not just SQLite tables?

Because some domains are naturally entities and relationships, not rectangular tables. kgrdbms keeps the storage boring while making the model graph-shaped.

The idea in 30 seconds

A label property graph needs only four primitives:

Store those in SQLite, add a few indexes, and you have a knowledge graph. Everything else in this project — traversal, an append-only history, a safety gate, the CLI, the MCP server — is built on top of those four facts.

from kgrdbms import Graph

with Graph(path="demo.db") as g: g.add_node("person:ada", kind="Person", name="Ada Lovelace", labels={"Person"}, properties={"born": 1815}) g.add_node("field:cs", kind="Field", name="Computer Science") g.add_edge("person:ada", "field:cs", "FOUNDED", properties={"year": 1843})

print(g.shortest_path("person:ada", "field:cs"))

flowchart LR

ada(["person:ada :Person born=1815"]) cs(["field:cs :Field"]) ada -->|"FOUNDED (year=1843)"| cs

Design philosophy

1. Boring storage is a feature. SQLite already solved durability, transactions, indexes, and recursive queries. We don't reinvent any of it. One file, copy it to back it up, open it with any SQLite tool to inspect it.

2. The schema fits on a screen. Five tables, no surprises. You can read the entire storage layer and know exactly where every fact lives. Legibility beats cleverness.

3. The state is a pure function of data. What you query is a *projection*. The source of truth is an append-only log of facts plus an optional declared seed. Your whole graph is reproducible: state = replay(seed + log). That one property buys audit, undo, and time-travel for free.

4. Mutation is gated, and the gate has two layers. When you let an agent rewrite your graph over a wire, you need rules. Some rules are *configurable* (policy); some must be *un-negotiable* (compiled-in invariants). We separate mechanism from policy on purpose.

5. One engine, many doors. A library call, a kg command, and an MCP tool all flow through the same gated, logged write path into the same file. There is no "CLI version" of the truth and "MCP version" of the truth — there's one.

6. Pay for speed only when you ask. Every single write commits on its own (safe by default). Bulk paths (batch(), add_nodes, add_edges) let you opt into ~10× throughput when you mean to.

The data model

The graph is five tables. That's the whole storage layer.

erDiagram

nodes ||--o{ node_labels : "is labeled" nodes ||--o{ node_properties : "has" nodes ||--o{ edges : "from / to" edges ||--o{ edge_properties : "has"

nodes { text id PK text kind text name text created_at } node_labels { text node_id FK text label } node_properties { text node_id FK text key text value_json } edges { text id PK text from_node FK text to_node FK text type } edge_properties { text edge_id FK text key text value_json }

Design notes that matter:

• Edges are unique on `(from_node, type, to_node)`. Re-adding the same triple updates its properties instead of duplicating it. Idempotent by construction.
• Properties are JSON. Values round-trip as whatever JSON type you store — ints, bools, lists, nested objects.
• Foreign keys cascade. Delete a node and its labels, properties, and incident edges go with it, enforced by SQLite.
• `slug()` deduplicates natural-language ids. Two strings that slugify the same become the same node — the load-bearing trick for turning prose concepts into stable ids.
• Ids are CURIEs. person:ada-lovelace, company:apple — a compact URI: prefix:reference, where the prefix is a short stable type token and the reference is slugged (slug(name, prefix="person") mints them). It stays a plain string today and expands to a full IRI *only* the day you publish to the linked-data world, so interop is a cheap, additive option rather than a tax paid up front. The id is an *address*, not a record: identity goes in the id, changeable facts go in properties.

A sixth table, graph_events, holds the append-only history (see below). It shares the same file and connection.

Architecture: three front doors, one engine

flowchart TD

subgraph doors["front doors"] CLI["kg (command line)"] MCP["kgrdbms-mcp (MCP server)"] LIB["import kgrdbms (library)"] end

SVC["service.py — gated + logged write path"] GATE{"invariants.enforce then policy.mutation_check"} GRAPH[("SQLite file nodes · edges · labels · properties")] LOG[["graph_events (append-only log)"]]

CLI -->|writes| SVC MCP -->|writes| SVC LIB -->|writes| SVC SVC --> GATE GATE -->|"pass"| GRAPH GATE -->|"record fact"| LOG

CLI -.->|reads| GRAPH MCP -.->|reads| GRAPH LIB -.->|reads / fast bulk writes| GRAPH

The CLI, the MCP server, and your own Python code all mutate through service.py, so the safety gate and the event-log bookkeeping exist in exactly one place and can't drift between front doors.

The gate resolves invariants.enforce and policy.mutation_check *through their modules at call time* — so editing your policy (or monkeypatching it in a test) takes effect across every door at once.

The library also has a direct, fast, unlogged path (g.add_node(...),

g.add_nodes(...)). It's the right tool for bulk loading, but those writes

are