Graphersal

An in-memory graph database and traversal engine in Rust, queried with Gremlin.

Playground · Book ·
Step reference ·
API docs ·
Mirror on GitHub Pages

Why Graphersal

AI moves faster than the tools around it. We built Graphersal so you don't have to wait for them: a
lightweight, embeddable graph engine you can turn into whatever your AI solution needs — a library
inside your application, a tool for your agents, or a full server with your own features on top.

It works out of the box: a browser UI, an MCP endpoint for AI agents, an AI chat where you simply
ask about your graph in plain language and it writes and runs the queries for you, durable storage
and transactions, and the safety to run queries you did not write — permissions, read-only access,
resource limits and timeouts. You start with a working system, not with a list of components to
wire together.

A first look

You ask Graphersal questions in plain language or in Gremlin. In the AI chat you simply
write what you want to know, and the model of your choice turns it into queries, runs them and
answers. Gremlin is the query language of Apache TinkerPop™:
start somewhere in a graph, walk along its edges, filter, group and count.

// who created software together with marko?
g.v().has("name", "marko").as("me")
  .out("created").in("created")
  .where(P.neq("me"))
  .path().by("name")

Run it in the playground:
the real engine, compiled to WebAssembly, runs in your browser. Nothing to install, and your data
never leaves your browser.

What you get

• Gremlin, two ways. Build traversals in Rust or write them as text in the Gremlin DSL, in
  snake_case or in Gremlin's own camelCase (has_label or hasLabel). The same text runs in the
  browser, on the command line, from Python and through an AI agent.
• A playground in the browser. Write a query and see a table, the graph drawing, the schema and
  the optimized plan.
• A command line tool. One-shot queries for shell scripts, an interactive REPL with completion
  and help, and a local server that brings the playground UI to a graph on your disk.
• AI agents on your graph. The server speaks the Model Context Protocol (MCP), so Claude Code or
  another MCP client can query the graph you are looking at. In the playground's AI Chat tab you ask
  about your graph in plain language, and the model of your choice writes and runs the queries
  (experimental).
• Safe by construction. Every traversal is atomic: it commits completely or leaves nothing
  behind. Schemas (a subset of JSON Schema) are enforced on write. Limits, timeouts and permissions
  make it safe to run queries you did not write.
• Durable when you need it. A graph lives in memory, and the Store keeps it on disk: every
  commit goes to a write-ahead log, and you can go back to any point in time, fork, roll back, back
  up and repair. The file format is a public specification.
• Fast and observable. A rule-based optimizer rewrites each query; profile() shows the
  optimized plan with timings, traverser counts and memory per step.
• Open for integration. Rust and Python APIs, saved (named, parameterized) queries stored in the
  graph, change capture with commit hooks, GraphSON 3.0 and GraphML files, and a storage trait to
  run the whole engine on a storage of your own.

Get started

In the browser

Open play.graphersal.dev, pick a sample graph and press Run. The
playground tour shows every panel.

On the command line

cargo install graphersal-cli          # the binary is `graphersal`

graphersal -e 'g.v().has("name", "marko").out("knows").values("name")'
graphersal --graph people.json -e 'g.v().has_label("person").count()'    # GraphSON or GraphML
graphersal                                                               # interactive REPL
graphersal --graph people.json --server --mcp      # the playground UI + MCP on http://127.0.0.1:8080

The result goes to stdout, a diagnostic to stderr, and a failing query exits with 1, so a shell
script or a CI job can check a graph. See The Command Line
and Dev Server, MCP and AI Chat.

From Rust

[dependencies]
graphersal = { version = "0.1", features = ["script", "io", "display"] }

use graphersal::prelude::*;

let graph = GraphSource::tinkerpop_modern();
let friends = graph
    .read()
    .traversal()
    .v(None)
    .has("name", "marko")
    .out("knows")
    .values("name")
    .to_list()?; // ["josh", "vadas"]

// the same query as Gremlin text (feature `script`)
let names = graphersal::script::eval_value(
    std::sync::Arc::new(graph),
    r#"g.V().has("name", "marko").out("knows").values("name").toList()"#,
)?;

Every feature is off by default: script (the Gremlin DSL), io (GraphSON and GraphML),
display (tables), serde, persist (snapshots, journal and the Store). See the
Rust Quick Start.

From Python

pip install graphersal

import graphersal

graph = graphersal.Graph.tinkerpop_modern()
graph.query('g.V().has("name", "marko").out("knows").values("name")')
# ['josh', 'vadas']

See the Python Quick Start.

How mature is it

Graphersal 0.1 is a first public release, built with the care of a database:

• TinkerPop conformance. Apache TinkerPop's own Gherkin test suite (3.8.2) runs on every test
  run. More than 95 % of the scenarios in scope pass, and no implemented step gives a wrong result.
  The rest are steps that are not implemented yet or differ on purpose; each difference is
  documented (compliance,
  deviations).
• Tested hard. About 90 % line coverage; randomized differential tests and fuzzing of queries,
  file decoders, checkpoints and backups run in every cargo test, with long budgets before each
  release. A query that goes wrong ends in an error with a help() text, never in a crash.
• A public storage format. Snapshots, the write-ahead log and the Store are described byte by
  byte in the format specification; every
  decoder treats its input as hostile.
• Clear stability labels. Within 0.1.x the public API of graphersal (outside the items
  marked experimental), the DSL and the schema format change only additively. The storage traits
  (GraphStorage, PersistentStorage, StoreDir) are experimental in 0.1.x, and the dev
  server's HTTP API is internal.

Graphersal is not a complete copy of TinkerPop. Read
Graphersal and TinkerPop for what
is the same, what is different and why.

Repository

Building from source needs Rust 1.88 or newer:

cargo build --release -p graphersal-cli      # target/release/graphersal

Contributing

Bug reports, questions and pull requests are welcome. Contributions are accepted under the
Apache-2.0 licence with a DCO sign-off (git commit -s); see CONTRIBUTING.md.
Please report security issues privately as described in SECURITY.md.

License

Licensed under the Apache License, Version 2.0; see also NOTICE. Use of
the project name is described in TRADEMARKS.md.

Graphersal is compatible with, and inspired by, Apache TinkerPop Gremlin. It is an independent
project: it is not part of Apache TinkerPop and is not endorsed by the Apache Software Foundation.
Apache TinkerPop, TinkerPop and Gremlin are trademarks of the Apache Software Foundation.