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).

跳到安装

仓库: ModernRelay/omnigraph
最近来源活动: 2026年8月23日 10:11
检测到的 SKILL.md 语言: 英语
星标: 1,085
分支: 247

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

直接命令不会经过审查 Prompt；运行前请先检查来源。

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

命令会保持在同一行。复制前请横向滚动并检查完整内容。

想先保存到本地？可下载 SkillsMP 当前能够提供的文件。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

文件资源管理器

12 个文件

SKILL.md

来源说明 · 只读预览

返回搜索返回安装

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

安装方式

检查来源文件

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

来源信息

安装方式

检查来源文件

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`