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).
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).
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 applyrefuses 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
The patterns below cover the daily 80% — enough to write correct .gq and JSONL without leaving this file. The long tail (multi-hop, negation, aggregations, hybrid search, every decorator) is in references/queries.md and references/schema.md.
Comments in .pg and .gq are //, never # (the #1 parse error).
Read query (.gq)
query get_signal($slug: String) {
match {
$s: Signal { slug: $slug } // inline property filter goes in the match block
$s formsPattern $p // edge FormsPattern declared PascalCase, traversed lowerCamelCase
}
return { $s.slug, $s.name, $p.slug }
}
Parameterize, never interpolate. Declare $var: Type in the signature; pass via --params '{"slug":"sig-foo"}'. An empty signature still needs parens: query foo() { ... }.
Edge traversal is lowerCamelCase even though the schema declares edges PascalCase (FormsPattern → formsPattern).
List/sort by appending order { $s.stagingTimestamp desc } limit 50 after return.
Ranking ops (nearest/bm25/rrf) require a trailing limit N — omitting it is a compile error. They live in order { }, not as filters. Scope with match/filters first, then rank (order { nearest($d.embedding, $q) } limit 10).
Mutation (.gq)
There is no top-level mutation { } — every block is a named query; the verb (insert/update/delete) makes it a write. Dispatch with omnigraph mutate (not query).
omnigraph load --data seed.jsonl --mode merge $GRAPH# --mode is REQUIRED (no default)
omnigraph load --data delta.jsonl --from main --branch review --mode merge $GRAPH# fork a review branch in one shot
--mode: merge (upsert by @key) · append (fails on collision) · overwrite (destructive, staged). --from <base> forks a missing --branch; bare load needs an existing branch. Works local and remote.
Date footgun: mutate --params takes ISO strings (Date"2026-04-29", DateTime"…T00:00:00Z"); load JSONL takes integer days since epoch for Date (20572) but ISO for DateTime.
Dispatching
omnigraph alias signal sig-foo # operator alias → its bound stored query (read or write)
omnigraph query get_signal --params '{"slug":"sig-foo"}'# served stored query by name (verb asserts read vs write)
omnigraph query -e 'query q() { match { $s: Signal } return { $s.slug } limit 5 }'# ad-hoc/inline (or: --query f.gq <name>)
omnigraph mutate add_signal --query mutations.gq --params '{"slug":"sig-foo", ...}'# name positional; ad-hoc file source
omnigraph lint --schema schema.pg --query queries/foo.gq # after EVERY .gq/.pg edit (no server needed)
.gq grammar
The non-obvious facts that bite, then the full grammar:
Scalar param types: String Bool I32 I64 U32 U64 F32 F64 DateTime Date Blob. Modifiers: T? (optional), [T] (list), Vector(N). There is no Int — use I64.
A read query needs matchandreturn (order/limit optional); a mutation has neither — only insert/update/delete.
limit takes an integer literal, not a param — limit 50, never limit $n.
Variable-hop traversal: $p knows{1,3} $f — bounds are required to be finite ({1,} is rejected: "unbounded traversal is disabled").
Undirected traversal (omnigraph >= 0.8.1): $p <knows> $f matches the edge in either direction, deduplicated (a pair connected both ways appears once). Same-endpoint-type edges only (e.g. Related: Issue -> Issue) — asymmetric edges are rejected (T22). Composes with bounds ($p <knows>{1,3} $f) and not { }. Replaces the query-both-directions-and-merge workaround for symmetric relations.
Edge bindings (omnigraph >= 0.9.0): an optional $var: prefix on the edge word — $src $w:knows $dst, undirected $a $w:<related> $b — binds the matched edge row, so edge properties work in filters ($w.confidence = "asserted"), projections (return { $w.role }), aggregates, and ordering. A bound traversal returns one row per edge (parallel edges stay distinct); binding a {min,max} multi-hop, rebinding a taken name, or projecting bare $w is rejected (T23).
Literals & calls: now(), date("2026-04-29"), datetime("…T00:00:00Z"), list […].
Global addressing flags: --as <actor> (direct/--store writes only — a server resolves the actor from its token), --server <name|url>, --cluster <dir|uri> (cluster-managed storage, for maintenance), --graph <id> (selects the graph within a --server or --cluster scope), --profile <name> ($OMNIGRAPH_PROFILE), --store <uri>. Data commands also take a positional file:///s3:// URI (--config <dir> is for cluster commands only). Output: --json, or reads take --format <json|jsonl|csv|kv|table>. Write guards:--yes skips the confirm prompt for a destructive write (cleanup, overwrite load, branch delete) against a non-local scope (it refuses without it when non-TTY or --json); --quiet suppresses the resolved-target echo.
Data plane — any (served via --server/--profile, or direct via --store/URI):
query (alias read) <name> — a served stored query by name (via --server/--profile); or ad-hoc [<name>] (--query <f.gq> | -e '<GQ>') where <name> picks which query in the source. [--params <json> | --params-file <p>] [--branch <b> | --snapshot <id>] [--format <fmt> | --json]. No positional URI — address via --server/--store/--profile.
mutate (alias change) — same shape (served stored mutation by <name>, or ad-hoc --query/-e); [--params …] [--branch <b>] [--json]. The verb asserts kind: query→read, mutate→write (400 on mismatch).
alias <name> [args…] — invoke an operator alias's bound stored query (read or write); [--params … | --params-file <p>] [--format <fmt> | --json] (server/graph/query come from the binding)
Omnigraph schemas are ontologies. The canonical design criteria from Gruber's Toward Principles for the Design of Ontologies Used for Knowledge Sharing (Int. J. Human-Computer Studies 43:907–928) apply directly when authoring .pg files.
Clarity — definitions should communicate intended meaning unambiguously and be independent of social or computational context. In Omnigraph: precise type names, narrow enums over String, @check/@range for stated invariants. A reviewer should understand the domain from the schema alone.
Coherence — inferences sanctioned by the schema must be consistent with the domain modeled. Gruber's trap: defining quantity as a (magnitude, unit) pair makes 6 feet ≠ 2 yards even though they describe the same length. In Omnigraph: watch for @card, @unique, and edge directionality that let the schema distinguish things the domain treats as equal.
Extendibility — the schema should support specialization without revising existing definitions. In Omnigraph: prefer interfaces for shared shape, leave enums open where the domain genuinely admits more, model identifiers via mapping functions rather than baking units/formats into the entity.
Minimal encoding bias — representation choices made for notation or implementation convenience leak into the model. In Omnigraph: don't type dates as String because the source API returns strings; separate conceptual entities (a publication date, a person) from their surface encoding (a year integer, a name string) when both matter.
Minimal ontological commitment — make as few claims about the world as the use case requires. In Omnigraph: don't add required properties, closed enums, or @card(1..1) "in case"; tighten later via schema plan/apply when a real constraint emerges. Weaker schemas leave consumers room to specialize.
The criteria trade off against each other — Clarity wants tight definitions while Minimal Commitment wants weak ones. Gruber's resolution: having decided a distinction is worth making, give it the tightest possible definition. Decide what to model conservatively; once modeled, constrain precisely.
Schema Authoring Principles
Twelve practical rules for .pg authoring — full text and examples in the bundled references/schema.md. In short: schema-is-the-contract · explicit identity via @key · model meaning not tables · strong intentional types · deliberate optionality · shared shape in interfaces · schema-level constraints (@unique/@index/@range/@check/@card) · search as a schema decision · edge semantics matter · reviewable schemas · intentional migrations (@rename_from) · domain clarity over ORM habits.
Design flow: entities → stable keys → relationships worth their own edge → enum candidates → uniqueness/bounds/cardinality → search needs → shared shape into interfaces → evolution plan.
Provenance Is Structural (Multi-Agent Source of Truth)
When Omnigraph serves as canonical truth across multiple agents, every assertion must answer who said it, when, based on what evidence. This is the runtime guarantee Gruber's criteria don't cover — his agents shared vocabulary; ours additionally must share attribution. Provenance belongs in the schema, not in logs.
Without structural provenance, agents cannot reconcile contradictory assertions, retract facts when a source is discredited, replay graph state at a past timestamp, or distinguish high-evidence facts from speculation.
In Omnigraph: model provenance as a Claim-style interface (or a separate Claim node linked to each sourced fact) with required fields — asserted_by: Actor, asserted_at: DateTime, evidence_source: Source, optionally confidence: F64. Don't stash provenance into a free-text source: String or a metadata: JSON dump — structured provenance is queryable, indexable, and migratable; free-form is none of these.
Storage & Credentials
A graph's bytes live in one of two backends:
Local filesystem — a path or file:// URI. In cluster mode storage: defaults to the config directory, so local dev needs no object store.
S3-compatible object storage — AWS, Railway, Tigris, etc. (s3://bucket/prefix). Authenticate with the standard AWS_* environment contract; keep dev creds in a git-ignored .env.omni and source it before CLI calls:
set -a && source .env.omni && set +a
init, load, and cluster apply write storage directly (bypassing the server). cluster apply is a storage-direct control-plane command — it reaches the object store directly (the __cluster/ ledger and each graph's Lance datasets, to create/migrate/delete them), never through a running server, so the host that runs it needs storage access (the AWS_* contract for an s3:// cluster). That is by design: the control plane is declarative (config → cluster), not a runtime mutation API on the serving process. The server reads cluster state read-only at boot, but it is not read-only against storage overall — data-plane HTTP writes (mutate/load/branch) still go through the server to the graph datasets, so it needs read-write storage access. Validate with curl http://127.0.0.1:8080/healthz, then omnigraph snapshot <graph-uri> --json.
Project Layout
Deployment & access (omnigraph >= 0.7.0)
Cluster deployment — the only way to serve. A cluster.yaml declares the
whole deployment (graphs, schemas, stored queries, policies, optional S3
storage: root); omnigraph cluster apply converges it and
omnigraph-server --cluster . (or --cluster s3://bucket/prefix,
config-free) serves it. See references/cluster.md.
Direct / embedded access — no server. Address a graph's storage directly
with --store <file://|s3:// uri> or a positional URI for one-off CLI ops.
There is no single-graph server mode — the server is cluster-only.
The two config surfaces (omnigraph >= 0.7.0)
Configuration has two single-owner homes (RFC-007/008), plus an
everything-explicit flag/env tier:
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
who I am: identity, named servers, output defaults, personal aliases
Flags / env
per invocation
—
everything, explicitly
# ~/.omnigraph/config.yaml — per operator, never committedoperator:actor:act-andrew# default --as identityservers:intel-dev:url:https://graph.example.com# no tokens here, everdefaults:output:table# read-format defaultserver:intel-dev# default served scope (or `store: file://…/g.omni` for a local default — mutually exclusive)default_graph:spike# graph within a server/cluster scopeprofiles:# optional named scope bundles — pick with --profile <name>staging: { server:intel-staging, default_graph:spike }
aliases:# personal bindings to TEAM stored queries (see references/aliases.md)triage: { server:intel-dev, graph:spike, query:weekly_triage, args: [since] }
The operator config and credentials are auto-discovered — no flag points at them: the CLI reads $OMNIGRAPH_HOME/config.yaml (default ~/.omnigraph/config.yaml), and an absent file is just an empty layer (zero-config). $OMNIGRAPH_HOME relocates the directory only, not a specific file. (--config/$OMNIGRAPH_CONFIG is a separate flag for the cluster / server config — not this.)
Credentials live outside config: echo $TOKEN | omnigraph login intel-dev
writes ~/.omnigraph/credentials (0600); the matching token resolves via
OMNIGRAPH_TOKEN_INTEL_DEV or that file.
Addressing a graph: --store <file://|s3:// uri> or a positional URI for
direct storage; --server <name|url> (+ --graph <id>) for a served remote;
--profile <name> for a named bundle; else the operator defaults. A remote is
addressed with --server (a bare http(s):// URL is not a graph address). Run
data-plane commands from a graph's project folder so relative queries/,
schema.pg, and .env.omni paths resolve.
What to commit
Commit:schema.pg, queries/*.gq, cluster.yaml, seed.md, seed.jsonl, and the project's README.md and CLAUDE.md.
Ignore:.env.omni (credentials), .claude/ (local agent state), *.omni/ (local graph artifacts), __cluster/ and graphs/ (cluster state + derived graph roots).
Give agents a CLAUDE.md
A per-project CLAUDE.md tells coding agents where files live and what conventions matter. Without it, agents re-discover the same things every session.
Common Gotchas
These are the traps most likely to bite. Scan this table before debugging any parse or runtime error.
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 --configafter 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
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
