omnigraph/README.md

Omnigraph

Omnigraph is a typed property graph database built on Lance. It combines schema-first graph modeling, typed queries and mutations, Git-style graph workflows, and storage that runs equally well on a local directory or an s3:// URI.

Quick Install

curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/install.sh | bash

This installs omnigraph and omnigraph-server into ~/.local/bin. If no tagged release exists for your platform yet, the installer falls back to a source build.

One-Command Local RustFS Bootstrap

curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/local-rustfs-bootstrap.sh | bash

That bootstrap:

• starts RustFS on 127.0.0.1:9000
• creates a bucket and S3-backed repo
• loads the checked-in context fixture
• launches omnigraph-server on 127.0.0.1:8080

Docker must be installed and running first.

Good Fit For

• Team knowledge graphs and internal context graphs
• Research, decisions, and evidence tracking
• Collaborative knowledge systems with reviewable changes
• Private self-hosted graph backends for local or on-prem AI tooling

Why Omnigraph

• Typed schema, typed queries, and typed mutations
• Git-style graph workflows: branches, commits, merges, and transactional runs
• Local-first and S3-native storage with snapshot-pinned reads
• Graph traversal plus text, fuzzy, BM25, vector, and RRF search in one runtime
• Policy as code for server-side access control

Quick Start

From a checkout of this repo:

cargo build --workspace

cargo run -p omnigraph-cli -- init \
  --schema crates/omnigraph/tests/fixtures/test.pg \
  ./repo.omni

cargo run -p omnigraph-cli -- load \
  --data crates/omnigraph/tests/fixtures/test.jsonl \
  ./repo.omni

cargo run -p omnigraph-cli -- read \
  ./repo.omni \
  --query crates/omnigraph/tests/fixtures/test.gq \
  --name friends_of \
  --params '{"name":"Alice"}'

init also scaffolds an omnigraph.yaml next to the repo if one does not already exist.

Run A Server

Serve the same repo over HTTP:

cargo run -p omnigraph-server -- ./repo.omni --bind 127.0.0.1:8080

Then query it remotely:

cargo run -p omnigraph-cli -- read \
  --target http://127.0.0.1:8080 \
  --query crates/omnigraph/tests/fixtures/test.gq \
  --name get_person \
  --params '{"name":"Alice"}'

Server routes include /healthz, /snapshot, /export, /read, /change, /ingest, /branches, /runs, and /commits.

To require auth, set OMNIGRAPH_SERVER_BEARER_TOKEN on the server and set the matching bearer token env var in your CLI target config.

Common Commands

Core repo flow:

omnigraph init --schema ./schema.pg ./repo.omni
omnigraph load --data ./data.jsonl --mode overwrite ./repo.omni
omnigraph snapshot ./repo.omni --branch main --json
omnigraph read ./repo.omni --query ./queries.gq --name get_person --params '{"name":"Alice"}'
omnigraph change ./repo.omni --query ./queries.gq --name insert_person --params '{"name":"Mina","age":28}'
omnigraph branch create --uri ./repo.omni --from main feature-x
omnigraph branch merge --uri ./repo.omni feature-x --into main

More CLI examples, config patterns, and admin commands live in docs/cli.md.

Production Features

• Branches, commits, merge-base-aware graph merges, and transactional runs
• Snapshot-pinned reads across local and S3-backed repos
• Traversal plus text, fuzzy, BM25, vector, and RRF search
• Axum server for reads, changes, export, branches, commits, and runs
• Cedar-based server-side authorization

Docs

• Install guide
• CLI guide
• Deployment guide

Build And Test

cargo build --workspace
cargo check --workspace
cargo test --workspace

Notes:

• Rust stable toolchain, edition 2024
• CI runs cargo test --workspace --locked
• Full CI and some local test flows require protobuf-compiler
• S3 integration tests expect an S3-compatible endpoint such as RustFS

Workspace Crates

• crates/omnigraph-compiler: shared schema/query parser, typechecker, catalog, and IR lowering
• crates/omnigraph: storage/runtime, branching, merge, change detection, and query execution
• crates/omnigraph-cli: CLI for init/load/ingest/read/change/branch/snapshot/export/policy operations
• crates/omnigraph-server: Axum HTTP server for remote reads, changes, ingest, export, branches, commits, and runs

Contributing

Please open an issue, spec, or design discussion before sending large code changes. Design feedback and concrete problem statements are the fastest way to collaborate on the roadmap.