omnigraph/README.md

Omnigraph

Lakehouse native graph engine built for context assembly

Omnigraph acts as operational state & coordination layer for agents. Hundreds of agents can enrich the graph on parallel isolated branches and changes can be reviewed and merged safely.

• Git-style versioning & branching
• Multimodal retrieval (graph+vector/fts+filters) optimized for context assembly
• Runs on the local filesystem or any S3-compatible object store (AWS S3, R2, MinIO, RustFS)
• Native blob-as-data support (docs, images, videos, etc)
• VPC, On-prem, hybrid deployment
• Lance format as open storage layer

AS CODE	What it means
Schema AS CODE	Typed .pg schemas, planned, applied, enforced
Context AS CODE	Linted queries & agentic nudges, versioned and reusable
Security AS CODE	Cedar policies enforced server-side on every mutation
Dashboards AS CODE	Declarative views & controls over the graph (coming)

Core Use Cases

Use case	What it's for
Company brain	Org knowledge unified into one queryable graph
Context graph	Decision traces and codified tribal knowledge
Agentic memory	Durable, versioned memory for long-running agents
Dev graph	Issues & dependency model for coding agents
R&D data layer	Experiments & trials data written into branches
ML workflows	Versioned, branchable graphs for training & eval
Karpathy's LLM wiki	A living, agent-updatable knowledge base

Quick Install

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

This installs omnigraph and omnigraph-server into ~/.local/bin from published release binaries.

Or install with Homebrew:

brew tap ModernRelay/tap
brew install ModernRelay/tap/omnigraph

Quick start

The fastest path is an embedded, local file-backed graph — no server, no object store, no Docker:

# A schema and one row of data
cat > schema.pg <<'PG'
node Person {
  slug: String @key
  name: String
  title: String?
}
PG
echo '{"type":"Person","data":{"slug":"alice","name":"Alice","title":"Engineer"}}' > people.jsonl

# Create → load (--mode is required) → query
omnigraph init  --schema schema.pg ./graph.omni
omnigraph load  --data people.jsonl --mode overwrite --store ./graph.omni
omnigraph query find_people --store ./graph.omni --params '{"t":"Engineer"}' \
  -e 'query find_people($t: String) { match { $p: Person { title: $t } } return { $p.name } }'

# Branch, write in isolation, merge — Git-style across the whole graph
omnigraph branch create --from main review/new-hires --store ./graph.omni
omnigraph branch merge  review/new-hires --into main --store ./graph.omni

Storage backends — the same flow runs on any backend; only the graph address changes:

Backend	Use it for	Graph address
Embedded (local filesystem)	dev, demos, single machine — the default	./graph.omni
Object storage (AWS S3, R2, GCS-S3)	shared, multi-host, durable	s3://bucket/graph.omni (+ the AWS_* env)
RustFS / MinIO	rehearse the S3 path locally, no cloud account	s3://… against a local endpoint → deployment guide

init takes the address as its positional argument (omnigraph init --schema schema.pg <address>); load, query, and branch take it via --store <address>.

For a served, multi-graph deployment (the cluster model), see Common Commands below.

Set it up with an AI agent

Omnigraph is built to be set up by coding agents. Paste this into Claude Code, Cursor, or any agent that can read a URL, install a package, and run a shell command — it installs the skill, reads the docs, and walks you through setup for your use case:

Help me set up Omnigraph (a lakehouse-native graph engine for agents).

1. Install the Omnigraph skill so you operate it correctly:
     npx skills add ModernRelay/omnigraph@omnigraph
2. Read the docs at https://github.com/ModernRelay/omnigraph — start with
   docs/user/quickstart.md, then docs/user/clusters/index.md.
3. Skim the starter graphs and seed data in the cookbooks:
   https://github.com/ModernRelay/omnigraph-cookbooks
4. Ask me what I want to build (company brain, agent memory, dev graph,
   research / R&D layer, …). Then install the CLI, stand up a first graph for
   that use case, load a little data, and run a query so I can see it working.

Works with any agent that can browse a URL, install a package, and run a shell.

Agent skill & starter graphs

This repo ships the omnigraph agent skill — the operational playbook (cluster mode, the two config surfaces, schema evolution, query linting, data writes, branches, Cedar policy, and common gotchas) that teaches a coding agent to drive Omnigraph correctly. Install it with:

npx skills add ModernRelay/omnigraph@omnigraph

For ready-to-run graphs with real seed data (company brain, VC operating system, pharma & industry intel), ModernRelay/omnigraph-cookbooks is the fastest way to see Omnigraph shaped to a real domain. To rehearse the S3 path locally, see deployment.md → Testing against S3 locally.

Common Commands

A deployment is a cluster. A cluster.yaml declares its graphs, schemas, stored queries, and policies; you converge it with cluster apply and serve it. The server is cluster-first — it boots only from a cluster and serves every graph under /graphs/{id}/…. Day-to-day work goes through that server: graphs are addressed with --server <name|url> (+ --graph <id>), and query/mutate invoke a stored query from the catalog by name.

# 1. Converge the declared cluster, then serve it (--as attributes the apply)
omnigraph cluster apply --config ./company-brain --as you
omnigraph-server --cluster ./company-brain --bind 0.0.0.0:8080
#    or config-free from object storage — the bucket IS the deployment:
#    omnigraph-server --cluster s3://my-bucket/company-brain --bind 0.0.0.0:8080

# 2. Work against the served graph — stored queries invoked by name
omnigraph query  find_people --server prod --graph knowledge --params '{"q":"AI safety"}'
omnigraph mutate add_person  --server prod --graph knowledge --params '{"name":"Mina"}'
omnigraph load   --data ./data.jsonl --mode merge --server prod --graph knowledge

# 3. Branch and merge, Git-style across the whole graph
omnigraph branch create --from main review/2026-06 --server prod --graph knowledge
omnigraph branch merge  review/2026-06 --into main --server prod --graph knowledge

Set a default scope (or a --profile) in ~/.omnigraph/config.yaml — operator identity, named servers/clusters, credentials — and the --server/--graph flags drop away (omnigraph query find_people --params …).

Local / ad-hoc. For quick iteration on a standalone graph (no cluster, no server), address storage directly with --store (or a positional file:// / s3:// URI) and run ad-hoc .gq with --query (the positional then selects which query in the file):

omnigraph init  --schema ./schema.pg ./graph.omni
omnigraph load  --data ./data.jsonl --mode merge --store ./graph.omni
omnigraph query --query ./queries.gq get_person --params '{"name":"Alice"}' --store ./graph.omni

See docs/user/cli/index.md, the CLI reference, the cluster guide, and the deployment guide for schema apply, snapshots, commits, profiles, and policy/queries tooling.

Clients

For programmatic access to a running omnigraph-server:

• TypeScript SDK + MCP server — @modernrelay/omnigraph and @modernrelay/omnigraph-mcp, versioned in lockstep with omnigraph-server. Source, docs, and examples: ModernRelay/omnigraph-ts.
• Python SDK — coming soon.

Docs

• Install 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 (zero Lance dependency)
• crates/omnigraph (package omnigraph-engine): storage/runtime, branching, merge, change detection, query execution, and embeddings
• crates/omnigraph-policy: Cedar policy compilation and enforcement
• crates/omnigraph-api-types: shared HTTP wire DTOs used by both the server and the CLI
• crates/omnigraph-cluster: cluster config validation, planning, and apply (the control plane)
• crates/omnigraph-server: Axum HTTP server — cluster-first, serving N graphs under /graphs/{id}/…
• crates/omnigraph-cli: CLI for graph lifecycle (init/load), query/mutate, branch/commit/merge, schema/lint, snapshot/export, cluster control, policy/queries, profiles, and maintenance (optimize/repair/cleanup)

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.

Community

Join the Omnigraph Slack community to ask questions, share feedback, and follow development.