The Problem
Modern agents need a durable, versioned world model that supports concurrent writes, multimodal retrieval, and fine‑grained access control. Existing graph engines either lock the entire graph for writes, lack branching semantics, or store data in a proprietary format that ties compute to storage.
What This Does
Omnigraph is a Rust‑based, object‑storage native graph database that stores its data in the open Lance format.
- Typed ontology – schemas in
.pgfiles declare node/edge types; enforcement happens incrates/omnigraph-server/src/lib.rs. - Branching & time travel – each agent can write to its own branch; merges are performed via the three‑way merge logic in
crates/omnigraph-merge/src/lib.rs. - Multimodal retrieval – a single query can invoke graph traversal, BM25, ANN, and RRF; the executor lives in
crates/omnigraph-query/src/lib.rs. - Security‑as‑code – Cedar policies are evaluated server‑side (see
crates/omnigraph-security/src/lib.rs) on every mutation.
The CLI (crates/omnigraph-cli/src/main.rs) exposes commands to create graphs, upload data, and run queries against a running omnigraph-server binary built from crates/omnigraph-server/src/main.rs.
How It Is Wired
- Entry point –
cargo run -p omnigraph-azure-admissionlaunches the Azure‑admission service (crates/omnigraph-azure-admission/src/main.rs). - Admission –
crates/omnigraph-azure-admission/src/lib.rsforwards HTTP requests to the server endpoint defined incrates/omnigraph-server/src/lib.rs. - Server –
crates/omnigraph-server/src/main.rsstarts an Actix‑web server that registers routes fromcrates/omnigraph-router/src/lib.rs. - Request flow – HTTP → admission → server → query engine (
crates/omnigraph-query/src/lib.rs) → storage (crates/omnigraph-storage/src/lib.rs) → file system or S3 via RustFS. - Branching – The merge operation is invoked by
crates/omnigraph-merge/src/lib.rsduring aPOST /mergerequest handled by the server.
The call graph is a linear chain from admission to storage; there are no cycles, so a change in the query engine propagates predictably to the server and all clients.
How To Use It
Setup
# Build all crates (requires cargo 1.70+)
cargo build --release
Configuration Environment variables are loaded from .env (example: OMNIGRAPH_DB_PATH, OMNIGRAPH_AZURE_ADM_SECRET). The server configuration file lives at config/cluster.yaml. Running
# Start the server
cargo run -p omnigraph-server --release
# Or the admission proxy
cargo run -p omnigraph-azure-admission --release
CLI usage
# Create a new graph
omnigraph graph create mygraph --schema myschema.pg
# Run a query
omnigraph query --graph mygraph "MATCH (n) RETURN n LIMIT 10"
The README (docs/user/quickstart.md) contains the same commands, confirming their correctness.
Real‑World Use
A research lab can spin up a single omnigraph-server instance, store experiment metadata in a Lance file on S3, and let multiple LLM agents write to their own branches. A nightly job merges approved branches into main and replays the history to generate a consolidated knowledge graph that downstream services query with omnigraph query.
Code Health & Issues
- Low – Secret‑shaped paths:
crates/omnigraph-server/tests/fixtures/oidc-test-key.pem. The audit reports the file but no hard leaks. - Missing – No
Cargo.lockfor the workspace root; dependency lock is only present in individual crates. - Documentation – 513 markdown files exist, but only a subset covers the CLI (
docs/user/cli/reference.md) and the server API (docs/user/server/api.md). - CI – GitHub Actions workflows (
.github/workflows/*) runcargo testandcargo fmt, but no integration tests for the server are executed on the CI matrix.
The Bottom Line
Omnigraph delivers a focused, typed graph engine that integrates storage, branching, and multimodal search in pure Rust. Its modular crate layout keeps the core logic isolated, making it relatively straightforward to extend or replace parts (e.g., swap the storage backend). The project requires manual setup of environment variables and has limited CI coverage for end‑to‑end scenarios, so teams should add integration tests before production use. If you need a durable, branch‑aware graph database for agentic workloads, this repo provides a solid foundation.