Governance

When multiple agents write to the same knowledge base, you need governance -- rules that control what changes land, who made them, and how to undo mistakes. Omnigraph builds governance into the database layer so you don't have to build it yourself.

Core principles

Every change to an Omnigraph repository is:

• Versioned -- Every mutation creates a new version. You can inspect any historical state.
• Isolated -- Changes happen on branches. Nothing touches main until explicitly merged.
• Auditable -- Every branch, merge, and mutation records who did what and when.
• Reversible -- You can inspect earlier graph commits and restore state with explicit branch workflows.
• Gated -- Merge can require validation, review, or automated checks before landing.

Patterns

Branch-per-action

Every agent action gets its own branch. This is the simplest governance pattern: nothing goes to main without a merge.

omnigraph branch create --uri ./repo.omni --from main agent-enrichment-042
# Agent does work on the branch
# Review the branch with snapshot and validation queries
omnigraph snapshot ./repo.omni --branch agent-enrichment-042
omnigraph branch merge --uri ./repo.omni agent-enrichment-042 --into main

If the agent's work is bad, you don't merge. The branch can be inspected, fixed, or deleted.

Human-in-the-loop

Require human review before merging agent branches. The agent writes to a branch and signals that it's ready for review. A human (or a review agent) inspects the diff and approves.

# Agent creates and populates the branch
omnigraph branch create --uri ./repo.omni --from main agent-analysis-run
# Agent writes analysis results...

# Human reviews
omnigraph read --uri ./repo.omni --query review.gq --name pending_review --branch agent-analysis-run
# Human approves
omnigraph branch merge --uri ./repo.omni agent-analysis-run --into main

Automated quality gates

Run validation queries against a branch before allowing a merge. If the queries find problems, the merge is blocked.

query orphaned_nodes() {
    match {
        $n: Contact
        not { $n belongsTo $a: Account }
    }
    return { $n.name }
}

If this query returns results on the branch, the agent created contacts without linking them to accounts. Block the merge until fixed.

Time-travel debugging

When something goes wrong, inspect the graph at any previous point in time.

omnigraph snapshot ./repo.omni
omnigraph commit list ./repo.omni --branch main
omnigraph read --uri ./repo.omni --query diagnostic.gq --snapshot <graph-commit-id>

Compare the current state to a historical state to find when a problem was introduced.

Parallel experiments

Run multiple approaches on separate branches and compare results before committing to one.

omnigraph branch create --uri ./repo.omni --from main approach-a
omnigraph branch create --uri ./repo.omni --from main approach-b
# Agent A works on approach-a
# Agent B works on approach-b
omnigraph snapshot ./repo.omni --branch approach-a
omnigraph snapshot ./repo.omni --branch approach-b
# Compare, pick the better one, merge it
omnigraph branch merge --uri ./repo.omni approach-a --into main

Decisions as data

When the trail of why a change happened needs to be queryable — not just the data change itself — model decisions as nodes:

node Decision {
    outcome: String
    rationale: String
    decided_at: DateTime
    decided_by: String
    evidence_refs: [String]
}

edge HasDecision: Review -> Decision

Combined with branch history, you can trace who recorded what decision, when, and which graph commit captured the resulting data change. This is a data modeling pattern, not a compliance certification — Omnigraph does not sign or cryptographically chain these records.

Choosing a governance level

Start at the lowest level that meets your needs. You can increase governance later without changing your schema or queries.

What happens without governance