# How ai-memory Handles Time-Travel and Revision History: A Deep Dive into Supersession Chains

> Explore how ai-memory's immutable supersession chains enable time-travel and revision history. Learn how new versions link to older revisions for seamless data management.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-09-01

---

**ai-memory implements time-travel and revision history through an immutable supersession chain where every wiki page write creates a new versioned row, with `superseded_at` linking older revisions and `NULL` marking the current version.**

The `ai-memory` crate achieves built-in versioning without external tools by treating the `pages` table as an append-only log. Each edit spawns a fresh row while preserving the full ancestry—enabling queries to retrieve any historical state of a wiki page.

## Core Design: The Supersession Chain

The foundation of ai-memory's time-travel capability rests on a **supersession chain** architecture in the `pages` table.

### How Supersession Works

When `Wiki::write_page` is invoked in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) at line 1269, the system performs these steps:

1. **SHA-256 short-circuit check** – Compare the new body against the current version. Identical content aborts the write.
2. **New row insertion** – Create a fresh `pages` row with the updated content, timestamp, and author.
3. **Chain linkage** – Set `superseded_at` on the previous row to the new row's creation time.
4. **Current version marker** – Leave `superseded_at = NULL` on the newest row.

This design yields an **immutable linked list** of revisions. Even no-op writes produce supersession entries at line 1652, preserving complete auditability. Author attribution travels with each version via `pages.author_id` at line 2206.

## Write Path: Atomic Chain Updates

The writer actor in [`crates/ai-memory-store/src/writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/writer.rs) at line 1512 guarantees **transactional consistency** across the entire supersession chain. All link updates occur in a single database transaction—partial writes cannot corrupt the revision history.

Key properties of the write implementation:

- **Graceful deduplication** – SHA-256 comparison prevents redundant versions for unchanged content.
- **Forced versioning** – Explicit no-op writes still create chain entries when audit trails matter.
- **Author tracking** – Every revision captures `author_id` for blame and attribution queries.

## Read Path: Time-Travel Queries

The reader implementation in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) at line 7894 supports **three access patterns**:

| Access Mode | Method | How It Works |
|-------------|--------|--------------|
| **Latest** | `read_page(path)` | Select where `superseded_at IS NULL` |
| **By ID** | `read_page_by_id(path, id)` | Direct primary key lookup |
| **By timestamp** | Follow supersession links | Traverse chain to find version active at given time |

The reader follows supersession pointers backward through the chain when historical resolution is required. This enables **point-in-time reconstruction** of any wiki page state.

## Operations Layer: CRUD Semantics and Statistics

The store surface in [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) documents supersession behavior explicitly:

- Line 1803: A later version **starts a new supersession**—no in-place updates exist.
- Line 1979: **Every supersession row counts** in page-level statistics; revision count equals chain length.
- Line 3094: Page deletion cascades through the **entire supersession ancestry** after a configurable grace period, enabling soft-delete with eventual hard removal.

## Core Abstraction: The Versioned Page Type

The `Page` struct in [`crates/ai-memory-core/src/page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/page.rs) at line 5 encapsulates the versioning model. Its documentation established `ai-memory`'s core invariant: **pages are versioned entities**, not mutable records.

## Practical Examples: Time-Travel in Action

```rust
use ai_memory_wiki::Wiki;

// Write creates a new supersession entry automatically
let page_path = "projects/example.md";
let new_body = format!("Updated content at {}", chrono::Utc::now());
wiki.write_page(page_path, &new_body).await?;

// Retrieve current version (superseded_at = NULL)
let latest = wiki.read_page(page_path).await?;
println!("Current: {}", latest.body);

// Time-travel: fetch specific revision by ID
let revision_id = 42u64;
let historic = wiki.read_page_by_id(page_path, revision_id).await?;
println!("Revision {}: {}", historic.id, historic.body);

// Reconstruct full timeline
let chain = wiki.page_history(page_path).await?;
for rev in chain {
    let status = if rev.superseded_at.is_none() { "CURRENT" } else { "archived" };
    println!("[{}] rev {} @ {} — {}", status, rev.id, rev.created_at, rev.body);
}

```

The API surface hides chain complexity—callers simply write and read, with time-travel available through optional parameters.

## Performance and Storage Considerations

The supersession chain design trades **storage for simplicity and correctness**:

- **O(1) latest version lookup** via `superseded_at IS NULL` index.
- **O(n) history traversal** where *n* = revision depth (typically small for wiki pages).
- **Storage growth** is linear with edits; no compression or delta encoding is currently implemented.

## Summary

- **Every write creates a version**: The `pages` table uses append-only supersession chains in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs).
- **Immutable history**: Old rows persist with `superseded_at` timestamps; no update-in-place occurs.
- **Transactional safety**: [`crates/ai-memory-store/src/writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/writer.rs) ensures atomic chain updates.
- **Flexible reads**: [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) supports latest, by-ID, and timestamp-based queries.
- **Explicit semantics**: [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) defines versioning rules and deletion behavior.

## Frequently Asked Questions

### How does ai-memory prevent revision history corruption?

The writer actor performs all supersession updates inside a single database transaction at line 1512 of [`crates/ai-memory-store/src/writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/writer.rs). Either the entire chain update succeeds, or the transaction rolls back—no partial states are possible.

### Can ai-memory retrieve a page as it appeared on a specific date?

Yes, though the API emphasizes ID-based and latest-version access. The reader follows supersession links at line 7894 of [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs), which enables timestamp-based resolution by walking the chain to find the version active at a given point.

### What happens when a page is deleted in ai-memory?

Deletion marks the page for removal but preserves the supersession chain until a configurable grace period expires. Afterward, line 3094 of [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) hard-deletes the entire ancestry—enabling recovery windows before permanent erasure.

### Does ai-memory support branching or merging of page versions?

No. The supersession chain is strictly linear as implemented in [`crates/ai-memory-core/src/page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/page.rs). Each version has exactly one predecessor and (at most) one successor—there is no support for divergent branches or three-way merge operations.