GraphForge

Composable graph tooling for analysis, construction, and refinement

An embedded, openCypher-compatible graph engine with a Rust core, Arrow results, and Parquet persistence — for research and investigative workflows

Build a graph, ask it questions, and keep what you learn, without running a database server. GraphForge runs inside your Python or Node process or through the gf command.

Who it is for. The core audience is a nontechnical analyst working with an agent. v0.6.0 initially serves technical analysts and integrators more completely: people who write Python or Node, or direct a coding agent. Setup and execution still need an agent or technical helper. See Who GraphForge is for.

Two jobs you can complete today:

1. Explore a connected dataset (a citation network, a dependency graph, evidence for an inquiry) with openCypher or the analyst verbs, and keep the graph as a durable project.
2. Bulk-load a large relationship table, reopen it, and move it by verified export and import.

Not a fit: a centrally hosted application with many concurrent users; durable storage on a network or container-overlay filesystem; anything that needs backward compatibility between versions. Evaluate an operational database for those.

Start with plain graph construction and querying. Saved analyses, challenged hypotheses, research history, and collaboration are there when you need them, and none of them is required to begin.

• Pre-v1. APIs and project formats can change. There is no backward-compatibility or migration guarantee; GraphForge opens only supported current-format projects.
• Durable projects need ext4, xfs, or btrfs on Linux (GF_UNSUPPORTED_FILESYSTEM otherwise). In-memory projects (GraphForge()) run the full engine anywhere a native package exists.
• Crates.io builds lack two DataFusion fixes that the Python wheel and Node packages carry. Prefer those packages unless you need the Rust crates.
• Measured scale: one run reached 1,073,741,824 live edges on a documented host; the 1,000,000 edges/s ingest target is not met. Every number, its workload, host, command, and limits are in Scale and workload limits. Benchmark results are unaudited.

Details: installation status and limits.

Python 3.10+

python -m pip install --pre graphforge # latest pre-release

python -m pip install graphforge # latest release

Node.js 20+

npm install @curatelabs/graphforge@next apache-arrow # latest pre-release

npm install @curatelabs/graphforge apache-arrow # latest release

Releases lists what is available, and the installation guide covers candidates and source builds. Before v1.0.0 there is no backward-compatibility or migration guarantee.

The coordinated launch journey is browse the production Hub, install the exact candidate CLI, clone a project, reopen and query it, continue locally, publish back, then discover and clone the new Version. Follow the Hub launch path.

Qualification is blocked: the intended opendata/openalex fixture is not yet available through production discovery. Production clone/query/publish-back and the selected candidate remain subject to #1209. The local example below is available independently.

from graphforge import GraphForge

forge = GraphForge()
survey = forge.add_node("Paper", title="Survey")
methods = forge.add_node("Paper", title="Methods")
forge.add_edge(survey, "CITES", methods)

result = forge.execute("""
    MATCH (source:Paper)-[:CITES]->(paper:Paper)
    RETURN source.title AS source, paper.title AS title
""")
print(result.to_pylist())
# [{'source': 'Survey', 'title': 'Methods'}]
forge.close()

This graph lives in memory and is gone when closed. To keep one, save and reopen a durable project; it needs supported local storage, such as ext4, xfs, or btrfs on Linux.

Built-in open-dataset loaders (SNAP, LDBC, NetworkRepository) are a backlog extension and not part of the core release; build graphs with the construction APIs or Cypher. The full documentation is at docs.graphforge.sh.

Ask in GitHub Discussions or open an issue from a template. Get help and report a problem explains what to include in a minimal reproduction and how maintainers triage reports. Support is best-effort; there is no service-level agreement.

One Rust engine sits behind both Cypher and the analyst verbs:

forge.execute("MATCH ...")       → Cypher compiler and execution pipeline
forge.rank(..., by=...)          → Rust algorithm dispatch → Arrow Table
forge.cluster(..., by=...)       → Rust algorithm dispatch → Arrow Table
forge.similar(..., by=...)       → Rust algorithm dispatch → Arrow Table
forge.paths(..., by=...)         → Rust algorithm dispatch → Arrow Table
forge.analyze(..., by=...)       → Rust algorithm dispatch → Arrow Table
forge.find(...)                  → Search path → Arrow Table

Cypher runs through five Rust layers; the analyst verbs bypass the parser and dispatch straight to typed Rust handlers:

graphforge-cypher → graphforge-ir → graphforge-plan → graphforge-rel → graphforge-exec
                                                                         ↘ graphforge-storage (Parquet)

• Results: tabular results are pyarrow.Table in Python and Arrow IPC bytes in Node. Construction methods can return handles; metadata and lifecycle methods return collections, scalars, or nothing.
• Storage: graph data persists as Arrow/Parquet and metadata as JSON. Graph identities are public UUIDs.
• Bindings: Python and Node only adapt arguments and Arrow data. igraph and NetworkX are optional development parity oracles, never runtime backends or fallbacks.
• Conformance: the openCypher TCK runs as a regression baseline.

uv sync --all-extras --inexact               # Python dependencies; keeps the built wheel
pnpm install                                 # Node dependencies

make check                                   # all static checks (mirrors CI Lint)
make test-rust ARGS="-p graphforge-storage"  # Rust tests, narrowed to a crate

# The binding suites test the built wheel and addon; rebuild after changing Rust
uv run maturin develop --release -m crates/graphforge-bindings-py/Cargo.toml
pnpm --filter @curatelabs/graphforge build
make test-python                             # Python binding suites
make test-node                               # Node binding suites

The documentation is an Astro Starlight site in docs-site/, built from the Markdown in docs/:

pnpm install
pnpm docs:dev          # http://localhost:4321/
pnpm docs:build        # output: docs-site/dist/

Start with Contributing. The agent skills package documents its local pack and offline install. Releases are cut by pushing a v<version> tag; see RELEASING.md and Publishing.

The roadmap has delivery detail. Release notes are attached to each immutable GitHub Release.

Open source under the Apache License 2.0 (Apache-2.0) © Curate Labs Inc. You may use, modify, and distribute GraphForge, including for commercial purposes, subject to the license terms. See LICENSE and licensing details.

Built on Apache Arrow, DataFusion, Parquet, and the openCypher specification.