cortex/docs/milestones/01-temporal-versioning.md

Milestone 1: Temporal Versioning

Overview

Track how knowledge evolves over time. Every node change creates a version, enabling "time travel" queries like "what did I know about authentication last month?"

Motivation

• Facts change — what was true yesterday may not be true today
• Debugging requires knowing historical context
• AI agents need to reason about temporal relationships
• Prevents accidental knowledge loss from overwrites

Features

1.1 Node Versioning

Every update to a node creates a new version instead of overwriting.

-- New table
CREATE TABLE node_versions (
  id TEXT PRIMARY KEY,
  node_id TEXT NOT NULL,
  version INTEGER NOT NULL,
  title TEXT NOT NULL,
  content TEXT,
  status TEXT,
  tags TEXT,
  metadata TEXT,
  valid_from INTEGER NOT NULL,
  valid_until INTEGER,  -- NULL = current version
  created_by TEXT,      -- 'user', 'auto-capture', 'merge', etc.
  FOREIGN KEY (node_id) REFERENCES nodes(id)
);

CREATE INDEX idx_versions_node ON node_versions(node_id, version);
CREATE INDEX idx_versions_time ON node_versions(valid_from, valid_until);

1.2 Time-Travel Queries

# Show node as it was on a specific date
cortex show abc123 --at "2024-01-15"

# Query the graph at a point in time
cortex query "authentication" --at "2024-01-15"

# Show version history
cortex history abc123

1.3 Diff & Compare

# Compare two versions
cortex diff abc123 --v1 3 --v2 5

# Compare node across time
cortex diff abc123 --from "2024-01-01" --to "2024-02-01"

1.4 MCP Tools

// New MCP tools
memory_history    // Get version history for a node
memory_show_at    // Show node at specific timestamp
memory_diff       // Compare versions

Implementation

Database Changes

1. Add node_versions table
2. Add version column to nodes table (current version number)
3. Modify updateNode() to create version records
4. Add valid_from/valid_until to enable point-in-time queries

API Changes

// store.ts additions
export function getNodeHistory(id: string): NodeVersion[];
export function getNodeAtTime(id: string, timestamp: number): Node | null;
export function diffVersions(id: string, v1: number, v2: number): NodeDiff;

Migration Strategy

1. Create new tables
2. Migrate existing nodes as version 1
3. Set valid_from to created_at for existing nodes

CLI Commands

Command	Description
cortex history <id>	Show version history
cortex show <id> --at <date>	Show node at point in time
cortex diff <id> [--v1 N] [--v2 M]	Compare versions
cortex restore <id> --version <N>	Restore old version

Testing

• Create node, update 3 times, verify 3 versions exist
• Query at historical timestamp returns correct version
• Diff shows actual changes between versions
• Restore creates new version (not destructive)
• Migration preserves existing data

Acceptance Criteria

• All node updates create version records
• --at flag works on show/query commands
• History command shows all versions with timestamps
• Diff output is human-readable
• MCP tools expose versioning functionality
• No performance regression on normal operations (<10% slower)

Estimated Effort

• Database schema: 2 hours
• Store layer changes: 4 hours
• CLI commands: 3 hours
• MCP tools: 2 hours
• Testing: 2 hours
• Total: ~13 hours

Dependencies

• None (can start immediately)

References

• Zep Temporal Knowledge Graph
• Datomic's immutable database model
• Event sourcing patterns