# How Semantica Tracks Graph Modifications with Its Change Management Workflow

> Discover Semantica's change management workflow for tracking graph modifications. Learn how its Git-like versioning system enables immutable snapshots, detailed diffs, and easy rollbacks.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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:

```python
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)](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:

```python
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)](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:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/managers.py)) computes a SHA-256 checksum and persists metadata through a `ChangeLogEntry` object defined in [`semantica/change_management/change_log.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/change_management/change_log.py).

*Source: [`create_snapshot`](https://github.com/semantica-agi/semantica/blob/main/semantica/change_management/managers.py#L20-L29)*

### Apply Graph Modifications

Execute changes using Semantica's graph tool API:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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)](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:

```python
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:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/change_management/managers.py#L68-L71)*

### Validate Snapshot Integrity

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

```python
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):

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/change_management/managers.py#L80-L92)*

## 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

```python

# 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`](https://github.com/semantica-agi/semantica/blob/main/managers.py) | `TemporalVersionManager`, diff computation, snapshot/restore operations | [`semantica/change_management/managers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/change_management/managers.py) |
| [`change_log.py`](https://github.com/semantica-agi/semantica/blob/main/change_log.py) | `ChangeLogEntry` and `MutationRecord` definitions, validation logic | [`semantica/change_management/change_log.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/change_management/change_log.py) |
| [`graph.py`](https://github.com/semantica-agi/semantica/blob/main/graph.py) | Graph mutation tools that trigger version manager callbacks | [`semantica/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/graph.py) |
| [`change_management.md`](https://github.com/semantica-agi/semantica/blob/main/change_management.md) | User documentation for checksum usage and compliance workflows | [`docs/reference/change_management.md`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.