omigamedev
d484f61b29
- docs/plan.md: Master roadmap with phases and priorities - docs/milestones/01-13: Detailed specs for each feature - Updated CLAUDE.md with plan references and build commands Milestones cover: - Phase 1: Temporal versioning, auto-capture, context injection, codebase indexing - Phase 2: Daily journal, content ingestion, graph visualization, import/export - Phase 3: Multi-graph, smart retrieval, TUI dashboard, browser extension, shell completions
141 lines
3.7 KiB
Markdown
141 lines
3.7 KiB
Markdown
# 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)
|