Omnigraph is the operational state and coordination layer for fleets of agents. Run it as a server, declared as code; hundreds of agents operate and enrich the graph on parallel isolated branches, and every change is reviewed and merged safely.
A cluster.yaml declares graphs, schemas, stored queries, embedding providers, and policies; cluster apply converges it and omnigraph-server brings every graph online at /graphs/{id}/….
Built for fleets of agents
Hundreds of agents enrich the graph on parallel isolated branches; changes are reviewed and merged safely, Git-style, across the whole graph.
Multimodal retrieval
Graph traversal + vector ANN + full-text + Reciprocal Rank Fusion in one query runtime, for context assembly.
Security as code
Cedar policy enforced server-side on every mutation, per-graph and server-wide; bearer auth; actor/audit tracking.
Runs on your infrastructure
Local storage or any S3-compatible object store (RustFS / MinIO, AWS S3 / R2 / GCS, Azure). VPC, on-prem, hybrid; your data never leaves your store.
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
Set it up with an AI agent
Omnigraph is built to be run by coding agents. Two ways in:
Teach your agent the playbook. This repo ships the
omnigraph agent skill: the operational playbook
covering cluster mode, the two config surfaces, schema evolution, query linting,
data writes, branches, Cedar policy, and the common gotchas.
npx skills add ModernRelay/omnigraph@omnigraph
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.
Deploy
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.
Query and mutate
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.
Security & governance
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.
Both npm packages are versioned in lockstep with omnigraph-server.
Local quick test (no server)
1-min setup to try it: an embedded, local file-backed graph (no server, no
object store). For dev and experiments; production is the deployed cluster above.
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
Workspace Crates
crates/omnigraph-compiler: shared schema/query parser, typechecker, catalog, and IR lowering (zero Lance dependency)
crates/omnigraph-storage: shared local/S3/Azure control-object storage implementation and concrete backend handle
crates/omnigraph-azure-admission: narrow Azure Blob lease wrapper for the single-writer reference deployment
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, runs N graphs under /graphs/{id}/…
crates/omnigraph-cli: CLI for graph lifecycle, query/mutate, branch/commit/merge, schema/lint, snapshot/export, cluster control, policy/queries, profiles, and maintenance
Contributing
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.
Omnigraph 是一个湖仓原生的图数据库，充当 AI 智能体集群的运行状态与协调层，把图遍历、向量搜索和全文搜索与 Git 风格的分支结合起来，让大量智能体能安全地充实同一个共享知识图谱。