knowledge-graph-rdbms: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A label property graph (nodes, typed directed edges, labels, JSON properties) stored in SQLite. The core library has zero third-party dependencies — everything is stdlib + SQLite. Three front doors (Python library, kg CLI, MCP server) sit on one gated + logged engine, and a control plane (resolver.py + the backends/ package) lets all three address many named ontologies — each its own file (or, eventually, its own engine) — through one interface. See README.md for the full design narrative.

Commands

uv venv && uv pip install -e ".[dev]"   # set up dev env (installs pytest + mcp)

pytest                                   # run all tests (~62)
pytest tests/test_graph.py               # one file
pytest tests/test_graph.py::test_name    # one test
pytest -k events                         # by keyword

python bench/benchmark.py                # perf, full p50–p99 distributions
python bench/charts.py                   # render assets/*.png from bench data (needs [charts])
python bench/runtimes/compare.py         # CPython vs Node vs Bun SQLite comparison

kg stats                                 # default ontology (~/.kgrdbms/graph.db)
kg schema                                # observed vocabulary: kinds, edge types, labels, keys-per-kind
kg schema --samples                      # + example ids and enum-like property values per kind
kg ontology list                         # the registry (the "db of dbs")
kg ontology create coffee --stance inferential   # register a named ontology
kg --ontology coffee node add drink:latte --kind Drink   # route to it (resolver)
kg fed schema                            # union vocabulary across ALL ontologies (multithreaded fan-out)
kg fed node person:ada                   # find an id across the federation (identity-aware)
kg link add coffee drink:latte ENJOYED_BY people person:ada   # cross-ontology edge (backbone)
kg link same-as people person:ada wiki person:ada-lovelace    # assert same real-world entity
kg prefix add person https://kg.local/person/   # CURIE prefix -> IRI (identity backbone)
kg --db /tmp/x.db node add a:1 --kind T  # raw escape hatch: exact file, no registry
kg serve                                 # run the MCP server (needs [mcp] extra)