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 roll back to any previous version or revert a specific merge.
• 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 --from main agent-enrichment-042
# Agent does work on the branch
omnigraph branch diff agent-enrichment-042 main
# Review the diff
omnigraph branch merge 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 --from main agent-analysis-run
# Agent writes analysis results...

# Human reviews
omnigraph branch diff agent-analysis-run main
# Human approves
omnigraph branch merge 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
# List available versions
omnigraph read ./repo.omni --version 42 --query diagnostic.gq

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 --from main approach-a
omnigraph branch create --from main approach-b
# Agent A works on approach-a
# Agent B works on approach-b
omnigraph branch diff approach-a main
omnigraph branch diff approach-b main
# Compare, pick the better one, merge it
omnigraph branch merge approach-a --into main

Compliance and audit trails

For regulated domains, every decision and data change must be traceable. Model decisions as nodes so they're part of the graph.

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

edge HasDecision: Review -> Decision

Combined with branch history, this gives you a complete audit trail: who made what decision, when, based on what evidence, and what data changed as a result.

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