ModernRelay/omnigraph

Object-storage native graph database with branching and typed ontology.
_{Unified retrieval engine (vector/bm25/graph) · Git-style workflows · Open data format (Lance)}

Quickstart  ·  Docs  ·  Cookbooks  ·  CLI llms.txt

Omnigraph is engineered for the new workload introduced by long-horizon agents: Multiple agents sharing a typed world model to continuously retrieve and store context and coordinate work. Agents and UIs can become thin stateless consumers of a durable state.

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

This installs omnigraph (CLI) and omnigraph-server into ~/.local/bin from published release binaries. Or with Homebrew:

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

Omnigraph is built to be run by coding agents. Two ways in:

Teach your agent the playbook. The omnigraph binary carries the omnigraph agent skill written for it: the operational playbook covering cluster mode, the two config surfaces, schema evolution, query linting, data writes, branches, Cedar policy, and the common gotchas. Export it where your agent loads skills, so the skill always matches the installed CLI:

omnigraph skill export ~/.claude/skills/omnigraph --force

With an older CLI that has no skill command, or none installed, npx skills add ModernRelay/omnigraph@omnigraph installs the copy on the default branch instead.

Or have an agent set it up from scratch. Paste this into Claude Code, Codex, or any agent that can read a URL and run a shell command:

Help me set up Omnigraph

1. Read the docs at https://github.com/ModernRelay/omnigraph, starting with
   docs/user/clusters/index.md, then docs/user/deployment.md.
2. Skim the starter graphs and seed data in the cookbooks:
   https://github.com/ModernRelay/omnigraph-cookbooks
3. Ask me what I want to build (company brain, agent memory, dev graph,
   research / R&D layer, …). Then stand up a cluster for it, load a little
   data, and run a query so I can see it working.

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.

A deployment is a cluster: a multigraph config directory that declares its graphs, schemas, stored queries, and policies as code. You manage it Terraform-style: cluster plan previews the diff, cluster apply converges it. omnigraph-server then boots from the cluster and brings every graph online at /graphs/{id}/…, each behind its own policy.

1. Declare the cluster.

company-brain/
├── cluster.yaml
├── people.pg          # schema for the "knowledge" graph
├── queries/           # stored queries: the .gq files ARE the declaration
│   └── people.gq
└── base.policy.yaml   # a Cedar policy bundle

# cluster.yaml
version: 1
metadata:
  name: company-brain
storage: s3://company/clusters/company-brain   # ledger, catalog, and graph data live here
graphs:
  knowledge:
    schema: people.pg
    queries: queries/                          # every `query <name>` in queries/*.gq registers
policies:
  base:
    file: base.policy.yaml
    applies_to: [knowledge]                    # graph-bound; use [cluster] for server-level

2. Stand up your object store. On-prem, run RustFS (or MinIO); Omnigraph writes Lance over the standard S3 API. In the cloud, use S3 / R2 / GCS through AWS_*. Native az:// roots are also available as a qualification preview. Every Azure writer, including cluster apply and the server, must use the checked-in admission wrapper; follow the Azure deployment guide instead of running the bare commands below.

3. Converge and run. apply creates each graph, applies its schema, and publishes queries and policies into the content-addressed catalog. It is idempotent; re-running is always safe.

omnigraph cluster validate   # parse + typecheck everything
omnigraph cluster plan       # preview what apply would do
omnigraph cluster apply      # converge

# Boot the server from the cluster dir; storage resolves through cluster.yaml
omnigraph-server --cluster company-brain --bind 0.0.0.0:8080

The bare commands above describe local and S3 deployments. See the cluster guide for the day-2 loop (edit → plan → apply → restart), approval gates for destructive changes, drift inspection, and recovery; the deployment guide for containers, AWS/Railway/Azure, auth, and the object-store environment contracts.

Set a default server and graph once in ~/.omnigraph/config.yaml, and the everyday commands stay short. Stored queries and mutations run by name:

omnigraph query  search_docs --params '{"q":"AI safety"}'
omnigraph mutate add_person  --params '{"name":"Mina"}'

# Branch, review, merge across the whole graph; agents write in isolation
omnigraph branch create --from main agent/ingest-42
omnigraph branch merge  agent/ingest-42 --into main

An alias is shorter still: bind a server, graph, and stored query to one name, then omnigraph alias triage runs it. For an ad-hoc target, any command still takes --server <name|url> --graph <id> (or --store <uri> for a local graph). See the CLI reference.

• Engine-wide enforcement: every write path goes through the same Cedar gate, so the HTTP server, the CLI, and the embedded SDK obey identical rules.
• Declared in the cluster: a policy bundle is bound to graphs (or the whole server) via policies: → applies_to.
• Scoped: rules apply per graph, per branch, or server-wide.
• No plaintext tokens: bearer tokens are hashed at startup and compared in constant time.
• Forge-proof identity: the actor is resolved server-side from the token; clients can't set it.

See the policy guide.

Both npm packages are versioned in lockstep with omnigraph-server.

• Cluster guide · Deployment guide · CLI reference
• Schema · Queries · Search · Policy

cargo build --workspace
cargo test --workspace --exclude omnigraph-gqt --exclude omnigraph-dst

Notes:

• Rust stable toolchain, edition 2024
• The GQT corpus (cargo test -p omnigraph-gqt) and the DST suite (cargo test from crates/omnigraph-dst, which supplies its process environment) run separately; a plain cargo test --workspace starts the DST binaries without that environment and they refuse. Commands and CI gates: docs/dev/testing.md
• CI runs the same excluded command with --locked and the failpoint features
• Full CI and some local test flows require protobuf-compiler
• S3 integration tests expect an S3-compatible endpoint such as RustFS

Please open an issue before sending large code changes — a maintainer triages it, and the accepted label is the green light for a PR (see GOVERNANCE.md). Concrete problem statements are the fastest way to collaborate on the roadmap.

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