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

```sql
-- 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

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

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

```typescript
// 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

```typescript
// 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](https://arxiv.org/abs/2501.13956)
- [Datomic's immutable database model](https://www.datomic.com/)
- [Event sourcing patterns](https://martinfowler.com/eaaDev/EventSourcing.html)