vektor-slipstream 1.2.3 → 1.3.1

package/axon.js

@@ -0,0 +1,389 @@
+/**
+ * cloak_axon.js
+ * Session boundary handler — fires at SessionStart and Stop.
+ * Writes one MemCell per session end. Loads last MemCell on session start.
+ *
+ * Implements EverMemOS-style Episodic Trace Formation:
+ *   Stop  → bundle session into a single MemCell → memory.remember()
+ *   Start → memory.recall('[CLOAK_AXON_MEMCELL]') → seed context
+ *
+ * Architecture: CLOAK layer → Vektor semantic + temporal graphs
+ * Research: EverMemOS arXiv:2601.02163 §3.1 Episodic Trace Formation
+ *           MAGMA arXiv:2601.03236 §3.3 dual-stream fast ingest
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// ---------------------------------------------------------------------------
+// Crash recovery — debounced write to .wolf/axon-recovery.json
+// If process dies before Stop hook fires, this file survives.
+// On next SessionStart we detect it, build a MemCell, write to Vektor, delete.
+// ---------------------------------------------------------------------------
+let _crashWriteTimer = null;
+const CRASH_WRITE_DEBOUNCE_MS = 2000; // write at most every 2s
+
+function _getCrashLogPath(projectPath) {
+  const wolfDir = path.join(projectPath || process.cwd(), '.wolf');
+  return path.join(wolfDir, 'axon-recovery.json');
+}
+
+function _writeCrashLog() {
+  if (!_sessionLog.sessionId || !_sessionLog.projectPath) return;
+  try {
+    const wolfDir = path.join(_sessionLog.projectPath, '.wolf');
+    if (!fs.existsSync(wolfDir)) fs.mkdirSync(wolfDir, { recursive: true });
+    fs.writeFileSync(
+      _getCrashLogPath(_sessionLog.projectPath),
+      JSON.stringify({
+        sessionId        : _sessionLog.sessionId,
+        projectName      : _sessionLog.projectName,
+        startTime        : _sessionLog.startTime,
+        events           : _sessionLog.events.slice(-20), // last 20 only
+        filesWritten     : [..._sessionLog.filesWritten],
+        filesRead        : [..._sessionLog.filesRead].slice(0, 10),
+        errorsEncountered: _sessionLog.errorsEncountered,
+        fixesApplied     : _sessionLog.fixesApplied,
+        savedAt          : Date.now(),
+      }, null, 2)
+    );
+  } catch {
+    // Never let crash log writes block or error — silent failure is fine
+  }
+}
+
+function _debouncedCrashWrite() {
+  // Hook mode: process is ephemeral — exits immediately after hook runs.
+  // A debounced setTimeout would never fire before process.exit(0) kills it.
+  // Write synchronously here instead (single small JSON file, acceptable).
+  //
+  // MCP server mode: process is long-lived. Debounce avoids excessive fs
+  // writes on busy sessions (many rapid logEvent calls compress to one write).
+  if (process.argv.includes('--hook')) {
+    _writeCrashLog();
+    return;
+  }
+  if (_crashWriteTimer) clearTimeout(_crashWriteTimer);
+  _crashWriteTimer = setTimeout(_writeCrashLog, CRASH_WRITE_DEBOUNCE_MS);
+}
+
+// ---------------------------------------------------------------------------
+// Session log — accumulated in RAM, never written to disk raw
+// ---------------------------------------------------------------------------
+const _sessionLog = {
+  sessionId    : null,
+  projectPath  : null,
+  projectName  : null,
+  startTime    : null,
+  events       : [],   // { type, content, ts }
+  filesWritten : new Set(),
+  filesRead    : new Set(),
+  errorsEncountered: [],
+  fixesApplied : [],
+};
+
+function _resetLog() {
+  _sessionLog.sessionId     = null;
+  _sessionLog.projectPath   = null;
+  _sessionLog.projectName   = null;
+  _sessionLog.startTime     = null;
+  _sessionLog.events        = [];
+  _sessionLog.filesWritten  = new Set();
+  _sessionLog.filesRead     = new Set();
+  _sessionLog.errorsEncountered = [];
+  _sessionLog.fixesApplied  = [];
+}
+
+// ---------------------------------------------------------------------------
+// MemCell builder — condenses session into a single dense string
+// EverMemOS calls this "Episodic Trace Formation" — converts chat/event
+// stream into atomic facts + time-bounded summary.
+// ---------------------------------------------------------------------------
+function buildMemCell(log, tokenCount, narrative = '') {
+  const durationMs  = Date.now() - log.startTime;
+  const durationMin = Math.round(durationMs / 60000);
+
+  const parts = [
+    `[CLOAK_AXON_MEMCELL]`,
+    `session:${log.sessionId}`,
+    `project:${log.projectName}`,
+    `started:${new Date(log.startTime).toISOString()}`,
+    `ended:${new Date().toISOString()}`,
+    `duration:${durationMin}min`,
+    `tokens_used:~${tokenCount}`,
+  ];
+
+  // Intent/goal — the "WHY" of the session, not just the "WHAT"
+  // This is what separates memory from telemetry.
+  if (narrative && narrative.trim()) {
+    parts.push(`narrative:${narrative.trim().slice(0, 400)}`);
+  }
+
+  if (log.filesWritten.size > 0) {
+    parts.push(`files_written:${[...log.filesWritten].join(',')}`);
+  }
+
+  if (log.filesRead.size > 0) {
+    parts.push(`files_read:${[...log.filesRead].slice(0, 10).join(',')}`); // cap at 10
+  }
+
+  if (log.errorsEncountered.length > 0) {
+    parts.push(`errors:${log.errorsEncountered.slice(0, 5).join(' | ')}`);
+  }
+
+  if (log.fixesApplied.length > 0) {
+    parts.push(`fixes:${log.fixesApplied.slice(0, 5).join(' | ')}`);
+  }
+
+  // Key events summary — most recent 5 only (not raw log dump)
+  if (log.events.length > 0) {
+    const recent = log.events.slice(-5).map(e => e.content).join(' | ');
+    parts.push(`key_events:${recent}`);
+  }
+
+  return parts.join(' || ');
+}
+
+// ---------------------------------------------------------------------------
+// Session ID generator
+// ---------------------------------------------------------------------------
+function generateSessionId() {
+  return `S-${Date.now().toString(36).toUpperCase()}-${Math.random().toString(36).slice(2,6).toUpperCase()}`;
+}
+
+// ---------------------------------------------------------------------------
+// Hook: SessionStart
+// Loads the last MemCell from Vektor and returns it as seed context.
+// Does NOT write anything to Vektor — read only.
+// ---------------------------------------------------------------------------
+
+/**
+ * onSessionStart({ projectPath, memory })
+ * Call this when Claude Code fires the SessionStart hook.
+ * Returns the last session's MemCell content as a string for context seeding.
+ */
+async function onSessionStart({ projectPath, memory } = {}) {
+  if (!projectPath) throw new Error('cloak_axon: projectPath is required');
+  if (!memory)      throw new Error('cloak_axon: memory instance is required');
+
+  // ── Crash recovery check ─────────────────────────────────────────────────
+  // If a recovery file exists, the last session died without firing Stop.
+  // Rescue it: build a MemCell, write to Vektor, delete the file.
+  const crashLogPath = _getCrashLogPath(projectPath);
+  let crashRecovered = false;
+  try {
+    if (fs.existsSync(crashLogPath)) {
+      const crashed = JSON.parse(fs.readFileSync(crashLogPath, 'utf8'));
+      if (crashed.sessionId) {
+        // Reconstruct _sessionLog from crash data to build MemCell
+        const tempLog = {
+          sessionId        : crashed.sessionId,
+          projectPath,
+          projectName      : crashed.projectName,
+          startTime        : crashed.startTime,
+          events           : crashed.events || [],
+          filesWritten     : new Set(crashed.filesWritten || []),
+          filesRead        : new Set(crashed.filesRead || []),
+          errorsEncountered: crashed.errorsEncountered || [],
+          fixesApplied     : crashed.fixesApplied || [],
+        };
+        const crashMemCell = buildMemCell(tempLog, 0) + ' || recovered_from_crash:true';
+        await memory.remember(crashMemCell).catch(() => {});
+        crashRecovered = true;
+      }
+      fs.unlinkSync(crashLogPath); // clean up regardless
+    }
+  } catch {
+    // Recovery failure is non-fatal — proceed with new session
+  }
+
+  // Reset RAM log for new session
+  _resetLog();
+  _sessionLog.sessionId   = generateSessionId();
+  _sessionLog.projectPath = projectPath;
+  _sessionLog.projectName = path.basename(projectPath);
+  _sessionLog.startTime   = Date.now();
+
+  // Recall last MemCell from Vektor — single fast query, no PPR needed here
+  let lastContext = null;
+  try {
+    const results = await memory.recall(
+      `[CLOAK_AXON_MEMCELL] project:${_sessionLog.projectName}`,
+      { limit: 1 }
+    );
+    if (results && results.length > 0) {
+      lastContext = results[0].content;
+    }
+  } catch (err) {
+    // Non-fatal — first session or Vektor not yet seeded
+    console.warn('[cloak_axon] Could not load last MemCell:', err.message);
+  }
+
+  return {
+    sessionId   : _sessionLog.sessionId,
+    projectName : _sessionLog.projectName,
+    crashRecovered,
+    lastContext,
+    message     : crashRecovered
+      ? `Crash recovery: rescued lost session. Last context loaded.`
+      : lastContext
+        ? `Session ${_sessionLog.sessionId} started. Last session context loaded.`
+        : `Session ${_sessionLog.sessionId} started. No prior context (first run or new project).`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Hook: onEvent — accumulate session events in RAM
+// Call this from axon or cerebellum when notable things happen.
+// Does NOT write to Vektor — that only happens at Stop.
+// ---------------------------------------------------------------------------
+
+/**
+ * logEvent(type, content)
+ * @param {'file_write'|'file_read'|'error'|'fix'|'note'} type
+ * @param {string} content
+ */
+function logEvent(type, content) {
+  if (!_sessionLog.sessionId) return;
+
+  const truncated = String(content).slice(0, 200);
+
+  _sessionLog.events.push({ type, content: truncated, ts: Date.now() });
+
+  switch (type) {
+    case 'file_write':
+      _sessionLog.filesWritten.add(path.basename(truncated));
+      break;
+    case 'file_read':
+      _sessionLog.filesRead.add(path.basename(truncated));
+      break;
+    case 'error':
+      _sessionLog.errorsEncountered.push(truncated);
+      break;
+    case 'fix':
+      _sessionLog.fixesApplied.push(truncated);
+      break;
+  }
+
+  // Debounced crash recovery write — survives SIGKILL
+  _debouncedCrashWrite();
+}
+
+// ---------------------------------------------------------------------------
+// Hook: SessionStop
+// Builds MemCell from RAM log, writes ONE node to Vektor, clears log.
+// This is the ONLY write call in axon — one per session, not continuous.
+// ---------------------------------------------------------------------------
+
+/**
+ * onSessionStop({ memory, tokenCount })
+ * Call this when Claude Code fires the Stop hook.
+ * @param {object}  memory      - Vektor memory instance
+ * @param {number}  tokenCount  - Total tokens used this session (from cloak_token)
+ * @returns {object}            - { sessionId, memCell, written }
+ */
+async function onSessionStop({ memory, tokenCount = 0, narrative = '' } = {}) {
+  if (!memory) throw new Error('cloak_axon: memory instance is required');
+
+  if (!_sessionLog.sessionId) {
+    console.warn('[cloak_axon] onSessionStop called without active session');
+    return { sessionId: null, memCell: null, written: false };
+  }
+
+  // Cancel any pending debounced crash write — clean stop, no crash
+  if (_crashWriteTimer) {
+    clearTimeout(_crashWriteTimer);
+    _crashWriteTimer = null;
+  }
+
+  // Delete crash recovery file — session ended cleanly
+  try {
+    const crashLogPath = _getCrashLogPath(_sessionLog.projectPath);
+    if (fs.existsSync(crashLogPath)) fs.unlinkSync(crashLogPath);
+  } catch {}
+
+  // Build the MemCell — includes narrative intent from final Claude message
+  const memCell = buildMemCell(_sessionLog, tokenCount, narrative);
+
+  let written = false;
+  try {
+    await memory.remember(memCell);
+    written = true;
+  } catch (err) {
+    console.error('[cloak_axon] Failed to write MemCell:', err.message);
+  }
+
+  const result = {
+    sessionId : _sessionLog.sessionId,
+    memCell,
+    written,
+    events    : _sessionLog.events.length,
+    duration  : Math.round((Date.now() - _sessionLog.startTime) / 60000),
+  };
+
+  _resetLog(); // clear RAM — do not persist raw events
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code hook registration helper
+// Reads Claude Code's hook payload from stdin (as Claude Code sends it)
+// and routes to the correct handler.
+// ---------------------------------------------------------------------------
+
+/**
+ * handleHookPayload({ payload, memory, projectPath, tokenCount })
+ * Use this if integrating directly with Claude Code's hook system.
+ * Claude Code sends JSON via stdin to hook scripts.
+ */
+async function handleHookPayload({ payload, memory, projectPath, tokenCount = 0 } = {}) {
+  const hookName = payload?.hook_event_name || payload?.event;
+
+  switch (hookName) {
+    case 'SessionStart':
+    case 'session_start':
+      return onSessionStart({ projectPath: projectPath || payload?.cwd, memory });
+
+    case 'Stop':
+    case 'session_stop': {
+      // Extract Claude's final summary message as session narrative
+      // Claude Code emits a final assistant message before Stop — this is the "Why"
+      const narrative = payload?.last_assistant_message
+        || payload?.session_summary
+        || payload?.final_message
+        || '';
+      return onSessionStop({
+        memory,
+        tokenCount,
+        narrative,
+      });
+    }
+
+    case 'PreToolUse':
+    case 'PostToolUse': {
+      // Log file reads/writes for MemCell accumulation
+      const tool  = payload?.tool_name;
+      const input = payload?.tool_input;
+      if (tool === 'Write' || tool === 'Edit' || tool === 'MultiEdit') {
+        logEvent('file_write', input?.file_path || input?.path || 'unknown');
+      } else if (tool === 'Read') {
+        logEvent('file_read', input?.file_path || input?.path || 'unknown');
+      }
+      return null; // no write to Vektor on per-tool hooks
+    }
+
+    default:
+      return null;
+  }
+}
+
+module.exports = {
+  onSessionStart,
+  onSessionStop,
+  logEvent,
+  handleHookPayload,
+  _sessionLog, // exported for testing and cloak_token integration
+};