omnigraph

Store, retrieve, and query knowledge, memory, and relationships in an Omnigraph graph, and operate a local or remote Omnigraph deployment. Use when the user wants to capture or recall facts, notes, or entities, build or query a knowledge graph or agent memory, or run Omnigraph — and whenever you see Omnigraph CLI commands (omnigraph init/query/mutate/load/schema/lint/embed/branch/commit/login/profile/cluster), .pg schema or .gq query files, s3:// graph URIs, bearer-authed graph endpoints, 504 errors, or a cluster.yaml / omnigraph.yaml / ~/.omnigraph/config.yaml. Covers cluster-mode deployments (cluster.yaml plan/apply, omnigraph-server --cluster), the two config surfaces (cluster.yaml + ~/.omnigraph/config.yaml), schema evolution, query linting, data writes (mutate; load needs --mode/--from), branches, embeddings, Cedar policy, and remote ops. Especially important before schema apply (plan first), any load (--mode required), any .gq/.pg edit (lint after), or any remote write (verify via commit list).

Jump to install

Repository: ModernRelay/omnigraph
Last source activity: August 23, 2026 at 10:11
Detected SKILL.md language: English
Stars: 1,085
Forks: 247

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/ModernRelay/omnigraph --skill omnigraph

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

File Explorer

12 files

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

Operating Omnigraph Locally

This skill captures the operational rules for working with a locally or remotely deployed Omnigraph. Follow them when authoring schema, writing queries, loading data, evolving schema, or automating graph operations.

The Seven Rules

Lint before commit — omnigraph lint --schema schema.pg --query queries/foo.gq validates both sides against each other. No running repo required.

Plan before apply — never run schema apply without a successful schema plan first. Apply is destructive; plan is free. (Cluster mode has the same rule with different verbs: cluster plan before cluster apply — the plan embeds the engine's real migration steps.)

Branches are for data; apply is for schema — review bulk data loads on a feature branch then merge. Schema changes go straight to main: in cluster mode edit the .pg and run cluster apply (a direct schema apply refuses a cluster-managed graph); schema plan/apply is for a non-cluster store.

Pick the right write command — mutate for edits (typechecked, parameterized); load for bulk JSONL, local or remote, with a required --mode (merge upsert · append strict-insert · overwrite clean-slate). load --from <base> forks a review branch in one shot; bare load needs an existing target branch.

Parameterize everything — never string-interpolate values into .gq bodies or --params. Declare $var: Type and pass via --params.

Expose agent operations as aliases — not raw CLI invocations. Aliases decouple the operation name from the query implementation.

Verify after every remote write — compare commit list --branch main head before and after. The CLI's exit code is not authoritative on remote graphs; proxies can drop the response while the write commits server-side. See references/remote-ops.md for the verification ritual and how to recover from 504s.

Essentials: Queries, Mutations, Loads

Operating Omnigraph Locally

The Seven Rules

Lint before commit — omnigraph lint --schema schema.pg --query queries/foo.gq validates both sides against each other. No running repo required.

Parameterize everything — never string-interpolate values into .gq bodies or --params. Declare $var: Type and pass via --params.

Expose agent operations as aliases — not raw CLI invocations. Aliases decouple the operation name from the query implementation.

Essentials: Queries, Mutations, Loads

// Query Grammar (.gq files) WHITESPACE = _{ " " | "\t" | "\r" | "\n" } COMMENT = _{ LINE_COMMENT | BLOCK_COMMENT } LINE_COMMENT = _{ "//" ~ (!"\n" ~ ANY)* } BLOCK_COMMENT = _{ "/*" ~ (!"*/" ~ ANY)* ~ "*/" } query_file = { SOI ~ query_decl* ~ EOI } query_decl = { "query" ~ ident ~ "(" ~ param_list? ~ ")" ~ query_annotation* ~ "{" ~ query_body ~ "}" } query_annotation = { description_annotation | instruction_annotation } description_annotation = { "@description" ~ "(" ~ string_lit ~ ")" } instruction_annotation = { "@instruction" ~ "(" ~ string_lit ~ ")" } query_body = { read_query_body | mutation_body } mutation_body = { mutation_stmt+ } read_query_body = { match_clause ~ return_clause ~ order_clause? ~ limit_clause? } mutation_stmt = { insert_stmt | update_stmt | delete_stmt } insert_stmt = { "insert" ~ type_name ~ "{" ~ mutation_assignment+ ~ "}" } update_stmt = { "update" ~ type_name ~ "set" ~ "{" ~ mutation_assignment+ ~ "}" ~ "where" ~ mutation_predicate } delete_stmt = { "delete" ~ type_name ~ "where" ~ mutation_predicate } mutation_assignment = { ident ~ ":" ~ match_value ~ ","? } mutation_predicate = { ident ~ comp_op ~ match_value } param_list = { param ~ ("," ~ param)* } param = { variable ~ ":" ~ type_ref } type_ref = { (list_type | base_type | vector_type) ~ "?"? } list_type = { "[" ~ base_type ~ "]" } vector_type = { "Vector" ~ "(" ~ integer ~ ")" } base_type = { "String" | "Blob" | "Bool" | "I32" | "I64" | "U32" | "U64" | "F32" | "F64" | "DateTime" | "Date" } match_clause = { "match" ~ "{" ~ clause+ ~ "}" } clause = { negation | binding | traversal | filter | text_search_clause } text_search_clause = { search_call | fuzzy_call | match_text_call } // Binding: $p: Person { name: "Alice" } binding = { variable ~ ":" ~ type_name ~ ("{" ~ prop_match_list ~ "}")? } prop_match_list = { prop_match ~ ("," ~ prop_match)* ~ ","? } prop_match = { ident ~ ":" ~ match_value } match_value = { literal | variable | now_call } // Traversal: $p knows $f (directional) or $p <knows> $f (undirected, >= 0.8.1) // Edge binding: $p $w:knows $f then $w.prop in filter/return (>= 0.9.0) traversal = { variable ~ edge_binding? ~ (undirected_edge | edge_ident) ~ traversal_bounds? ~ variable } edge_binding = { variable ~ ":" } undirected_edge = { "<" ~ edge_ident ~ ">" } traversal_bounds = { "{" ~ integer ~ "," ~ integer? ~ "}" } // Filter: $f.age > 25 filter = { expr ~ filter_op ~ expr } // Negation: not { ... } negation = { "not" ~ "{" ~ clause+ ~ "}" } // Return clause — projections separated by commas or newlines return_clause = { "return" ~ "{" ~ projection+ ~ "}" } projection = { expr ~ ("as" ~ ident)? ~ ","? } // Order clause order_clause = { "order" ~ "{" ~ ordering ~ ("," ~ ordering)* ~ "}" } ordering = { nearest_ordering | (expr ~ order_dir?) } nearest_ordering = { "nearest" ~ "(" ~ prop_access ~ "," ~ expr ~ ")" } order_dir = { "asc" | "desc" } // Limit clause limit_clause = { "limit" ~ integer } // Expressions expr = { now_call | nearest_ordering | search_call | fuzzy_call | match_text_call | bm25_call | rrf_call | agg_call | prop_access | variable | literal | ident } now_call = { "now" ~ "(" ~ ")" } search_call = { "search" ~ "(" ~ expr ~ "," ~ expr ~ ")" } fuzzy_call = { "fuzzy" ~ "(" ~ expr ~ "," ~ expr ~ ("," ~ expr)? ~ ")" } match_text_call = { "match_text" ~ "(" ~ expr ~ "," ~ expr ~ ")" } bm25_call = { "bm25" ~ "(" ~ expr ~ "," ~ expr ~ ")" } rank_expr = { nearest_ordering | bm25_call } rrf_call = { "rrf" ~ "(" ~ rank_expr ~ "," ~ rank_expr ~ ("," ~ expr)? ~ ")" } prop_access = { variable ~ "." ~ ident } agg_call = { agg_func ~ "(" ~ expr ~ ")" } agg_func = { "count" | "sum" | "avg" | "min" | "max" } comp_op = { ">=" | "<=" | "!=" | ">" | "<" | "=" } filter_op = { "contains" | comp_op } // Terminals variable = @{ "$" ~ (ident_chars | "_") } ident_chars = @{ (ASCII_ALPHA_LOWER | "_") ~ (ASCII_ALPHANUMERIC | "_")* } // Edge identifier — lowercase start, same as ident but used in traversal context // Must not match keywords edge_ident = @{ !("not" ~ !ASCII_ALPHANUMERIC) ~ (ASCII_ALPHA_LOWER | "_") ~ (ASCII_ALPHANUMERIC | "_")* } type_name = @{ ASCII_ALPHA_UPPER ~ (ASCII_ALPHANUMERIC | "_")* } ident = @{ (ASCII_ALPHA_LOWER | "_") ~ (ASCII_ALPHANUMERIC | "_")* } literal = { list_lit | datetime_lit | date_lit | string_lit | float_lit | integer | bool_lit } date_lit = { "date" ~ "(" ~ string_lit ~ ")" } datetime_lit = { "datetime" ~ "(" ~ string_lit ~ ")" } list_lit = { "[" ~ (literal ~ ("," ~ literal)*)? ~ "]" } string_lit = @{ "\"" ~ string_char* ~ "\"" } string_char = @{ !("\"" | "\\") ~ ANY | "\\" ~ ANY } float_lit = @{ ASCII_DIGIT+ ~ "." ~ ASCII_DIGIT+ } integer = @{ ASCII_DIGIT+ } bool_lit = { "true" | "false" }

Trap

Symptom

Fix

# comments in .pg

parse error: expected schema_file

Use //

Standalone enum Foo { ... } block

parse error: expected EOI or schema_decl

Inline: kind: enum(a, b)

[Category] (list of enum)

compile error

Use [String]; lists must contain scalars

@embed(text) without quotes

unexpected constraint_name

@embed("text")

@unique(src) on edge without body block

parse error

@card(1..1) { @unique(src) }

load --mode merge after @embed source change

stale embeddings

omnigraph embed --reembed_all or load --mode overwrite

schema apply with feature branches open

rejected

Merge or delete branches first

nearest(...) / bm25(...) / rrf(...) without limit

compile error

Add limit N

Adding non-nullable property without backfill

unsupported migration

Make optional → backfill; keep it optional (tightening T? → T is refused, OG-MF-106)

omnigraph init --json

unexpected argument --json

init doesn't support --json; drop the flag

omnigraph init on an already-initialized URI

AlreadyInitialized error (v0.6.0+)

--force to re-init (skips the schema preflight; does not purge data)

schema apply dropping a property/type

soft-dropped or rejected (no data loss)

add --allow-data-loss to actually drop the column

Committing .env.omni

credential leak

Add .env* to .gitignore

Non-parameterized query values

typecheck surprise, injection risk

Declare $param: Type and pass via --params

Missing required field in insert

T12: insert for 'X' must provide non-nullable property 'Y'

Accept the param in the mutation signature

Long-lived feature branches

merge conflicts, schema apply blocked

Merge promptly; delete when done

mutation { ... } wrapper in .gq

parse error: expected query_file at line 1

Use query <name>(...) { insert T { ... } }; there is no top-level mutation keyword

--config placed before subcommand

unexpected argument --config

Put --config after the subcommand (e.g. omnigraph schema show --config X)

Reading a large schema via stdout-capped tool

Truncated, garbled, or duplicated output

omnigraph schema show > /tmp/schema.pg first; then read the file with offset/limit

omnigraph load without --mode

error: --mode is required

Pass --mode merge|append|overwrite — there is no default (overwrite is destructive, so it is never implicit). load works against local and remote URIs

Blind retry after 504

Duplicate Signal/Decision/Claim (append-only types lack @key dedup)

commit list --branch main --json first; head advanced means it landed; only retry if unchanged

sync_branch() mentioned in version-drift error

Searching for nonexistent CLI command

Server-internal directive in error text; just retry — the next call re-pins to the new head

Stale empty branches at main's head

504-orphaned forks from a timed-out load --from; eventually block writes

List branches, find ones at main's graph_commit_id, omnigraph branch delete <name> --store <graph-uri>

omnigraph schema apply / init on a cluster-managed graph

refused — bypasses the cluster ledger

Evolve cluster graphs via omnigraph cluster apply --config .; schema apply/init are for a non-cluster store

omnigraph optimize against a table with a Blob property

table is skipped, not failed (Lance blob-v2 compaction bug)

Expected — --json reports it under skipped; non-blob tables still compact

@unique on a [List]/Blob column

load now errors loudly (was silently un-enforced before #160)

Use @unique only on scalar columns (and composite @unique(a, b), now keyed as a true tuple) — uniqueness needs a type that reduces to a scalar key

name	omnigraph
description	Store, retrieve, and query knowledge, memory, and relationships in an Omnigraph graph, and operate a local or remote Omnigraph deployment. Use when the user wants to capture or recall facts, notes, or entities, build or query a knowledge graph or agent memory, or run Omnigraph — and whenever you see Omnigraph CLI commands (omnigraph init/query/mutate/load/schema/lint/embed/branch/commit/login/profile/cluster), .pg schema or .gq query files, s3:// graph URIs, bearer-authed graph endpoints, 504 errors, or a cluster.yaml / omnigraph.yaml / ~/.omnigraph/config.yaml. Covers cluster-mode deployments (cluster.yaml plan/apply, omnigraph-server --cluster), the two config surfaces (cluster.yaml + ~/.omnigraph/config.yaml), schema evolution, query linting, data writes (mutate; load needs --mode/--from), branches, embeddings, Cedar policy, and remote ops. Especially important before schema apply (plan first), any load (--mode required), any .gq/.pg edit (lint after), or any remote write (verify via commit list).
license	MIT (see LICENSE at repo root)
compatibility	Requires omnigraph CLI >= 0.7.0 — the unified `load`, the two config surfaces (cluster.yaml + ~/.omnigraph/config.yaml), and cluster apply/serve all require 0.7.0. Version-gated features are marked inline (undirected traversal `<edge>` and enum widening in `schema apply` require >= 0.8.1; edge bindings `$w:EDGE`, strict `--mode append` key conflicts, the keyed per-load bounds, and `branch merge --delete-branch` require >= 0.9.0).
metadata	{"author":"ModernRelay","version":"0.10.0","repository":"https://github.com/ModernRelay/omnigraph"}

name	omnigraph
description	Store, retrieve, and query knowledge, memory, and relationships in an Omnigraph graph, and operate a local or remote Omnigraph deployment. Use when the user wants to capture or recall facts, notes, or entities, build or query a knowledge graph or agent memory, or run Omnigraph — and whenever you see Omnigraph CLI commands (omnigraph init/query/mutate/load/schema/lint/embed/branch/commit/login/profile/cluster), .pg schema or .gq query files, s3:// graph URIs, bearer-authed graph endpoints, 504 errors, or a cluster.yaml / omnigraph.yaml / ~/.omnigraph/config.yaml. Covers cluster-mode deployments (cluster.yaml plan/apply, omnigraph-server --cluster), the two config surfaces (cluster.yaml + ~/.omnigraph/config.yaml), schema evolution, query linting, data writes (mutate; load needs --mode/--from), branches, embeddings, Cedar policy, and remote ops. Especially important before schema apply (plan first), any load (--mode required), any .gq/.pg edit (lint after), or any remote write (verify via commit list).
license	MIT (see LICENSE at repo root)
compatibility	Requires omnigraph CLI >= 0.7.0 — the unified `load`, the two config surfaces (cluster.yaml + ~/.omnigraph/config.yaml), and cluster apply/serve all require 0.7.0. Version-gated features are marked inline (undirected traversal `<edge>` and enum widening in `schema apply` require >= 0.8.1; edge bindings `$w:EDGE`, strict `--mode append` key conflicts, the keyed per-load bounds, and `branch merge --delete-branch` require >= 0.9.0).
metadata	{"author":"ModernRelay","version":"0.10.0","repository":"https://github.com/ModernRelay/omnigraph"}

Surface	Owner	Location	Declares
Cluster config	the team, in the repo	`cluster.yaml` + the `.pg`/`.gq`/policy files it references	what the system is: graphs, schemas, queries, policies, storage
Operator config	one person	`~/.omnigraph/config.yaml` (`$OMNIGRAPH_HOME` relocates it)	who I am: identity, named servers, output defaults, personal aliases
Flags / env	per invocation	—	everything, explicitly

Reference	When to load
`references/schema.md`	Editing `.pg` files, running `schema plan`/`apply`, renaming types, backfilling required fields
`references/queries.md`	Writing or linting `.gq` files, search functions, aggregations, multi-hop patterns
`references/data.md`	Choosing between `mutate` and `load` (required `--mode`, `--from` to fork a review branch); branch review workflow; destructive ops
`references/remote-ops.md`	Operating against a remote/CloudFront-fronted graph: 504 verification ritual, version drift, fork-branch 504 fingerprints, append-only retry safety, operator `--server`/`login` targeting
`references/search.md`	Embeddings, `@embed`, vector/text ranking, scope-then-rank pattern
`references/aliases.md`	Defining aliases for agents, structured output, JSON args
`references/stored-queries.md`	Server-side stored-query registry: declared in `cluster.yaml`, `omnigraph queries validate/list`, `GET /graphs/{id}/queries` + `POST /graphs/{id}/queries/{name}`, `invoke_query` Cedar gating
`references/server-policy.md`	Starting the HTTP server, routes, bearer auth, Cedar policy gating, multi-graph mode
`references/commands.md`	`snapshot`, `export`, `commit list/show`, addressing & resolution
`references/migrations.md`	Migrating a pre-0.7.0 setup, or you hit an old config/command/flag/route/error and need its current form

omnigraph

Install options

Review the source files

Operating Omnigraph Locally

The Seven Rules

Essentials: Queries, Mutations, Loads

Operating Omnigraph Locally

The Seven Rules

Essentials: Queries, Mutations, Loads

Read query (`.gq`)

Mutation (`.gq`)

Bulk load (JSONL)

Dispatching

`.gq` grammar

CLI Reference (condensed)

Five Ontology Design Criteria (Gruber 1993)

Schema Authoring Principles

Provenance Is Structural (Multi-Agent Source of Truth)

Storage & Credentials

Project Layout

Deployment & access (omnigraph >= 0.7.0)

The two config surfaces (omnigraph >= 0.7.0)

What to commit

Give agents a `CLAUDE.md`

Common Gotchas

Deep Dives

omnigraph

Source facts

Install options

Review the source files

Operating Omnigraph Locally

The Seven Rules

Essentials: Queries, Mutations, Loads

Operating Omnigraph Locally

The Seven Rules

Essentials: Queries, Mutations, Loads

Read query (.gq)

Mutation (.gq)

Bulk load (JSONL)

Dispatching

.gq grammar

CLI Reference (condensed)

Five Ontology Design Criteria (Gruber 1993)

Schema Authoring Principles

Provenance Is Structural (Multi-Agent Source of Truth)

Storage & Credentials

Project Layout

Deployment & access (omnigraph >= 0.7.0)

The two config surfaces (omnigraph >= 0.7.0)

What to commit

Give agents a CLAUDE.md

Common Gotchas

Deep Dives

Read query (`.gq`)

Mutation (`.gq`)

`.gq` grammar

Give agents a `CLAUDE.md`