How Semantica Tracks Graph Modifications with Its Change Management Workflow

Semantica provides a Git-like versioning system for knowledge graphs through the TemporalVersionManager class, which records immutable snapshots, computes detailed diffs, and supports rollback to any prior state.

The semantica-agi/semantica repository implements a production-ready change management workflow for tracking modifications to knowledge graphs (KGs). At its core lies the TemporalVersionManager in semantica/change_management/managers.py, which transforms volatile graph operations into auditable, tamper-evident version histories suitable for regulatory compliance.

Understanding the TemporalVersionManager Architecture

The change management workflow centers on TemporalVersionManager, a persistent versioning layer that can use either SQLite for production workloads or an in-memory store for testing. Unlike simple logging, this system captures complete graph state snapshots with SHA-256 checksums, enabling cryptographic verification of data integrity.

Each snapshot stores node and edge collections under both legacy (entities, relationships) and modern (nodes, edges) keys, ensuring backward compatibility while supporting evolving data models.

Setting Up the Change Management Workflow

Initialize the Version Manager

Begin by instantiating TemporalVersionManager with a persistent storage path:

from semantica.change_management import TemporalVersionManager

manager = TemporalVersionManager(storage_path="versions.db")  # SQLite persistence

Source: [semantica/change_management/managers.py](https://github.com/semantica-agi/semantica/blob/main/semantica/change_management/managers.py)

Enable Automatic Mutation Tracking

For fine-grained audit events, attach the manager to your graph instance:

manager.attach_to_graph(my_graph)  # Records every add/remove operation

This injects a record_mutation callback into the graph's mutation_callback hook, capturing granular change events without manual instrumentation.

Source: [semantica/change_management/managers.py](https://github.com/semantica-agi/semantica/blob/main/semantica/change_management/managers.py)

Creating Snapshots Before and After Modifications

Capture Pre-Change State

Before any destructive operation—deduplication, merge, or conflict resolution—create an immutable baseline:

pre_snap = manager.create_snapshot(
    graph=my_graph.to_dict(),
    version_label="v1.0",
    author="alice@example.com",
    description="Snapshot before deduplication"
)

The create_snapshot method (lines 20-29 in managers.py) computes a SHA-256 checksum and persists metadata through a ChangeLogEntry object defined in semantica/change_management/change_log.py.

Source: create_snapshot

Apply Graph Modifications

Execute changes using Semantica's graph tool API:

from semantica.mcp.tools.graph import GRAPH_TOOLS

# Example: add a new node

add_entity_tool = next(t for t in GRAPH_TOOLS if t["name"] == "add_entity")
add_entity_tool["_handler"]({"id": "person_42", "label": "John Doe", "type": "Person"})

The GRAPH_TOOLS collection in semantica/mcp/tools/graph.py provides handlers like add_entity, add_relationship, and their removal counterparts.

Source: [semantica/mcp/tools/graph.py](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/graph.py)

Capture Post-Change State

Record the modified graph under a new version label:

post_snap = manager.create_snapshot(
    graph=my_graph.to_dict(),
    version_label="v2.0",
    author="alice@example.com",
    description="After deduplication"
)

Computing Diffs and Verifying Changes

Generate Detailed Difference Reports

The diff method (lines 68-71) compares any two versions and returns a structured report:

diff = manager.diff("v1.0", "v2.0")
print(diff["summary"])  # Contains counts of added/removed/modified entities and relationships

The diff includes:

• Full entity lists for additions and removals
• Relationship change tracking
• Summary statistics for quick overview

Source: diff

Validate Snapshot Integrity

Each snapshot carries a cryptographic checksum. Verify tamper-evidence with:

assert manager.verify_checksum(post_snap), "Data integrity violation detected"

Rolling Back to Previous States

Restore the graph to any prior snapshot using restore_snapshot (lines 80-92):

manager.restore_snapshot(my_graph, "v1.0", require_confirmation=False)

The require_confirmation parameter provides a safety guard against accidental data loss in production environments. When True, the method prompts for explicit operator confirmation before destructive restoration.

Source: restore_snapshot

Audit and Compliance Features

Semantica's change management workflow supports regulatory requirements including HIPAA, SOX, GDPR, and FDA 21 CFR Part 11 through:

• ChangeLogEntry validation: Enforces author email format, timestamps, and description requirements
• MutationRecord granularity: Tracks individual node/edge mutations via get_node_history
• Immutable checksums: SHA-256 verification prevents undetected tampering
• Complete provenance chains: Every change links to author identity and temporal context

Complete Workflow Example

# 1. Initialise manager with SQLite persistence

from semantica.change_management import TemporalVersionManager
manager = TemporalVersionManager(storage_path="kg_versions.db")

# 2. Attach automatic mutation tracking

manager.attach_to_graph(my_graph)

# 3. Snapshot before change

pre = manager.create_snapshot(
    graph=my_graph.to_dict(),
    version_label="pre-dedupe",
    author="bob@example.com",
    description="Baseline before deduplication"
)

# 4. Apply graph modifications

from semantica.mcp.tools.graph import GRAPH_TOOLS
add_tool = next(t for t in GRAPH_TOOLS if t["name"] == "add_entity")
add_tool["_handler"]({"id": "doc_1001", "label": "Medical Report", "type": "Document"})

# 5. Snapshot after change

post = manager.create_snapshot(
    graph=my_graph.to_dict(),
    version_label="post-dedupe",
    author="bob@example.com",
    description="After adding new document node"
)

# 6. Analyze changes

diff = manager.diff("pre-dedupe", "post-dedupe")
print("Summary:", diff["summary"])
for ent in diff["entities_added"]:
    print("Added entity:", ent["id"])

# 7. Verify integrity

assert manager.verify_checksum(post), "Checksum mismatch!"

# 8. Roll back if needed

manager.restore_snapshot(my_graph, "pre-dedupe", require_confirmation=False)

Key Source Files

Component	Purpose	Location
managers.py	TemporalVersionManager, diff computation, snapshot/restore operations	semantica/change_management/managers.py
change_log.py	ChangeLogEntry and MutationRecord definitions, validation logic	semantica/change_management/change_log.py
graph.py	Graph mutation tools that trigger version manager callbacks	semantica/mcp/tools/graph.py
change_management.md	User documentation for checksum usage and compliance workflows	docs/reference/change_management.md

Summary

• TemporalVersionManager provides the core change management workflow for tracking graph modifications in Semantica
• Immutable snapshots with SHA-256 checksums ensure tamper-evident audit trails
• Automatic mutation tracking via attach_to_graph() captures fine-grained change events
• Structured diffs between versions expose exactly what entities and relationships changed
• Protected rollback with confirmation guards prevents accidental data loss
• Regulatory compliance features support HIPAA, SOX, GDPR, and FDA 21 CFR Part 11 requirements

Frequently Asked Questions

How does Semantica prevent accidental data loss during rollbacks?

The restore_snapshot method includes a require_confirmation parameter that defaults to protective behavior. When enabled, operators must explicitly confirm restoration actions before the graph reverts to a previous state. This safety mechanism is implemented in managers.py lines 80-92.

What storage backends does TemporalVersionManager support?

The manager supports SQLite persistence for production workloads via the storage_path parameter, and falls back to an in-memory store when no path is specified (useful for testing). All snapshots persist as immutable records regardless of backend choice.

Can Semantica track changes to individual nodes over time?

Yes. The get_node_history method retrieves per-node mutation histories through MutationRecord objects stored in change_log.py. This granular tracking enables regulatory queries that demand complete provenance for specific entities.

How are snapshot checksums validated?

Each snapshot computes a SHA-256 checksum during creation via create_snapshot. The verify_checksum method recomputes the hash and compares it against the stored value, detecting any post-hoc modification to snapshot data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}