claude-cortex 1.0.0 → 1.1.0

package/dashboard/src/lib/position-algorithm.ts

@@ -0,0 +1,177 @@
+/**
+ * Position Algorithm
+ * Calculates 3D positions for memories in a brain-like visualization
+ *
+ * Brain anatomy mapping:
+ * - Frontal lobe (front, +Z): Short-term memories, decisions, planning
+ * - Temporal lobes (sides, ±X): Episodic memories, language, emotion
+ * - Parietal lobe (top, +Y): Spatial awareness, context
+ * - Occipital lobe (back, -Z): Long-term storage, patterns
+ * - Hippocampus (center): Learning, memory formation
+ */
+
+import { Memory, Memory3DPosition, MemoryCategory } from '@/types/memory';
+
+// Brain region definitions - where each category lives
+const BRAIN_REGIONS: Record<MemoryCategory, {
+  basePosition: { x: number; y: number; z: number };
+  spread: number;
+}> = {
+  // Prefrontal cortex - planning and architecture decisions
+  architecture: {
+    basePosition: { x: 0, y: 1.2, z: 2.2 },
+    spread: 1.0,
+  },
+  // Visual/pattern recognition area - occipital lobe
+  pattern: {
+    basePosition: { x: 0, y: 0.3, z: -2.2 },
+    spread: 0.9,
+  },
+  // Limbic system - preferences and emotions
+  preference: {
+    basePosition: { x: 1.6, y: -0.3, z: 0 },
+    spread: 0.7,
+  },
+  // Amygdala area - error/threat detection
+  error: {
+    basePosition: { x: -1.6, y: -0.3, z: 0.3 },
+    spread: 0.8,
+  },
+  // Parietal lobe - context and spatial awareness
+  context: {
+    basePosition: { x: 0, y: 1.8, z: 0 },
+    spread: 1.2,
+  },
+  // Hippocampus - learning and memory formation (central)
+  learning: {
+    basePosition: { x: 0, y: -0.3, z: 0 },
+    spread: 0.8,
+  },
+  // Frontal lobe - task planning
+  todo: {
+    basePosition: { x: 0.6, y: 0.8, z: 1.8 },
+    spread: 0.7,
+  },
+  // Temporal lobe - general notes and language
+  note: {
+    basePosition: { x: 1.8, y: 0, z: -0.3 },
+    spread: 1.0,
+  },
+  // Social brain network - relationships
+  relationship: {
+    basePosition: { x: -1.8, y: 0.3, z: -0.3 },
+    spread: 0.9,
+  },
+  // Distributed - custom memories
+  custom: {
+    basePosition: { x: 0, y: 0, z: 0 },
+    spread: 1.5,
+  },
+};
+
+// Memory type influences depth (surface vs inner brain)
+const TYPE_DEPTH: Record<string, number> = {
+  short_term: 0.6,   // Closer to surface (outer brain)
+  episodic: 0,       // Middle layer
+  long_term: -0.4,   // Deeper (inner brain, more permanent)
+};
+
+/**
+ * Seeded random for consistent positions based on memory ID
+ */
+function seededRandom(seed: number): number {
+  const x = Math.sin(seed * 12.9898) * 43758.5453;
+  return x - Math.floor(x);
+}
+
+/**
+ * Calculate 3D position for a memory within brain anatomy
+ */
+export function calculateMemoryPosition(memory: Memory): Memory3DPosition {
+  const region = BRAIN_REGIONS[memory.category] || BRAIN_REGIONS.custom;
+  const typeDepth = TYPE_DEPTH[memory.type] || 0;
+
+  // Use memory ID for consistent random offset
+  const rand1 = seededRandom(memory.id);
+  const rand2 = seededRandom(memory.id + 1000);
+  const rand3 = seededRandom(memory.id + 2000);
+
+  // Calculate position within brain region using spherical distribution
+  const spread = region.spread;
+  const theta = rand1 * Math.PI * 2; // Angle around Y axis
+  const phi = (rand2 - 0.5) * Math.PI; // Angle from horizontal
+  const r = rand3 * spread * 0.7 + spread * 0.3; // Distance from region center
+
+  // Convert to cartesian
+  const offsetX = r * Math.cos(phi) * Math.cos(theta);
+  const offsetY = r * Math.sin(phi) * 0.6; // Flatten vertically
+  const offsetZ = r * Math.cos(phi) * Math.sin(theta);
+
+  // Base position from region + offset + type depth
+  let x = region.basePosition.x + offsetX;
+  let y = region.basePosition.y + offsetY;
+  let z = region.basePosition.z + offsetZ + typeDepth;
+
+  // Salience affects prominence (higher = closer to surface, more visible)
+  const salienceBoost = memory.salience * 0.4;
+  const distanceFromCenter = Math.sqrt(x * x + y * y + z * z);
+  if (distanceFromCenter > 0.1) {
+    const targetDistance = distanceFromCenter + salienceBoost;
+    const scale = targetDistance / distanceFromCenter;
+    x *= scale;
+    y *= scale;
+    z *= scale;
+  }
+
+  // Constrain to brain-like ellipsoid shape
+  const brainWidth = 3.2;  // X axis
+  const brainHeight = 2.5; // Y axis
+  const brainDepth = 3.5;  // Z axis (front to back)
+
+  // Keep within brain bounds
+  const normalizedDist = Math.sqrt(
+    (x / brainWidth) ** 2 +
+    (y / brainHeight) ** 2 +
+    (z / brainDepth) ** 2
+  );
+
+  if (normalizedDist > 0.95) {
+    const scale = 0.95 / normalizedDist;
+    x *= scale;
+    y *= scale;
+    z *= scale;
+  }
+
+  return { x, y, z };
+}
+
+/**
+ * Calculate decay factor for visual effects
+ */
+export function calculateDecayFactor(memory: Memory): number {
+  if (!memory.lastAccessed) return 1;
+
+  const now = Date.now();
+  const lastAccessed = new Date(memory.lastAccessed).getTime();
+  const hoursSinceAccess = (now - lastAccessed) / (1000 * 60 * 60);
+
+  const decayRates: Record<string, number> = {
+    short_term: 0.995,
+    long_term: 0.9995,
+    episodic: 0.998,
+  };
+
+  const rate = decayRates[memory.type] || 0.995;
+  return Math.pow(rate, hoursSinceAccess);
+}
+
+/**
+ * Get region bounds for each memory type
+ */
+export function getRegionBounds() {
+  return {
+    short_term: { minZ: 1.0, maxZ: 3.0, color: '#F97316' },
+    episodic: { minZ: -1.0, maxZ: 1.0, color: '#8B5CF6' },
+    long_term: { minZ: -3.0, maxZ: -1.0, color: '#3B82F6' },
+  };
+}

package/dashboard/src/lib/simplex-noise.ts

@@ -0,0 +1,217 @@
+/**
+ * Simplex Noise Implementation
+ * Used for procedural brain mesh generation with organic cortex folds
+ *
+ * Based on Stefan Gustavson's simplex noise algorithm
+ */
+
+// Gradient vectors for 3D
+const grad3 = [
+  [1, 1, 0], [-1, 1, 0], [1, -1, 0], [-1, -1, 0],
+  [1, 0, 1], [-1, 0, 1], [1, 0, -1], [-1, 0, -1],
+  [0, 1, 1], [0, -1, 1], [0, 1, -1], [0, -1, -1],
+];
+
+// Permutation table
+const perm = new Uint8Array(512);
+const permMod12 = new Uint8Array(512);
+
+// Initialize with seed
+function initPermutation(seed: number = 0): void {
+  const p = new Uint8Array(256);
+  for (let i = 0; i < 256; i++) {
+    p[i] = i;
+  }
+
+  // Shuffle using seed
+  let n = seed;
+  for (let i = 255; i > 0; i--) {
+    n = (n * 1103515245 + 12345) & 0x7fffffff;
+    const j = n % (i + 1);
+    [p[i], p[j]] = [p[j], p[i]];
+  }
+
+  for (let i = 0; i < 512; i++) {
+    perm[i] = p[i & 255];
+    permMod12[i] = perm[i] % 12;
+  }
+}
+
+// Initialize with default seed
+initPermutation(42);
+
+// Skewing factors for 3D
+const F3 = 1 / 3;
+const G3 = 1 / 6;
+
+function dot3(g: number[], x: number, y: number, z: number): number {
+  return g[0] * x + g[1] * y + g[2] * z;
+}
+
+/**
+ * 3D Simplex Noise
+ * Returns value in range [-1, 1]
+ */
+export function simplex3D(x: number, y: number, z: number): number {
+  // Skew the input space
+  const s = (x + y + z) * F3;
+  const i = Math.floor(x + s);
+  const j = Math.floor(y + s);
+  const k = Math.floor(z + s);
+
+  const t = (i + j + k) * G3;
+  const X0 = i - t;
+  const Y0 = j - t;
+  const Z0 = k - t;
+
+  const x0 = x - X0;
+  const y0 = y - Y0;
+  const z0 = z - Z0;
+
+  // Determine simplex
+  let i1: number, j1: number, k1: number;
+  let i2: number, j2: number, k2: number;
+
+  if (x0 >= y0) {
+    if (y0 >= z0) {
+      i1 = 1; j1 = 0; k1 = 0; i2 = 1; j2 = 1; k2 = 0;
+    } else if (x0 >= z0) {
+      i1 = 1; j1 = 0; k1 = 0; i2 = 1; j2 = 0; k2 = 1;
+    } else {
+      i1 = 0; j1 = 0; k1 = 1; i2 = 1; j2 = 0; k2 = 1;
+    }
+  } else {
+    if (y0 < z0) {
+      i1 = 0; j1 = 0; k1 = 1; i2 = 0; j2 = 1; k2 = 1;
+    } else if (x0 < z0) {
+      i1 = 0; j1 = 1; k1 = 0; i2 = 0; j2 = 1; k2 = 1;
+    } else {
+      i1 = 0; j1 = 1; k1 = 0; i2 = 1; j2 = 1; k2 = 0;
+    }
+  }
+
+  const x1 = x0 - i1 + G3;
+  const y1 = y0 - j1 + G3;
+  const z1 = z0 - k1 + G3;
+  const x2 = x0 - i2 + 2 * G3;
+  const y2 = y0 - j2 + 2 * G3;
+  const z2 = z0 - k2 + 2 * G3;
+  const x3 = x0 - 1 + 3 * G3;
+  const y3 = y0 - 1 + 3 * G3;
+  const z3 = z0 - 1 + 3 * G3;
+
+  const ii = i & 255;
+  const jj = j & 255;
+  const kk = k & 255;
+
+  let n0 = 0, n1 = 0, n2 = 0, n3 = 0;
+
+  let t0 = 0.6 - x0 * x0 - y0 * y0 - z0 * z0;
+  if (t0 >= 0) {
+    const gi0 = permMod12[ii + perm[jj + perm[kk]]];
+    t0 *= t0;
+    n0 = t0 * t0 * dot3(grad3[gi0], x0, y0, z0);
+  }
+
+  let t1 = 0.6 - x1 * x1 - y1 * y1 - z1 * z1;
+  if (t1 >= 0) {
+    const gi1 = permMod12[ii + i1 + perm[jj + j1 + perm[kk + k1]]];
+    t1 *= t1;
+    n1 = t1 * t1 * dot3(grad3[gi1], x1, y1, z1);
+  }
+
+  let t2 = 0.6 - x2 * x2 - y2 * y2 - z2 * z2;
+  if (t2 >= 0) {
+    const gi2 = permMod12[ii + i2 + perm[jj + j2 + perm[kk + k2]]];
+    t2 *= t2;
+    n2 = t2 * t2 * dot3(grad3[gi2], x2, y2, z2);
+  }
+
+  let t3 = 0.6 - x3 * x3 - y3 * y3 - z3 * z3;
+  if (t3 >= 0) {
+    const gi3 = permMod12[ii + 1 + perm[jj + 1 + perm[kk + 1]]];
+    t3 *= t3;
+    n3 = t3 * t3 * dot3(grad3[gi3], x3, y3, z3);
+  }
+
+  return 32 * (n0 + n1 + n2 + n3);
+}
+
+/**
+ * Fractal Brownian Motion (fBm)
+ * Adds multiple octaves of noise for more detail
+ */
+export function fbm3D(
+  x: number,
+  y: number,
+  z: number,
+  octaves: number = 4,
+  lacunarity: number = 2,
+  gain: number = 0.5
+): number {
+  let value = 0;
+  let amplitude = 1;
+  let frequency = 1;
+  let maxValue = 0;
+
+  for (let i = 0; i < octaves; i++) {
+    value += amplitude * simplex3D(x * frequency, y * frequency, z * frequency);
+    maxValue += amplitude;
+    amplitude *= gain;
+    frequency *= lacunarity;
+  }
+
+  return value / maxValue;
+}
+
+/**
+ * Ridged noise - creates sharp ridges
+ * Useful for sulci (brain folds)
+ */
+export function ridged3D(
+  x: number,
+  y: number,
+  z: number,
+  octaves: number = 4,
+  lacunarity: number = 2,
+  gain: number = 0.5
+): number {
+  let value = 0;
+  let amplitude = 1;
+  let frequency = 1;
+  let weight = 1;
+
+  for (let i = 0; i < octaves; i++) {
+    let signal = simplex3D(x * frequency, y * frequency, z * frequency);
+    signal = 1 - Math.abs(signal);
+    signal *= signal * weight;
+    weight = Math.min(1, Math.max(0, signal * 2));
+    value += signal * amplitude;
+    amplitude *= gain;
+    frequency *= lacunarity;
+  }
+
+  return value;
+}
+
+/**
+ * Turbulence - absolute value of noise
+ */
+export function turbulence3D(
+  x: number,
+  y: number,
+  z: number,
+  octaves: number = 4
+): number {
+  let value = 0;
+  let amplitude = 1;
+  let frequency = 1;
+
+  for (let i = 0; i < octaves; i++) {
+    value += amplitude * Math.abs(simplex3D(x * frequency, y * frequency, z * frequency));
+    amplitude *= 0.5;
+    frequency *= 2;
+  }
+
+  return value;
+}

package/dashboard/src/lib/store.ts

@@ -0,0 +1,88 @@
+'use client';
+
+/**
+ * UI State Store
+ * Zustand store for dashboard UI state
+ */
+
+import { create } from 'zustand';
+import { Memory, MemoryEvent } from '@/types/memory';
+
+interface DashboardState {
+  // Selected memory
+  selectedMemory: Memory | null;
+  setSelectedMemory: (memory: Memory | null) => void;
+
+  // View mode
+  viewMode: '3d' | 'list' | 'graph';
+  setViewMode: (mode: '3d' | 'list' | 'graph') => void;
+
+  // Filters
+  typeFilter: string | null;
+  categoryFilter: string | null;
+  projectFilter: string | null;
+  setTypeFilter: (type: string | null) => void;
+  setCategoryFilter: (category: string | null) => void;
+  setProjectFilter: (project: string | null) => void;
+
+  // Recent events (for activity feed)
+  recentEvents: MemoryEvent[];
+  addEvent: (event: MemoryEvent) => void;
+  clearEvents: () => void;
+
+  // 3D camera state
+  cameraPosition: [number, number, number];
+  setCameraPosition: (pos: [number, number, number]) => void;
+
+  // Sidebar visibility
+  showLeftSidebar: boolean;
+  showRightSidebar: boolean;
+  toggleLeftSidebar: () => void;
+  toggleRightSidebar: () => void;
+
+  // Search query
+  searchQuery: string;
+  setSearchQuery: (query: string) => void;
+}
+
+export const useDashboardStore = create<DashboardState>((set) => ({
+  // Selected memory
+  selectedMemory: null,
+  setSelectedMemory: (memory) => set({ selectedMemory: memory }),
+
+  // View mode
+  viewMode: '3d',
+  setViewMode: (mode) => set({ viewMode: mode }),
+
+  // Filters
+  typeFilter: null,
+  categoryFilter: null,
+  projectFilter: null,
+  setTypeFilter: (type) => set({ typeFilter: type }),
+  setCategoryFilter: (category) => set({ categoryFilter: category }),
+  setProjectFilter: (project) => set({ projectFilter: project }),
+
+  // Recent events
+  recentEvents: [],
+  addEvent: (event) =>
+    set((state) => ({
+      recentEvents: [event, ...state.recentEvents].slice(0, 50),
+    })),
+  clearEvents: () => set({ recentEvents: [] }),
+
+  // 3D camera
+  cameraPosition: [0, 0, 12],
+  setCameraPosition: (pos) => set({ cameraPosition: pos }),
+
+  // Sidebars
+  showLeftSidebar: true,
+  showRightSidebar: true,
+  toggleLeftSidebar: () =>
+    set((state) => ({ showLeftSidebar: !state.showLeftSidebar })),
+  toggleRightSidebar: () =>
+    set((state) => ({ showRightSidebar: !state.showRightSidebar })),
+
+  // Search
+  searchQuery: '',
+  setSearchQuery: (query) => set({ searchQuery: query }),
+}));

package/dashboard/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/dashboard/src/lib/websocket.ts

@@ -0,0 +1,216 @@
+/**
+ * WebSocket client for real-time memory updates
+ *
+ * Connects to the visualization server's WebSocket endpoint
+ * and dispatches events to React Query for cache invalidation.
+ */
+
+import { useEffect, useRef, useCallback, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+
+const WS_URL = process.env.NEXT_PUBLIC_WS_URL || 'ws://localhost:3001/ws/events';
+
+export type WebSocketEventType =
+  | 'initial_state'
+  | 'memory_created'
+  | 'memory_accessed'
+  | 'memory_updated'
+  | 'memory_deleted'
+  | 'consolidation_complete'
+  | 'decay_tick'
+  // Phase 4: Worker events
+  | 'worker_light_tick'
+  | 'worker_medium_tick'
+  | 'link_discovered'
+  | 'predictive_consolidation';
+
+// Alias for backwards compatibility
+export type MemoryEventType = WebSocketEventType;
+
+interface WebSocketMessage {
+  type: WebSocketEventType;
+  data?: unknown;
+}
+
+interface UseMemoryWebSocketOptions {
+  enabled?: boolean;
+  onMessage?: (event: WebSocketMessage) => void;
+}
+
+// Reconnection configuration
+const INITIAL_RECONNECT_DELAY = 1000; // 1 second
+const MAX_RECONNECT_DELAY = 30000; // 30 seconds max
+const MAX_RECONNECT_ATTEMPTS = 10;
+
+/**
+ * Hook to connect to memory WebSocket and handle real-time updates
+ */
+export function useMemoryWebSocket(options: UseMemoryWebSocketOptions = {}) {
+  const { enabled = true, onMessage } = options;
+  const queryClient = useQueryClient();
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const reconnectAttemptsRef = useRef(0);
+  const reconnectDelayRef = useRef(INITIAL_RECONNECT_DELAY);
+  const [isConnected, setIsConnected] = useState(false);
+  const [lastEvent, setLastEvent] = useState<{
+    type: WebSocketEventType;
+    data?: unknown;
+    timestamp: string;
+  } | null>(null);
+
+  const connect = useCallback(() => {
+    if (!enabled || wsRef.current?.readyState === WebSocket.OPEN) return;
+
+    // Clear any pending reconnect timeout
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current);
+      reconnectTimeoutRef.current = null;
+    }
+
+    try {
+      const ws = new WebSocket(WS_URL);
+      wsRef.current = ws;
+
+      ws.onopen = () => {
+        setIsConnected(true);
+        // Reset reconnect state on successful connection
+        reconnectAttemptsRef.current = 0;
+        reconnectDelayRef.current = INITIAL_RECONNECT_DELAY;
+        console.log('[WebSocket] Connected to memory server');
+      };
+
+      ws.onmessage = (event) => {
+        try {
+          const message = JSON.parse(event.data) as WebSocketMessage & { timestamp?: string };
+          setLastEvent({
+            type: message.type,
+            data: message.data,
+            timestamp: message.timestamp || new Date().toISOString(),
+          });
+
+          // Notify external handler
+          onMessage?.(message);
+
+          // Invalidate relevant queries based on event type
+          switch (message.type) {
+            case 'initial_state':
+              // Full state received, refresh everything
+              queryClient.invalidateQueries({ queryKey: ['memories'] });
+              queryClient.invalidateQueries({ queryKey: ['stats'] });
+              queryClient.invalidateQueries({ queryKey: ['links'] });
+              break;
+
+            case 'memory_created':
+            case 'memory_updated':
+            case 'memory_deleted':
+              // Memory changed, refresh memories list
+              queryClient.invalidateQueries({ queryKey: ['memories'] });
+              queryClient.invalidateQueries({ queryKey: ['stats'] });
+              break;
+
+            case 'consolidation_complete':
+              // Major changes, refresh everything
+              queryClient.invalidateQueries({ queryKey: ['memories'] });
+              queryClient.invalidateQueries({ queryKey: ['stats'] });
+              queryClient.invalidateQueries({ queryKey: ['links'] });
+              break;
+
+            case 'decay_tick':
+              // Just decay scores updated, soft refresh
+              // We don't invalidate here to avoid constant refetches
+              // The dashboard can handle this via the onMessage callback
+              break;
+
+            // Phase 4: Worker events
+            case 'link_discovered':
+              // New link created, refresh links
+              queryClient.invalidateQueries({ queryKey: ['links'] });
+              break;
+
+            case 'predictive_consolidation':
+              // Predictive consolidation ran, refresh everything
+              queryClient.invalidateQueries({ queryKey: ['memories'] });
+              queryClient.invalidateQueries({ queryKey: ['stats'] });
+              queryClient.invalidateQueries({ queryKey: ['links'] });
+              break;
+
+            case 'worker_light_tick':
+            case 'worker_medium_tick':
+              // Worker ticks don't require cache invalidation
+              // Dashboard can track via onMessage callback if needed
+              break;
+          }
+        } catch (err) {
+          console.error('[WebSocket] Failed to parse message:', err);
+        }
+      };
+
+      ws.onerror = () => {
+        // Use warn instead of error to avoid Next.js error overlay in dev mode
+        // WebSocket connection failures are expected when API server isn't running
+        console.warn('[WebSocket] Connection failed - is the API server running?');
+      };
+
+      ws.onclose = () => {
+        setIsConnected(false);
+        console.log('[WebSocket] Disconnected');
+
+        // Attempt to reconnect with exponential backoff
+        if (enabled && reconnectAttemptsRef.current < MAX_RECONNECT_ATTEMPTS) {
+          const delay = reconnectDelayRef.current;
+          reconnectAttemptsRef.current++;
+
+          // Exponential backoff: double the delay each time, up to max
+          reconnectDelayRef.current = Math.min(
+            reconnectDelayRef.current * 2,
+            MAX_RECONNECT_DELAY
+          );
+
+          console.log(
+            `[WebSocket] Reconnecting in ${delay}ms (attempt ${reconnectAttemptsRef.current}/${MAX_RECONNECT_ATTEMPTS})...`
+          );
+
+          reconnectTimeoutRef.current = setTimeout(() => {
+            connect();
+          }, delay);
+        } else if (reconnectAttemptsRef.current >= MAX_RECONNECT_ATTEMPTS) {
+          console.error('[WebSocket] Max reconnection attempts reached. Use reconnect() to try again.');
+        }
+      };
+    } catch (err) {
+      console.error('[WebSocket] Failed to connect:', err);
+    }
+  }, [enabled, queryClient, onMessage]);
+
+  // Connect on mount
+  useEffect(() => {
+    if (enabled) {
+      connect();
+    }
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+        wsRef.current = null;
+      }
+    };
+  }, [enabled, connect]);
+
+  // Manual reconnect that resets backoff state
+  const manualReconnect = useCallback(() => {
+    reconnectAttemptsRef.current = 0;
+    reconnectDelayRef.current = INITIAL_RECONNECT_DELAY;
+    connect();
+  }, [connect]);
+
+  return {
+    isConnected,
+    lastEvent,
+    reconnect: manualReconnect,
+    reconnectAttempts: reconnectAttemptsRef.current,
+  };
+}