Time Travel

Every write to an Omnigraph repository creates a new immutable snapshot. Because snapshots are never modified or deleted, you can read the graph as it existed at any point in its history.

How snapshots work

A snapshot is an immutable record of the entire graph state at a moment in time. Each branch points to a snapshot, and every write advances the branch to a new one.

Snapshots are not diffs or deltas — each snapshot is a self-contained view of the graph. Under the hood, unchanged tables are shared across snapshots (copy-on-write), so storage grows only with actual changes.

Key properties:

• Immutable — Once created, a snapshot is never modified.
• Addressable by snapshot id — Historical reads use a string snapshot id, typically a graph commit id.
• Versioned for branch inspection — manifest_version tracks the visible branch version in snapshot and commit output.

Reading the current snapshot

To see the current manifest version and table state of a branch:

omnigraph snapshot ./repo.omni

{
  "branch": "main",
  "manifest_version": 5,
  "tables": [
    { "table_key": "Person", "table_path": "nodes/Person", "table_version": 3, "table_branch": "main", "row_count": 847 },
    { "table_key": "Company", "table_path": "nodes/Company", "table_version": 2, "table_branch": "main", "row_count": 124 },
    { "table_key": "WorksAt", "table_path": "edges/WorksAt", "table_version": 2, "table_branch": "main", "row_count": 912 }
  ]
}

The manifest_version is the branch's current visible version. Each table has its own version that advances independently when that table is modified.

Finding snapshot ids

Use commit list to enumerate graph commits for a branch:

omnigraph commit list ./repo.omni --branch main --json

{
  "commits": [
    {
      "graph_commit_id": "01JQ6V6T4R3Y6Z8W1M8E0S4R9C",
      "manifest_branch": "main",
      "manifest_version": 5,
      "parent_commit_id": "01JQ6V1VJ2E5N4K4T7T3A0M1D9",
      "merged_parent_commit_id": null,
      "actor_id": null,
      "created_at": 1744452000
    }
  ]
}

graph_commit_id is the snapshot id you pass to read --snapshot.

Querying at a specific snapshot id

Use the --snapshot flag to read the graph as it existed at a past graph commit:

omnigraph read --uri ./repo.omni \
    --query queries.gq \
    --name all_people \
    --snapshot 01JQ6V6T4R3Y6Z8W1M8E0S4R9C \
    --json

This runs the query against the graph state at that snapshot id, regardless of what the current branch head is.

Use cases

• Debugging — Query the graph before and after a mutation to isolate what changed
• Auditing — Review the exact state of the graph at the time a decision was made
• Reproducibility — Re-run a query at a known snapshot to reproduce past results
• Rollback analysis — Inspect a known-good historical state before deciding what to reapply on a new branch