ConnectomeKG -- Connectomes as Knowledge Graphs

ConnectomeKG turns an electron-microscopy connectome into a queryable knowledge graph: every neuron a node, every edge a counted synapse, with the cell types, neuropils and community labels layered on top.

The whole fly brain, and where its signal goes. Each sphere is one of the 79 neuropils, placed at the synapse-weighted center of its neurons and colored by brain region -- orange for the optic lobes down each side, yellow for the superior neuropils and lateral horn across the top, green for the antennal lobe and the neuropils around the esophagus below, blue and light blue for the inferior, ventromedial and ventrolateral neuropils between them. A sphere's width grows with the cube root of its synapse count, so one twice as wide holds about eight times as many.

The tubes are the strongest 100 of 5,786 directed neuropil pairs. Thickness grows with the square root of the flow, and each tube bows to the right of its direction of travel, so a tube bulging toward you runs left to right. Flow is carried by neurons rather than counted from synapses: each neuron's output synapses in B, apportioned by the share of its input lying in A, summed over every neuron.

Behind them, one gray dot per neuron at its cell body -- all 139,255 of them, which is what gives the brain its outline. The floor and shadow carry no data; they are there for depth. One command draws it: connkg quilt --view flow --floor --cloud --still.

Render of the FlyWire FAFB v783 connectome (Dorkenwald et al. 2024; Schlegel et al. 2024), CC BY-NC-SA 4.0. The image is an adaptation shared under the same license, not under the software's Elastic License 2.0.

The first corpus is the FlyWire FAFB v783 adult Drosophila brain: 139,255 neurons and 3,732,460 connected neuron pairs. ConnectomeKG reads the Codex export, normalizes it into dataset-neutral tables, and writes a typed graph to SQLite. Neurons are instances of cell types, cell types sit under a super class and class taxonomy and belong to hemilineages, and both neurons and types connect to the neuropils they innervate. Each synapse edge carries its count and a transmitter sign. A vector index over the small human vocabulary (cell type names, neuropils, labels, taxa) lets a query like "sugar sensing gustatory neurons" find the right place to start.

From there you can ask wiring questions directly: the strongest signed path from a sensory neuron to a motor neuron, the downstream cone of a visual projection type, the hub neurons and strongest type-to-type connections. Because it is a KGModule built on kgmodule-utils, the same graph also federates with the rest of the KGRAG fleet.

The design follows its siblings: structure is ground truth; embeddings are an acceleration layer. In a connectome this is literal. The synapse counts come from the microscope and the semantic layer is a thin set of labels on top. Neurons are not embedded by default; there are 139k of them and their names carry little meaning. Search finds a type or a neuropil, then the graph does the rest.

Everything runs on your laptop. A full v783 build without the vector index takes about three minutes.

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

Status: pre-alpha (0.7.1). The Codex reader, the synthetic fixture, the extractor, path, cone and influence queries, the Markdown analysis, snapshots, the connkg CLI, the connkg-mcp server, and the 2-D and 3-D views work end to end, and a real FAFB v783 build has been run and measured. Not done yet: the neuPrint reader (hemibrain, MaleCNS) and the LIF what-if simulation. The KGRAG adapter ships in kg-rag 0.16.0: pip install "kg-rag[connectome]".

Sister projects

ConnectomeKG is part of the KGRAG family, a suite of knowledge-graph systems that share the same hybrid semantic-plus-structural design, each for a different kind of corpus:

• PyCodeKG -- Python source code: modules, classes, functions and their typed relationships.
• DocKG -- document corpora (.md, .txt, .rst, .pdf) with source-grounded passage packs.
• MetaboKG -- metabolic pathways (KEGG, SBML, BioPAX) with FBA and ODE simulation on top of the graph.
• GenealogyKG -- GEDCOM family-history files: people, families, events, places and lineage.
• DiaryKG -- personal journals and diary corpora.
• AgentKG -- conversational memory as a knowledge graph.

All of them build on kgmodule-utils, the shared SDK for storage, indexing, query and snapshots.

Get started

Requirements: Python >= 3.12, < 3.14

pip install "connectome-kg[semantic]"

To work on it, install from a clone instead:

git clone https://github.com/Flux-Frontiers/connectome_kg.git
cd connectome_kg
pip install -e ".[semantic]"      # or: poetry install --with dev --extras semantic

The semantic extra adds the embedding model for connkg query. Without it, everything except semantic search works; pass --no-index to build.

The viz3d extra (pip install "connectome-kg[viz3d]") adds PyVista, PyQt5, pyvistaqt and quiltwright for connkg quilt and connkg viz3d: real-geometry 3-D views of the whole brain plus a circuit's traced skeletons or the signal flow between neuropils, rendered to a Looking Glass quilt or opened in an interactive viewer. docs/rendering.md explains both views and how each is drawn.

No install at all also works from the clone root: PYTHONPATH=src python -m connectomekg <arguments>. With Poetry, prefix commands with poetry run.

Try it on a synthetic connectome

No download needed. The fixture is a seeded connectome shaped like v783 (population shares, degree tail, synapse histogram, transmitter shares, reciprocity) with planted feeding, escape and grooming circuits, written in Codex format so it goes through the real reader:

connkg fixture --out /tmp/synth1k --n 1000 --seed 1
connkg --root /tmp/kg --dataset synthetic1k build --data-dir /tmp/synth1k --no-index --wipe
connkg --root /tmp/kg path --from GRN_sugar --to MN9
connkg --root /tmp/kg cone LC4 --min-syn 5
connkg --root /tmp/kg analyze

Build the real FlyWire brain

The Codex portal needs a Google sign-in and lists display labels instead of file names, so the download is a manual step. docs/DOWNLOAD.md walks through it, including which three files are required (about 71 MB) and the Safari .gz trap.

connkg files                                   # portal label -> file name
connkg verify --data-dir /path/to/fafb_v783    # check the download
connkg --root . --dataset fafb783 build --data-dir /path/to/fafb_v783
connkg --root . analyze

For the 3-D views, two more one-time passes fill in the anatomy:

connkg --root . --dataset fafb783 meshes                                  # 78 neuropil surfaces, ~1 MB
connkg --root . --dataset fafb783 skeletons --data-dir /path/to/fafb_v783 -j 12

skeletons needs the 31 GB skeleton download, and is the only thing that does: it caches every neuron's simplified skeleton (2.5 GB) and writes each neuron's real soma into the graph. -j is the worker count and defaults to 1, so pass your core count -- 2m 39s across twelve on FAFB v783, against 19m 30s on one.

Measured on Apple silicon for the 0.2.0 release, September 2026: 3 minutes 2 seconds, 7.2 GB peak memory, and 2.3 GB of SQLite for 157,698 nodes and 5,072,285 edges. Keep about 4 GB free; the write-ahead log and the database both exist during the final checkpoint. The vector index for connkg query adds 25 seconds (16,861 vectors, 29 MB; Apple M5 Max, September 2026); --no-index skips it.

What is in the graph

Transmitter signs follow Shiu et al. (2024): acetylcholine, dopamine, octopamine and serotonin are +1; GABA and glutamate (inhibitory in Drosophila via GluCl-alpha) are -1; an unresolved transmitter is 0.

How path queries work

connkg path and connkg cone load the SYNAPSES_TO edges once into a sparse matrix and answer with SciPy.

An edge's weight is the fraction of the postsynaptic neuron's input synapses it carries. A path's strength is the product of those fractions, so the strongest path is the Dijkstra shortest path on -log(fraction). This is the connectome-interpreter convention: a 40-synapse input that is half of a small neuron's drive counts for more than a 40-synapse input that is 1% of a large one. Each result reports per-hop synapse counts, fractions and signs, and a net sign for the whole path.

A spec names a starting set of neurons in any of four ways:

What you can do with it

What a SPEC can be

Every command that takes neurons takes the same grammar, and connkg specs prints it.

An answer goes anywhere a spec does, and draws the query rather than naming it:

The arrow follows the signal, which is why upstream is <. Specs are case-sensitive, and a label: pattern is a regular expression. An answer that will not fit in one scene is refused; narrow it with --min-syn.

--root and --dataset come before the command. Run connkg <command> --help for every option.

One graph per connectome

Each connectome release is built into its own directory, the way GutenbergKG keeps one graph per book:

<root>/connectomes/
  fafb783/.connectomekg/     graph.sqlite, vectors.sqlite, snapshots/
  synthetic/.connectomekg/

Releases never share a graph, a vector index or a snapshot history. --dataset ID picks one. Without it, connkg build writes to fafb783 (synthetic with --source synthetic), and every other command uses the only built dataset, or stops and lists them when there are several. Dataset ids are 1-64 lowercase letters, digits, _, . or -.

A graph built before this layout sat in <root>/.connectomekg/. Move it with:

mkdir -p connectomes/fafb783/.connectomekg
mv .connectomekg/*.sqlite* connectomes/fafb783/.connectomekg/

From Python

from connectomekg import ConnectomeKG

with ConnectomeKG("/tmp/kg", source="synthetic", n_neurons=1000, seed=1) as kg:
    kg.build_graph(wipe=True)       # graph only; build() also embeds (semantic extra)
    path = kg.strongest_path("GRN_sugar", "MN9")
    print(path.strength, path.net_sign, [h.node_id for h in path.hops])
    print(kg.analyze())

As an MCP server

connkg-mcp serves the graph to MCP clients (Claude Code, Claude Desktop, Cursor) over stdio, or SSE with --transport sse. Point --root at the directory holding connectomes/, and add --dataset ID when more than one dataset is built. Serve two datasets as two entries. In a project's .mcp.json, which holds absolute paths and is gitignored:

{
  "mcpServers": {
    "connkg": {
      "command": "/path/to/connectome_kg/.venv/bin/connkg-mcp",
      "args": ["--root", "/path/to/connectome_kg", "--dataset", "fafb783"]
    }
  }
}

Every argument is bounded and checked inside ConnectomeKG, so the CLI and the server reject the same bad input with the same message: k 1-100, hop and hops 0-5, limit and max_nodes 1-500, min_syn 1-10000, queries and ids at most 500 characters, and a label: regex at most 100 characters that must compile. The first strongest_path or cone call on FAFB v783 loads all 3.7 M synapse edges; later calls reuse them.

Documentation map

Data and licensing

The FlyWire data is free for non-commercial use under CC BY-NC-SA 4.0. A graph built from it is a derived work under the same license. Keep the download and the built graphs (connectomes/*/.connectomekg/*.sqlite) out of the repository (.gitignore already does) and out of anything commercial.

The Codex portal is synchronised with the live FlyWire database, so its files drift from the October 2024 published release. For a build that has to be reproducible, use the static no-login snapshots listed in docs/DOWNLOAD.md and record which one you used.

If you use FlyWire data, cite the data papers:

• Dorkenwald, S. et al. (2024). Neuronal wiring diagram of an adult brain. Nature 634, 124-138.
• Schlegel, P. et al. (2024). Whole-brain annotation and multi-connectome cell typing of Drosophila. Nature 634, 139-152.
• Eckstein, N. et al. (2024). Neurotransmitter classification from electron microscopy images at synaptic sites in Drosophila melanogaster. Cell 187, 2574-2594.

Citation

If you use ConnectomeKG in research or a project, please cite it. The software is archived on Zenodo with each GitHub release. The DOI below, 10.5281/zenodo.22817369, always resolves to the newest version.

APA

Suchanek, E. G. (2026). ConnectomeKG: Connectomes as Knowledge Graphs (Version 0.7.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22817369

BibTeX

@software{suchanek_connectome_kg,
  author    = {Suchanek, Eric G.},
  title     = {{ConnectomeKG}: Connectomes as Knowledge Graphs},
  version   = {0.7.1},
  year      = {2026},
  publisher = {Flux-Frontiers},
  doi       = {10.5281/zenodo.22817369},
  url       = {https://github.com/Flux-Frontiers/connectome_kg},
}

License

Elastic License 2.0 -- free for non-commercial and internal use; commercial redistribution or hosting requires a license from Flux-Frontiers. This covers the software only. The connectome data keeps its own license (see above).

Support

• Issues -- GitHub Issues
• Sister projects: PyCodeKG, DocKG, MetaboKG
• Built on: kgmodule-utils, SQLite, sqlite-vec, pandas, SciPy and Click

Built for neuroscientists, and the AI agents that work alongside them -- egs