d69b15d975
The shared pre-stage precondition rejected any strict write (update / delete / schema apply) whenever a table's Lance HEAD differed from the manifest pin the caller captured. But `HEAD > pin` is ambiguous: it can be benign content-preserving drift that never published (compaction, a recovery restore, an old-binary optimize, an external compact_files) — which carries no recovery sidecar and is safe to write over — or a real in-flight partial write a recovery sidecar covers and the open-time sweep will roll back. The old check failed both with a stale-view 409, so schema apply (and strict mutation) could not run on any write-active graph that had ever compacted or recovered, and the original +1-per-retry loop followed from it. Replace it with `Omnigraph::ensure_writable_or_defer`, which makes the OCC fence the *current* manifest pin (re-read fresh on the conflict path), not the caller's possibly-stale snapshot pin: - HEAD == caller pin: fresh, no drift -> proceed (fast path, no extra read). - caller pin != current pin: the caller is stale -> ExpectedVersionMismatch here, before any staged commit or sidecar, so a stale handle still fails loudly and leaves no residue (the prior early-reject behavior is preserved). - caller pin == current pin, HEAD > pin, no sidecar: benign drift -> proceed; the writer's commit + publisher CAS reconcile the manifest. - caller pin == current pin, HEAD > pin, a (foreign) sidecar pins the table: defer with an actionable 'reopen to recover' error. - HEAD < current pin: manifest leads durable Lance state -> loud invariant. Load-bearing details: - The OCC fence staging records is now the manifest pin threaded out of `open_for_mutation_on_branch` (4th tuple element), not `ds.version()`. With benign drift tolerated, capturing the drifted HEAD would relocate the rejection into a spurious 409 at the post-queue strict check. - `sidecar_pins_table` takes `exclude_operation_id`: schema apply writes its own recovery sidecar before its per-table head re-checks, so it must skip that sidecar or it would defer against itself. - The delete path's `initial_version` (reopen-for-mutation) stays `ds.version()` — it is a HEAD-vs-HEAD self-consistency check, not an OCC fence. Only the pre-stage check changes; the post-queue strict checks and the publisher CAS (manifest-vs-manifest) are unchanged. |
||
|---|---|---|
| .cargo | ||
| .context | ||
| .github | ||
| crates | ||
| docker | ||
| docs | ||
| scripts | ||
| .dockerignore | ||
| .gitignore | ||
| AGENTS.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CLAUDE.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| GOVERNANCE.md | ||
| LICENSE | ||
| og-cheet-sheet.md | ||
| omnigraph.example.yaml | ||
| openapi.json | ||
| README.md | ||
| rust-toolchain.toml | ||
| SECURITY.md | ||
Omnigraph
Lakehouse native graph engine built for context assembly
Omnigraph acts as operational state & coordination layer for agents
- Git-style versioning & branching
- Multimodal retrieval (graph+vector/fts+filters) optimized for context assembly
- Object storage native (S3, RustFS)
- Native blob-as-data support (docs, images, videos, etc)
- VPC, On-prem, hybrid deployment
Lanceformat 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
For starter graphs and agent skills to bootstrap and operate Omnigraph, see ModernRelay/omnigraph-cookbooks.
One-Command Local RustFS Bootstrap
curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/local-rustfs-bootstrap.sh | bash
That bootstrap:
- starts RustFS on
127.0.0.1:9000 - creates a bucket and S3-backed graph
- loads the checked-in context fixture
- launches
omnigraph-serveron127.0.0.1:8080
Docker must be installed and running first.
The RustFS bootstrap prefers the rolling edge binaries and only falls back to
source builds when release assets are unavailable.
If a previous run left objects under the same graph prefix but did not finish
initializing the graph, rerun with RESET_REPO=1 or set PREFIX to a new
value.
Common Commands
The same URI works for local paths, s3://…, or http://host:port.
omnigraph init --schema ./schema.pg ./graph.omni
omnigraph load --data ./data.jsonl ./graph.omni
omnigraph read --query ./queries.gq --name get_person --params '{"name":"Alice"}' ./graph.omni
omnigraph change --query ./queries.gq --name insert_person --params '{"name":"Mina"}' ./graph.omni
omnigraph branch create --from main feature-x ./graph.omni
omnigraph branch merge feature-x --into main ./graph.omni
See docs/user/cli.md for schema apply, snapshots, ingest, commits, and policy commands.
Clients
For programmatic access to a running omnigraph-server:
-
TypeScript SDK —
@modernrelay/omnigraph(source). Instance-per-client, typed errors, camelCase types, async-iterator streaming export.npm install @modernrelay/omnigraph -
Model Context Protocol server —
@modernrelay/omnigraph-mcp(source). Bridges Omnigraph to LLM hosts (Claude Desktop, Claude Code, …) over stdio. Exposes tools and resources for schema, branches, queries, mutations, ingest, and bundles curated best-practices guidance from the cookbook.npm install -g @modernrelay/omnigraph-mcp
Both packages are versioned in lockstep with omnigraph-server on major.minor: @modernrelay/omnigraph@X.Y.* targets omnigraph-server@X.Y.*. See ModernRelay/omnigraph-ts for the monorepo.
Docs
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 loweringcrates/omnigraph: storage/runtime, branching, merge, change detection, and query executioncrates/omnigraph-cli: CLI for graph lifecycle (init/load/ingest), query/mutate, branch/commit/merge, schema/lint, snapshot/export, policy, and maintenance (optimize/cleanup)crates/omnigraph-server: Axum HTTP server for remote reads, changes, ingest, export, branches, and commits
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.