omar/cortex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add temporal versioning for node history tracking (Milestone 1)

Browse Source 
Enable time-travel queries and history viewing by creating immutable
version records on every node update. Includes database schema changes,
store functions, MCP tools, and CLI commands for viewing history,
comparing versions, and restoring to previous states.
This commit is contained in:
omigamedev
2026-02-03 09:58:16 +01:00
parent 999c748d3d
commit 761c7a247c
9 changed files with 663 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
src/core/db.ts
View File

@@ -32,6 +32,21 @@ CREATE TABLE IF NOT EXISTS node_tags (
PRIMARY KEY (node_id, tag)
);
CREATE TABLE IF NOT EXISTS node_versions (
id TEXT PRIMARY KEY,
node_id TEXT NOT NULL,
version INTEGER NOT NULL,
title TEXT NOT NULL,
content TEXT NOT NULL DEFAULT '',
status TEXT,
tags TEXT DEFAULT '[]',
metadata TEXT DEFAULT '{}',
valid_from INTEGER NOT NULL,
valid_until INTEGER,
created_by TEXT DEFAULT 'user',
FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status);
CREATE INDEX IF NOT EXISTS idx_nodes_created ON nodes(created_at DESC);
@@ -40,6 +55,9 @@ CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_id);
CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_id);
CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);
CREATE INDEX IF NOT EXISTS idx_tags_tag ON node_tags(tag);
CREATE INDEX IF NOT EXISTS idx_versions_node ON node_versions(node_id, version);
CREATE INDEX IF NOT EXISTS idx_versions_time ON node_versions(valid_from, valid_until);
CREATE UNIQUE INDEX IF NOT EXISTS idx_versions_node_version ON node_versions(node_id, version);
`;
let _db: Database.Database | null = null;
@@ -68,6 +86,41 @@ export function getDb(): Database.Database {
_db.exec('UPDATE nodes SET last_accessed_at = updated_at WHERE last_accessed_at IS NULL');
}
// Migration: add version column to nodes table
if (!cols.some((c: any) => c.name === 'version')) {
_db.exec('ALTER TABLE nodes ADD COLUMN version INTEGER DEFAULT 1');
_db.exec('UPDATE nodes SET version = 1 WHERE version IS NULL');
}
// Migration: backfill node_versions for existing nodes without versions
const existingWithoutVersion = _db.prepare(`
SELECT * FROM nodes WHERE id NOT IN (SELECT DISTINCT node_id FROM node_versions)
`).all() as any[];
if (existingWithoutVersion.length > 0) {
const insertVersion = _db.prepare(`
INSERT INTO node_versions (id, node_id, version, title, content, status, tags, metadata, valid_from, valid_until, created_by)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`);
for (const node of existingWithoutVersion) {
const versionId = require('crypto').randomUUID();
insertVersion.run(
versionId,
node.id,
1,
node.title,
node.content,
node.status,
node.tags,
node.metadata,
node.created_at,
null,
'migration'
);
}
}
return _db;
}

266
src/core/store.ts
View File

@@ -1,6 +1,6 @@
import { randomUUID as uuid } from 'crypto';
import { getDb } from './db';
import { Node, Edge, AddNodeInput, UpdateNodeInput, ListOptions, QueryOptions, SearchResult, EdgeType } from '../types';
import { Node, Edge, AddNodeInput, UpdateNodeInput, ListOptions, QueryOptions, SearchResult, EdgeType, NodeVersion, HistoricalNode, NodeDiff } from '../types';
import { hybridSearch, deserializeEmbedding } from './search/index';
import { getEmbedding } from './search/ollama';
@@ -43,21 +43,44 @@ export async function addNode(input: AddNodeInput): Promise<Node> {
// Try to get embedding
const embedding = await getEmbedding(`${input.title} ${content}`);
db.prepare(`
INSERT INTO nodes (id, kind, title, content, status, tags, metadata, embedding, created_at, updated_at, last_accessed_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`).run(
id, input.kind, input.title, content, input.status ?? null,
JSON.stringify(tags), JSON.stringify(metadata),
embedding ? serializeEmbedding(embedding) : null,
now, now, now
);
const transaction = db.transaction(() => {
db.prepare(`
INSERT INTO nodes (id, kind, title, content, status, tags, metadata, embedding, created_at, updated_at, last_accessed_at, version)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`).run(
id, input.kind, input.title, content, input.status ?? null,
JSON.stringify(tags), JSON.stringify(metadata),
embedding ? serializeEmbedding(embedding) : null,
now, now, now, 1
);
// Insert tags
const insertTag = db.prepare('INSERT OR IGNORE INTO node_tags (node_id, tag) VALUES (?, ?)');
for (const tag of tags) {
insertTag.run(id, tag);
}
// Insert tags
const insertTag = db.prepare('INSERT OR IGNORE INTO node_tags (node_id, tag) VALUES (?, ?)');
for (const tag of tags) {
insertTag.run(id, tag);
}
// Create initial version record
const versionId = uuid();
db.prepare(`
INSERT INTO node_versions (id, node_id, version, title, content, status, tags, metadata, valid_from, valid_until, created_by)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`).run(
versionId,
id,
1,
input.title,
content,
input.status ?? null,
JSON.stringify(tags),
JSON.stringify(metadata),
now,
null,
'user'
);
});
transaction();
notifyDirty();
return {
@@ -114,46 +137,88 @@ export function listNodes(options: ListOptions = {}): Node[] {
return nodes;
}
export async function updateNode(id: string, input: UpdateNodeInput): Promise<Node | null> {
export async function updateNode(id: string, input: UpdateNodeInput, createdBy: string = 'user'): Promise<Node | null> {
const db = getDb();
const existing = getNode(id);
if (!existing) return null;
// Get existing node without updating last_accessed_at
const existingRow = db.prepare('SELECT * FROM nodes WHERE id = ?').get(id) as any;
if (!existingRow) return null;
const existing = rowToNode(existingRow);
const now = Date.now();
const sets: string[] = ['updated_at = ?'];
const params: any[] = [now];
if (input.title !== undefined) { sets.push('title = ?'); params.push(input.title); }
if (input.content !== undefined) { sets.push('content = ?'); params.push(input.content); }
if (input.status !== undefined) { sets.push('status = ?'); params.push(input.status); }
if (input.isStale !== undefined) { sets.push('is_stale = ?'); params.push(input.isStale ? 1 : 0); }
if (input.tags !== undefined) { sets.push('tags = ?'); params.push(JSON.stringify(input.tags)); }
if (input.metadata !== undefined) {
const merged = { ...existing.metadata, ...input.metadata };
sets.push('metadata = ?');
params.push(JSON.stringify(merged));
}
// Get current version number
const currentVersion = existingRow.version ?? 1;
const newVersion = currentVersion + 1;
// Re-embed if title or content changed
// Create version snapshot in a transaction
const transaction = db.transaction(() => {
// Close out the current version by setting valid_until
db.prepare(`
UPDATE node_versions SET valid_until = ? WHERE node_id = ? AND valid_until IS NULL
`).run(now, id);
// Insert new version record with the NEW state (after update)
const versionId = uuid();
const newTitle = input.title ?? existing.title;
const newContent = input.content ?? existing.content;
const newStatus = input.status !== undefined ? input.status : existing.status;
const newTags = input.tags ?? existing.tags;
const newMetadata = input.metadata !== undefined ? { ...existing.metadata, ...input.metadata } : existing.metadata;
db.prepare(`
INSERT INTO node_versions (id, node_id, version, title, content, status, tags, metadata, valid_from, valid_until, created_by)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`).run(
versionId,
id,
newVersion,
newTitle,
newContent,
newStatus ?? null,
JSON.stringify(newTags),
JSON.stringify(newMetadata),
now,
null,
createdBy
);
// Build the update query
const sets: string[] = ['updated_at = ?', 'version = ?'];
const params: any[] = [now, newVersion];
if (input.title !== undefined) { sets.push('title = ?'); params.push(input.title); }
if (input.content !== undefined) { sets.push('content = ?'); params.push(input.content); }
if (input.status !== undefined) { sets.push('status = ?'); params.push(input.status); }
if (input.isStale !== undefined) { sets.push('is_stale = ?'); params.push(input.isStale ? 1 : 0); }
if (input.tags !== undefined) { sets.push('tags = ?'); params.push(JSON.stringify(input.tags)); }
if (input.metadata !== undefined) {
const merged = { ...existing.metadata, ...input.metadata };
sets.push('metadata = ?');
params.push(JSON.stringify(merged));
}
params.push(id);
db.prepare(`UPDATE nodes SET ${sets.join(', ')} WHERE id = ?`).run(...params);
// Update tags if changed
if (input.tags !== undefined) {
db.prepare('DELETE FROM node_tags WHERE node_id = ?').run(id);
const insertTag = db.prepare('INSERT OR IGNORE INTO node_tags (node_id, tag) VALUES (?, ?)');
for (const tag of input.tags) {
insertTag.run(id, tag);
}
}
});
transaction();
// Re-embed if title or content changed (outside transaction since it's async)
if (input.title !== undefined || input.content !== undefined) {
const newTitle = input.title ?? existing.title;
const newContent = input.content ?? existing.content;
const embedding = await getEmbedding(`${newTitle} ${newContent}`);
if (embedding) {
sets.push('embedding = ?');
params.push(serializeEmbedding(embedding));
}
}
params.push(id);
db.prepare(`UPDATE nodes SET ${sets.join(', ')} WHERE id = ?`).run(...params);
// Update tags if changed
if (input.tags !== undefined) {
db.prepare('DELETE FROM node_tags WHERE node_id = ?').run(id);
const insertTag = db.prepare('INSERT OR IGNORE INTO node_tags (node_id, tag) VALUES (?, ?)');
for (const tag of input.tags) {
insertTag.run(id, tag);
db.prepare('UPDATE nodes SET embedding = ? WHERE id = ?').run(serializeEmbedding(embedding), id);
}
}
@@ -195,3 +260,114 @@ export async function query(text: string, options: QueryOptions = {}): Promise<S
const nodes = listNodes({ kind: options.kind, tags: options.tags, includeStale: options.includeStale });
return hybridSearch(nodes, text, options);
}
// Version tracking functions
function rowToNodeVersion(row: any): NodeVersion {
return {
id: row.id,
nodeId: row.node_id,
version: row.version,
title: row.title,
content: row.content,
status: row.status ?? undefined,
tags: JSON.parse(row.tags || '[]'),
metadata: JSON.parse(row.metadata || '{}'),
validFrom: row.valid_from,
validUntil: row.valid_until ?? null,
createdBy: row.created_by,
};
}
function rowToHistoricalNode(row: any, nodeRow: any): HistoricalNode {
return {
id: nodeRow.id,
kind: nodeRow.kind,
title: row.title,
content: row.content,
status: row.status ?? undefined,
tags: JSON.parse(row.tags || '[]'),
metadata: JSON.parse(row.metadata || '{}'),
version: row.version,
validFrom: row.valid_from,
validUntil: row.valid_until ?? null,
};
}
export function getNodeHistory(id: string): NodeVersion[] {
const db = getDb();
const rows = db.prepare(`
SELECT * FROM node_versions WHERE node_id = ? ORDER BY version DESC
`).all(id) as any[];
return rows.map(rowToNodeVersion);
}
export function getNodeAtTime(id: string, timestamp: number): HistoricalNode | null {
const db = getDb();
const nodeRow = db.prepare('SELECT * FROM nodes WHERE id = ?').get(id) as any;
if (!nodeRow) return null;
const versionRow = db.prepare(`
SELECT * FROM node_versions
WHERE node_id = ? AND valid_from <= ? AND (valid_until IS NULL OR valid_until > ?)
ORDER BY version DESC LIMIT 1
`).get(id, timestamp, timestamp) as any;
if (!versionRow) return null;
return rowToHistoricalNode(versionRow, nodeRow);
}
export function getNodeVersion(id: string, version: number): HistoricalNode | null {
const db = getDb();
const nodeRow = db.prepare('SELECT * FROM nodes WHERE id = ?').get(id) as any;
if (!nodeRow) return null;
const versionRow = db.prepare(`
SELECT * FROM node_versions WHERE node_id = ? AND version = ?
`).get(id, version) as any;
if (!versionRow) return null;
return rowToHistoricalNode(versionRow, nodeRow);
}
export function diffVersions(id: string, v1: number, v2: number): NodeDiff | null {
const version1 = getNodeVersion(id, v1);
const version2 = getNodeVersion(id, v2);
if (!version1 || !version2) return null;
const changes: NodeDiff['changes'] = [];
const fieldsToCompare: (keyof HistoricalNode)[] = ['title', 'content', 'status', 'tags', 'metadata'];
for (const field of fieldsToCompare) {
const oldVal = version1[field];
const newVal = version2[field];
const oldStr = JSON.stringify(oldVal);
const newStr = JSON.stringify(newVal);
if (oldStr !== newStr) {
changes.push({ field, old: oldVal, new: newVal });
}
}
return { nodeId: id, v1, v2, changes };
}
export async function restoreVersion(id: string, version: number, createdBy: string = 'restore'): Promise<Node | null> {
const historical = getNodeVersion(id, version);
if (!historical) return null;
// updateNode will handle creating a new version
return updateNode(id, {
title: historical.title,
content: historical.content,
status: historical.status,
tags: historical.tags,
metadata: historical.metadata,
}, createdBy);
}
export function getCurrentVersion(id: string): number {
const db = getDb();
const row = db.prepare('SELECT version FROM nodes WHERE id = ?').get(id) as any;
return row?.version ?? 1;
}