Gess documentation

Gess is a Go rules engine with a Rete-based runtime and a .gess file format for defining templates, seed facts, rules, and queries outside app code.

Start here

New to Gess? Follow this path:

1. Write templates, facts, rules, and queries in a .gess file. See the .gess language reference or jump straight into the tutorial.
2. Generate Go with gessc. See command-line tools.
3. Build a session from the generated ruleset and run it. See the Go API guide and session lifecycle.
4. Read results back with queries. See session lifecycle.

TUTORIAL.md walks through all four steps with one worked example, examples/gess-files/order_routing. For a hands-on workshop with checkpoints and guided edits, run the interactive tutorial locally instead of reading along.

Guides

Once the basics are working, these guides go deeper:

• Core concepts: templates, facts, rules, activations, the agenda, sessions, rulesets, and queries.
• The .gess language reference: every form the .gess parser accepts, with limits and errors.
• Go API guide: building templates, rules, queries, actions, pure functions, and portable scenario, report, and value JSON with the rules, session, dsl, and scenario packages.
• Session lifecycle: assert, modify, retract, reset, run, queries, snapshots, events, the focus stack, and ApplyRuleset.
• Executable semantics: evaluation truth tables, condition and lifecycle semantics, ordering guarantees, and the differential fuzz verification contract.
• Runtime diagnostics JSON: versioned graph, memory, agenda, terminal, aggregate, query, truth-maintenance, and backchain reports.
• Explain JSON: the versioned, one-way contract for derivations, why-not reports, and counterfactual runs.
• Value JSON: the lossless, deterministic typed-value contract shared by scenarios, reports, Workbench, and MCP.
• Scenario and report JSON: the strict, versioned, byte-deterministic artifact contracts for portable scenario inputs and run reports.
• Command-line tools: the gess REPL, gessc, gessfmt, and the gess-mcp agent-facing stdio server.
• Advanced behavior: the Rete runtime, expression predicate placement, aggregates, higher-order conditions, logical support, backward chaining, and module focus.
• Examples map: what each example demonstrates, organized by feature, and where to start.
• Interactive tutorial workshop: a local browser or terminal workshop with checkpoints for the vulnerability response scenario.
• Developer guide: repository layout, engine architecture, tests, benchmarks, and the documentation workflow.