GraphForge
Composable graph tooling for analysis, construction, and refinement
GraphForge is an embedded, local-first graph execution environment with a Rust core, Arrow results, and Parquet persistence. It brings openCypher and analyst-intent verbs to notebooks, scripts, repositories, and editor workflows without requiring a database server. The current v0.5 engine passes all 3,897 openCypher TCK scenarios.
Install tip: Install GraphForge from PyPI (
pip install graphforge) or npm (npm install @curatelabs/graphforge) to receive the current native release. Earlier pure-Python releases under thegraphforgePyPI name predate the CurateLabs engine. See Installation.
from graphforge import GraphForge
forge = GraphForge()alice = forge.add_node("Person", name="Alice", age=30)bob = forge.add_node("Person", name="Bob", age=25)forge.add_edge(alice, "KNOWS", bob, since=2020)
table = forge.execute(""" MATCH (p:Person)-[:KNOWS]->(friend) RETURN p.name AS person, friend.name AS friend""")
print(table.to_pandas())Every query and analyst verb returns an Apache Arrow Table. Python and Node are thin bindings; they never replace or fall back from the Rust engine.
Get started
Section titled “Get started”| Page | Job |
|---|---|
| Installation | Install Python or Node packages, or build from source |
| Quick Start | Create, query, and persist your first graph |
| Tutorial | Work through a complete citation-network example |
| CLI and repository integration | Initialize, validate, synchronize, checkpoint, export, and import a project |
| VS Code extension | Explore projects, run Cypher, and pair with coding agents in your editor |
Why GraphForge?
Section titled “Why GraphForge?”Modern research and investigation produce graph-shaped data: entity relationships extracted by LLMs, citation networks, dependency graphs, social connections, and evolving knowledge bases. GraphForge makes those graphs portable and inspectable without turning them into an application database or requiring a long-running service.
| Aspect | NetworkX | GraphForge | Neo4j / Memgraph |
|---|---|---|---|
| Setup | Python package | Embedded package | Run a server |
| Query language | Python API | Full openCypher | Full Cypher |
| Persistence | Manual | Parquet project directory | Native |
| Results | Python objects | Apache Arrow Tables | Driver rows |
| Notebook-friendly | ✓ | ✓ | Requires connection |
| Primary role | In-memory graph library | Local knowledge-analysis workbench | Operational graph database |
Use GraphForge for knowledge graphs, citation networks, LLM output storage, repository-aware
analysis, and social-network research. Use an operational database for high-throughput,
multi-user application workloads or graphs beyond the documented
scale limits (typically
GSI Level 07+ / LG).
Use every day
Section titled “Use every day”| Page | Job |
|---|---|
| Guide overview | Navigate everyday GraphForge workflows |
| Cypher guide | Query and mutate graphs with openCypher |
| Graph construction | Build graphs through Rust-owned APIs and Cypher |
| Analytics integration | Work with Arrow, pandas, Polars, and analyst verbs |
| VS Code commands | Run GraphForge from VS Code or a compatible editor |
| Agent interop | Drive structured extension commands from coding agents |
Architecture at a glance
Section titled “Architecture at a glance”GraphForge exposes one Rust-owned engine through Cypher, analyst-intent APIs, and repository lifecycle commands:
Python (PyO3, thin) ─┐Node (N-API, thin) ──┼──> graphforge-api ──> Arrow (data plane) + thin control/handle returnsCLI (thin launcher) ─┘
Cypher: graphforge-cypher ──> graphforge-ir ──> graphforge-rel ──> graphforge-exec └──> graphforge-storage (Parquet + JSON metadata)Analyst verbs bypass the Cypher parser and dispatch through Rust-owned typed handlers.Python, Node, the CLI, and the VS Code extension project the same engine behavior. Swift and Kotlin bindings are planned rather than shipped. See the architecture overview for storage, execution, ontology, knowledge, checkpoint, and compatibility contracts.
Understand and reference
Section titled “Understand and reference”| Page | Job |
|---|---|
| Book | Explore architecture, research, and deeper usage narratives |
| API reference | Look up engine, lifecycle, and analyst surfaces |
| Algorithm catalog | Choose rank, cluster, paths, analyze, or similar algorithms |
| OpenCypher compatibility | Inspect supported language behavior |
| Graph Scale Index (GSI) | Profile datasets by node band and density |
| Scale Evaluation | Official Graph500 + Derived density matrix; LDBC policy; external harness contract |
| TCK compliance | Review the 3,897 / 3,897 language gate |
Contribute and operate
Section titled “Contribute and operate”| Page | Job |
|---|---|
| Documentation map | Understand the public information architecture |
| Contributing | Prerequisites, validation, and focused PRs |
| Testing | See how GraphForge proves behavior |
| Roadmap | Review current and planned product surfaces |
| Publishing | Package destinations and release sequence |
| Release process | Operator checklist for cutting a release |
GraphForge is open source under the Apache License 2.0.