omnigraph README

The project's README from github.com/ModernRelay/omnigraph. As one markdown file: README.md.

OMNIGRAPH

Lakehouse graph database for context assembly & multi-agent coordination
Multimodal retrieval · Git-style branching · object-storage native

Quickstart  ·  Docs  ·  Cookbooks  ·  CLI

License: MIT Rust

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.

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

Key capabilities

Capability What it gives you
Declared as code 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.
Open, versioned storage Lance columnar format: branchable, time-travelable, with native blob-as-data (docs, images, video).

What you can build

Use case What it's for
Company brain Org knowledge unified into one graph every agent can query
Agentic memory Durable, versioned memory: a branch per agent or per task, merged on review
Context graph Decision traces and codified tribal knowledge for retrieval
Dev graph Issues & dependency model that coding agents read and write
R&D / ML data layer Experiments and trials written into branches, versioned for training & eval

Install

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

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

See the policy guide.

Clients & SDKs

Client Use it for Where
TypeScript SDK typed access from Node / TS @modernrelay/omnigraph · source
MCP server bridge Omnigraph to LLM hosts (Claude, Codex, …) @modernrelay/omnigraph-mcp
HTTP / OpenAPI any language, the wire contract the server's OpenAPI spec
Python SDK typed access from Python coming soon

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.

cat > schema.pg <<'PG'
node Source {
  slug: String @key
  title: String
}

node Claim {
  slug: String @key
  statement: String
}

edge Supports: Source -> Claim
PG
printf '%s\n' \
  '{"type":"Claim","data":{"slug":"lower-latency","statement":"The migration reduced request latency."}}' \
  '{"type":"Source","data":{"slug":"load-test","title":"Load test report"}}' \
  '{"edge":"Supports","from":"load-test","to":"lower-latency"}' > data.jsonl

omnigraph init  --schema schema.pg ./graph.omni
omnigraph load  --data data.jsonl --mode overwrite --store ./graph.omni

# "Which sources support the lower-latency claim?"
omnigraph query --store ./graph.omni \
  --params '{"claim":"lower-latency"}' \
  -e 'query sources_for_claim($claim: String) {
    match {
      $claim_node: Claim { slug: $claim }
      $source supports $claim_node
    }
    return { $source.title as source }
  }'
# → Load test report

Docs

Build And Test

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

Notes:

Workspace Crates

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.

Community

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

omnigraph (ModernRelay/omnigraph)

knowledge-management
Searching Database…

1.3K ·GitHub
Omnigraph
What is this?Omnigraph is a lakehouse-native graph database that acts as the operational state and coordination layer for fleets of AI agents, combining graph traversal, vector search, and full-text search with Git-style branching so many agents can enrich a shared knowledge graph safely.
Is this a server I run or a library I embed?It ships as a CLI (omnigraph) plus a server (omnigraph-server) deployed as a declared 'cluster', but it can also run embedded and local with no server at all, and there are TypeScript/Python SDKs and an MCP server for client access.
How do I get it running?Install the CLI and server from release binaries (or via Homebrew) into ~/.local/bin, declare your graphs/schemas/policies in a cluster.yaml, then run cluster apply; for quick testing there is a 1-minute embedded local file-backed graph with no server or object store needed.
Do I need an S3 bucket to run this in production?For real deployments you need an S3-compatible object store — RustFS, MinIO, AWS S3, Cloudflare R2, GCS, or Azure Blob — since Omnigraph writes its Lance data over the standard S3 API.
Is Azure storage production-ready like S3?Native Azure (az://) support is explicitly called a qualification preview, and every Azure writer must go through a special checked-in admission wrapper rather than running the bare commands used for S3; the Python SDK is also listed as 'coming soon', not yet shipped.
Does my data stay on my own infrastructure?Yes — Omnigraph runs on storage you control, whether local disk, your own VPC, on-prem, or a hybrid setup, and the README states your data never leaves your store.
What is the Git-style branching actually for?Hundreds of agents can work on parallel isolated branches of the same graph at once; every change is reviewed and merged back safely, just like a Git pull request, so experiments can't corrupt the shared graph.
How do AI agents connect to Omnigraph?Through a dedicated MCP server (@modernrelay/omnigraph-mcp) that bridges Omnigraph to LLM hosts like Claude or Codex, plus a TypeScript SDK for Node, a raw HTTP/OpenAPI interface for any language, and a Python SDK listed as coming soon.
How are writes protected from a misbehaving agent?Every write path — HTTP server, CLI, and embedded SDK — passes through the same Cedar policy engine enforced server-side; bearer tokens are hashed at startup and compared in constant time, and the acting identity is resolved server-side so clients can't spoof it.
What kinds of things can I build with it?The README lists use cases like a company-wide knowledge brain, durable per-agent/per-task agentic memory, decision-trace context graphs, dev graphs that coding agents read and write, and a versioned R&D/ML data layer for experiments.
What are similar projects?ruflo, xerj, chroma, m_flow, encore, OB1, executor, memory-lancedb-pro
Which topics is it in?policy-engine, lakehouse, graph-database, gcp, infrastructure-as-code, full-text-search, openapi, azure, s3, vector-search, knowledge-management, knowledge-graph
Creator
ModernRelay
Size
31.8 MB
Stars
1.3K
Updated
CommitOct 18Releasev0.13.0Oct 07
Age
6mo
Commits · 90 Days