Add development plan with 13 milestone specifications

- 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
2026-02-03 09:36:08 +01:00
parent 3d5a979a1b
commit d484f61b29
15 changed files with 3673 additions and 9 deletions
--- a/docs/milestones/01-temporal-versioning.md
+++ b/docs/milestones/01-temporal-versioning.md
@@ -0,0 +1,140 @@
+# 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)