GenealogyKG

A knowledge graph over GEDCOM family-history files: people, families, events, places and sources as nodes, lineage as edges, and a sqlite-vec index for natural-language search. Built on the KGRAG fleet's shared kgmodule-utils SDK, so it federates with the other knowledge graphs and speaks the fleet's temporal contract.

See docs/USAGE.md for the complete guide -- every CLI command, the MCP server's tool reference, the curated corpus, and the living-person privacy model, with real examples.

Author: Eric G. Suchanek, PhD -- Flux-Frontiers, Liberty TWP, OH

Status: pre-alpha. build, query, pack, analyze, status, ASCII lineage trees (ancestors/descendants), KGRAG federation, the place hierarchy, the living-person filter, snapshots, the 2-D viz charts and the 3-D quilt/viz3d renderer all work end to end (Phase 1-5). Since then: a curated, committed corpus (corpora/entries/, 97 trees across 10 genres) with genkg corpus survey/ingest to build and register it; bounded, normalized CLI and MCP inputs; deterministic resource cleanup and an MCP shutdown hook; a full MCP behavioral test suite and an enforced coverage floor; and field parity with kg-rag's own federation adapter. 0.3.0 adds the hourglass 3-D tree (ancestors as roots, descendants as canopy, every limb a kinship edge) and export-web/export-swift, the data files The Knowledge Press: The Family reads. See docs/DESIGN.md for the phased build history.

Overview

GenealogyKG reads a GEDCOM 5.5 or 5.5.1 file and builds:

• a SQLite graph (.genealogykg/graph.sqlite) with person, family, event, place and source nodes linked by CHILD_IN, SPOUSE_IN, PARENT_OF, MARRIED_TO, HAS_EVENT, OCCURRED_AT, CITES and WITHIN (place hierarchy: Cincinnati, Hamilton, Ohio, USA is WITHIN Hamilton, Ohio, USA, and so on up to USA) edges
• a sqlite-vec index (.genealogykg/vectors.sqlite) over a prose summary of every record, so "chemists born in Cincinnati" finds Robert Hartwell
• occurred_start / occurred_end metadata derived from birth, death and marriage dates, so a federated KGRAG query can scope the graph by time

pack returns the original GEDCOM record behind each hit, with line numbers. The source file is read in place and never copied into the store.

Quick start

pip install genealogy-kg

# Build the graph (creates .genealogykg/ in the current directory)
genkg build --source family.ged

# Search
genkg query "emigrated from Yorkshire"

# Source-grounded snippets for an LLM context window
genkg pack "Hartwell marriages" --output context.md

# Lineage walks
genkg ancestors I7 --generations 3
genkg descendants I1

# Family trees as self-contained HTML (needs the `viz` extra)
genkg viz I1 --output tree.html
genkg viz I1 --view network --color-by generation --output family.html

# A 3-D family tree: ancestors as roots below the ground, descendants as the
# canopy above (needs the `viz3d` extra)
genkg viz3d I7
genkg quilt I7 --ancestors 3 --descendants 2

# Data files for The Knowledge Press: The Family. Both refuse unless the store
# was built with the living-person filter on (see "Living people" below).
genkg export-web --out family-web --living-cutoff 100
genkg export-swift --out family-swift --living-cutoff 100 --embedder-from <dir>

# Generation depth, surnames, date coverage, people with no family links
genkg analyze

# Point-in-time metrics, tracked in git
genkg snapshot save
genkg snapshot list

# MCP server for Claude Code and other MCP clients
genkg-mcp --repo .

# No GEDCOM of your own? Build one of the 97 curated trees shipped in this
# repo -- see "The curated corpus" below.
genkg corpus ingest --genre samples --no-register
genkg descendants I0001 --repo corpora/entries/samples/bronte   # the Brontë family

Installation

From PyPI

pip install genealogy-kg
pip install "genealogy-kg[adapter]"   # + kg-rag, for KGRAG federation
pip install "genealogy-kg[viz]"       # + plotly/pyvis, for `genkg viz`
pip install "genealogy-kg[viz3d]"     # + PyVista/PyQt5, for `genkg quilt`/`viz3d`

Local development

git clone https://github.com/Flux-Frontiers/genealogy_kg.git
cd genealogy_kg
poetry install --with dev
poetry run pytest

Dev tooling is a Poetry group, not an extra: pip install genealogy-kg[dev] does not exist. To also get the dockg and pycodekg CLIs that index this repo itself, run poetry install --with dev,kg.

Configuration

genkg build --source records the file it used in .genealogykg/config.json; later builds reuse it. To pin sources in the project instead, list them in pyproject.toml:

[tool.genealogykg]
sources = ["family.ged"]

.gitignore excludes *.ged outside tests/fixtures/. GEDCOM exports contain personal data about living people; keep them out of version control.

Living people

Before sharing a store, turn on the living-person filter and rebuild:

[tool.genealogykg]
sources = ["family.ged"]
living_cutoff_years = 100
unknown_birth_policy = "redact"

Anyone with no death or burial record who was born within the last 100 years is then stored as a bare person node named Living: their lineage edges and sex are kept so trees still walk through them, but their name, dates, events, notes and citations are dropped, and their name is withheld from every family, spouse and parent mention too. A family with a living spouse keeps its members but not its marriage details.

unknown_birth_policy controls records that have neither a usable birth date nor a death/burial record. The default, "keep", preserves historical data completeness and existing behavior. The conservative "redact" mode withholds those uncertain records; this may also hide historical people whose dates are simply incomplete. A death or burial record always counts as affirmative evidence that the person is not living.

pack reads the GEDCOM file in place, so share the .genealogykg/ store without the .ged file.

export-web and export-swift never trust the store. Each re-reads the GEDCOM under its own cutoff (--living-cutoff, default the pyproject value; --unknown-birth defaults to redact) and refuses if the store holds anyone that cutoff treats as living under anything but Living. After writing, each scans its own output for those people's real names and refuses again on a hit, so a note in a dead relative's record that names a living child stops the export instead of shipping. A name a dead ancestor also bears cannot be scanned for, since the ancestor's own page carries it. --include-living skips both checks, for a private copy only, and is recorded in the output.

Git hook

genkg install-hooks writes a pre-commit hook that runs the repo's pre-commit checks on every commit. Set GENKG_SNAPSHOT=1 on a commit to also rebuild the store and save a snapshot; that is off by default because a snapshot staged into the commit it describes can never carry that commit's tree hash.

The curated corpus

corpora/entries/<genre>/<slug>/*.ged is a committed, curated set of 97 public GEDCOM trees across 10 genres (royalty, US presidents, corporations, fictional characters, and more) -- unlike the benchmark corpora below, these ship in the repo and are safe to build against directly, since safety is enforced at the query/pack/MCP boundary rather than by curating which files are let in. See corpora/entries/NOTICE.md for provenance and licensing.

genkg corpus survey                    # which entries are built, by genre
genkg corpus ingest --genre samples    # build (and register with KGRAG)

See docs/USAGE.md for the full genkg corpus reference.

Benchmark corpora

./scripts/fetch_corpora.sh downloads public GEDCOM files (the 1992 European royalty file, the US presidents file, the GEDCOM 5.5 torture test, and a 200,000-person scale benchmark) into the gitignored corpora/ directory -- everything under it except corpora/entries/, which is committed. docs/CORPORA.md lists each file, its provenance and licence, and what it exercises.

Storage

.genealogykg/
  graph.sqlite     nodes and edges
  vectors.sqlite   sqlite-vec index (BAAI/bge-small-en-v1.5, 384-d)
  snapshots/       point-in-time metrics, tracked in git
  config.json      source path used by the last build

KGRAG federation

GenealogyKG registers with kg-rag as kind genealogy (KGKind.GENEALOGY) -- genkg corpus ingest is the usual way entries get registered. Once registered, kgrag query and kgrag pack include people, families and events from every registered GenealogyKG store alongside the fleet's other knowledge graphs, and a federated query can scope by time using the occurred_start/occurred_end metadata derived from birth, death and marriage dates.

Citation

Suchanek, E. G. (2026). GenealogyKG: Genealogical Knowledge Graph
(Version 0.3.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22182369

@software{suchanek_genealogykg_2026,
  author    = {Suchanek, Eric G.},
  title     = {GenealogyKG: Genealogical Knowledge Graph},
  year      = {2026},
  version   = {0.3.0},
  url       = {https://github.com/Flux-Frontiers/genealogy_kg},
  doi       = {10.5281/zenodo.22182369},
}

License

Elastic License 2.0. See LICENSE.