vektor-slipstream 1.4.4 → 2.0.0

package/briefing.js

@@ -1,150 +0,0 @@
-/**
- * VEKTOR briefing() date scoping — v1.3.7
- * Adds `since` param to briefing() — filter to last N days/hours
- * or an explicit ISO timestamp.
- *
- * Drop-in replacement for existing briefing() implementation.
- */
-
-import { VektorError, ERR } from './errors.js';
-
-/**
- * Parse a `since` value into a Unix timestamp (seconds).
- * Accepts:
- *   '1d'   → last 1 day
- *   '7d'   → last 7 days
- *   '12h'  → last 12 hours
- *   '30m'  → last 30 minutes
- *   '2026-01-01T00:00:00Z'  → explicit ISO date
- *   1735689600  → raw unix timestamp
- */
-export function parseSince(since) {
-  if (!since) return null;
-
-  // Raw unix timestamp — guard against Date.now() (ms) being passed accidentally
-  // If number > 9999999999 it's milliseconds (year ~2001 in seconds) — convert it
-  if (typeof since === 'number') {
-    return since > 9_999_999_999 ? Math.floor(since / 1000) : since;
-  }
-
-  // Relative shorthand: 7d, 12h, 30m
-  const rel = String(since).match(/^(\d+)(d|h|m)$/);
-  if (rel) {
-    const n = parseInt(rel[1]);
-    const unit = rel[2];
-    const seconds = unit === 'd' ? n * 86400 : unit === 'h' ? n * 3600 : n * 60;
-    return Math.floor(Date.now() / 1000) - seconds;
-  }
-
-  // ISO date string
-  const ts = Date.parse(since);
-  if (!isNaN(ts)) return Math.floor(ts / 1000);
-
-  throw new VektorError(
-    ERR.MEMORY_READ_FAILED,
-    `Invalid since value: "${since}". Use "7d", "12h", "30m", ISO date, or unix timestamp.`
-  );
-}
-
-/**
- * briefing({ since, limit, minImportance })
- * Returns a structured summary of recent memories for agent context injection.
- *
- * @param {object} db
- * @param {string} agentId
- * @param {string} namespace
- * @param {Function} summariseFn  - LLM summarise function (existing REM summariser)
- * @param {object} opts
- * @param {string|number} opts.since         - time filter (default: '1d')
- * @param {number}        opts.limit         - max memories (default: 20)
- * @param {number}        opts.minImportance - filter by importance score (default: 0)
- * @param {boolean}       opts.raw           - return raw memories, skip LLM summary
- * @returns {object}  { period, memoryCount, pinned, summary, memories }
- */
-export async function briefing(db, agentId, namespace, summariseFn, opts = {}) {
-  const {
-    since = '1d',
-    limit = 20,
-    minImportance = 0,
-    raw = false
-  } = opts;
-
-  const sinceTs = parseSince(since);
-  const sinceClause = sinceTs ? `AND created_at >= ${sinceTs}` : '';
-  const importanceClause = minImportance > 0 ? `AND importance >= ${minImportance}` : '';
-
-  // Fetch scoped memories
-  const memories = db.prepare(`
-    SELECT id, content, summary, importance, pinned, created_at
-    FROM memories
-    WHERE agent_id = ? AND namespace = ?
-    ${sinceClause}
-    ${importanceClause}
-    ORDER BY importance DESC, created_at DESC
-    LIMIT ?
-  `).all(agentId, namespace, limit);
-
-  // Always fetch pinned regardless of time window — hard cap 50 to prevent context bomb
-  // (an agent running for months could accumulate hundreds of pinned memories)
-  const pinnedLimit = 50;
-  const pinned = db.prepare(`
-    SELECT id, content, summary, importance, created_at
-    FROM memories
-    WHERE agent_id = ? AND namespace = ? AND pinned = 1
-    ORDER BY importance DESC
-    LIMIT ${pinnedLimit}
-  `).all(agentId, namespace);
-
-  if (raw) {
-    return {
-      period: since,
-      memoryCount: memories.length,
-      pinned,
-      memories
-    };
-  }
-
-  // Build prompt context for LLM summary
-  const context = [
-    pinned.length > 0
-      ? `PINNED (permanent):\n${pinned.map(m => `- ${m.summary || m.content}`).join('\n')}`
-      : null,
-    memories.length > 0
-      ? `RECENT (${since}):\n${memories.map(m => `- [${m.importance?.toFixed(2)}] ${m.summary || m.content}`).join('\n')}`
-      : 'No recent memories in this period.'
-  ].filter(Boolean).join('\n\n');
-
-  const summary = await summariseFn(
-    `Produce a concise agent briefing from these memories. Lead with pinned facts, then recent activity.\n\n${context}`
-  );
-
-  return {
-    period: since,
-    memoryCount: memories.length,
-    pinnedCount: pinned.length,
-    pinned,
-    memories,
-    summary
-  };
-}
-
-/**
- * Integration into Memory class:
- *
- * async briefing(opts = {}) {
- *   return briefing(this.db, this.agentId, this.namespace, this._summarise.bind(this), opts);
- * }
- *
- * Usage:
- *   await memory.briefing();
- *   // → last 24h summary (default)
- *
- *   await memory.briefing({ since: '7d' });
- *   // → last 7 days
- *
- *   await memory.briefing({ since: '2026-01-01', minImportance: 0.7 });
- *   // → since Jan 1st, high importance only
- *
- *   await memory.briefing({ raw: true, since: '1h' });
- *   // → raw memory objects, no LLM call
- */

package/cerebellum.js

@@ -1,439 +0,0 @@
-/**
- * cloak_cerebellum.js
- * Pre-write enforcer — checks every write against known error patterns in
- * Vektor's causal graph. Auto-creates [RESOLVED_BY] edges when a fix matches
- * an open error node. Zero extra tool calls from Claude.
- *
- * Two responsibilities:
- *   1. CHECK  — before a write, recall causal error patterns and warn if matched
- *   2. RESOLVE — if new write content matches an error pattern, auto-write
- *                [RESOLVED_BY] causal edge to close the loop
- *
- * Architecture: CLOAK layer → Vektor causal graph (MAGMA §3.4)
- * Research: MAGMA arXiv:2601.03236, OpenWolf cerebrum Do-Not-Repeat pattern
- *
- * Key design decision: cerebellum NEVER blocks a write, it only warns.
- * Claude Code must remain in control — cerebellum is advisory, not a gatekeeper.
- */
-
-'use strict';
-
-const crypto = require('crypto');
-
-// ---------------------------------------------------------------------------
-// Similarity threshold for pattern matching
-// ---------------------------------------------------------------------------
-const SIMILARITY_THRESHOLD = 0.72;
-
-// Max error patterns to check per write
-const MAX_PATTERNS_TO_CHECK = 8;
-
-// Minimum content length to bother checking — skip tiny edits (console.log,
-// closing braces, single-line comments). Not worth a Vektor round-trip.
-const MIN_CHECK_LENGTH = 50;
-
-// ---------------------------------------------------------------------------
-// LRU warning cache — prevents slamming Vektor on rapid multi-file writes
-// (MultiEdit, code generation loops, etc.)
-//
-// Key:   SHA-1 of content.slice(0,300) — cheap, collision-safe for this use
-// Value: { warnings, cachedAt }
-// TTL:   60 seconds — patterns don't change that fast within a session
-// Max:   100 entries — bounded memory, evicts oldest on overflow
-// ---------------------------------------------------------------------------
-const CACHE_TTL_MS  = 60_000;
-const CACHE_MAX     = 100;
-const _warningCache = new Map(); // key → { warnings, cachedAt }
-
-function _cacheKey(content) {
-  return crypto.createHash('sha1').update(content.slice(0, 300)).digest('hex');
-}
-
-function _cacheGet(key) {
-  const entry = _warningCache.get(key);
-  if (!entry) return null;
-  if (Date.now() - entry.cachedAt > CACHE_TTL_MS) {
-    _warningCache.delete(key);
-    return null;
-  }
-  return entry.warnings;
-}
-
-function _cacheSet(key, warnings) {
-  // Evict oldest entry if at capacity
-  if (_warningCache.size >= CACHE_MAX) {
-    _warningCache.delete(_warningCache.keys().next().value);
-  }
-  _warningCache.set(key, { warnings, cachedAt: Date.now() });
-}
-
-// ---------------------------------------------------------------------------
-// Pattern storage key prefix — namespaces cerebellum nodes in Vektor
-// ---------------------------------------------------------------------------
-const ERROR_PREFIX    = '[CLOAK_CEREBELLUM_ERROR]';
-const RESOLVED_PREFIX = '[CLOAK_CEREBELLUM_RESOLVED]';
-const DNR_PREFIX      = '[CLOAK_CEREBELLUM_DNR]';  // Do-Not-Repeat
-
-// ---------------------------------------------------------------------------
-// Core: check a write against known error patterns
-// ---------------------------------------------------------------------------
-
-/**
- * checkWrite({ content, filePath, memory })
- * Called from the PreToolUse hook before every write.
- * Returns warnings if the write matches known error patterns.
- *
- * @param {string} content   - The content being written
- * @param {string} filePath  - The file being written to
- * @param {object} memory    - Vektor memory instance
- * @returns {object}         - { warnings: [], shouldProceed: true }
- */
-async function checkWrite({ content, filePath, memory } = {}) {
-  if (!memory)  throw new Error('cloak_cerebellum: memory instance is required');
-  if (!content) return { warnings: [], shouldProceed: true, cached: false };
-
-  // Bypass: tiny writes aren't worth a Vektor round-trip
-  // (closing braces, console.logs, single-line cosmetic edits)
-  if (content.length < MIN_CHECK_LENGTH) {
-    return { warnings: [], shouldProceed: true, bypassed: 'too_small' };
-  }
-
-  // Cache hit: same content checked recently — return instantly, no Vektor call
-  const key    = _cacheKey(content);
-  const cached = _cacheGet(key);
-  if (cached !== null) {
-    return {
-      warnings    : cached,
-      shouldProceed: true,
-      hasBlockers : cached.some(w => w.severity === 'block'),
-      cached      : true,
-    };
-  }
-
-  const warnings = [];
-
-  try {
-    // Query causal error graph for patterns similar to this write
-    const errorPatterns = await memory.recall(
-      `${ERROR_PREFIX} ${content.slice(0, 300)}`,
-      MAX_PATTERNS_TO_CHECK
-    );
-
-    if (!errorPatterns || errorPatterns.length === 0) {
-      _cacheSet(key, []); // cache the empty result too — prevents repeat Vektor calls
-      return { warnings: [], shouldProceed: true, cached: false };
-    }
-
-    for (const pattern of errorPatterns) {
-      if (pattern.score < SIMILARITY_THRESHOLD) continue;
-
-      // Parse the stored pattern
-      const parsed = parsePatternNode(pattern.content);
-      if (!parsed) continue;
-
-      // Skip if this pattern is already resolved
-      if (parsed.resolvedBy) continue;
-
-      warnings.push({
-        patternId   : pattern.id,
-        description : parsed.description,
-        originalFile: parsed.file,
-        severity    : parsed.severity || 'warn',
-        hint        : parsed.fix || 'See error pattern for details',
-        score       : Math.round(pattern.score * 100) / 100,
-      });
-    }
-
-    // Also check Do-Not-Repeat rules (always enforced regardless of similarity)
-    const dnrRules = await memory.recall(
-      `${DNR_PREFIX}`,
-      5
-    );
-
-    if (dnrRules) {
-      for (const rule of dnrRules) {
-        const parsed = parseDNRNode(rule.content);
-        if (!parsed) continue;
-
-        // Check if the pattern keyword appears in the write content
-        if (content.toLowerCase().includes(parsed.keyword.toLowerCase())) {
-          warnings.push({
-            patternId   : rule.id,
-            description : `Do-Not-Repeat: ${parsed.rule}`,
-            severity    : 'block',
-            hint        : parsed.alternative || 'Avoid this pattern',
-            score       : 1.0,
-          });
-        }
-      }
-    }
-
-  } catch (err) {
-    // Non-fatal — Vektor query failure should not block writes
-    console.warn('[cloak_cerebellum] Pattern check failed:', err.message);
-  }
-
-  // Cache the result for 60s — rapid multi-file writes skip Vektor entirely
-  _cacheSet(key, warnings);
-
-  return {
-    warnings,
-    shouldProceed: true,
-    hasBlockers  : warnings.some(w => w.severity === 'block'),
-    cached       : false,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Core: record a new error pattern into the causal graph
-// ---------------------------------------------------------------------------
-
-/**
- * recordError({ description, filePath, errorType, fix, severity, memory })
- * Store a new error pattern so future writes can be warned.
- *
- * @param {string} description  - Human-readable description of the error
- * @param {string} filePath     - File where error occurred
- * @param {string} errorType    - e.g. 'null_reference', 'type_mismatch'
- * @param {string} fix          - What fixed it (optional)
- * @param {'warn'|'block'} severity
- * @param {object} memory       - Vektor memory instance
- * @returns {object}            - { id, written }
- */
-async function recordError({ description, filePath, errorType, fix, severity = 'warn', memory } = {}) {
-  if (!memory)      throw new Error('cloak_cerebellum: memory instance is required');
-  if (!description) throw new Error('cloak_cerebellum: description is required');
-
-  const patternStr = [
-    ERROR_PREFIX,
-    `error_type:${errorType || 'unknown'}`,
-    `file:${filePath || 'unknown'}`,
-    `description:${description}`,
-    `severity:${severity}`,
-    fix ? `fix:${fix}` : null,
-    `recorded_at:${new Date().toISOString()}`,
-    `resolved:false`,
-  ].filter(Boolean).join(' | ');
-
-  try {
-    await memory.remember(patternStr);
-    return { written: true, pattern: patternStr };
-  } catch (err) {
-    console.error('[cloak_cerebellum] Failed to record error:', err.message);
-    return { written: false, error: err.message };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Core: auto-resolve — detect when a write fixes an open error
-// Called from PostToolUse after a successful write.
-// This is the key improvement over OpenWolf — resolution is automatic,
-// not dependent on Claude remembering to call a separate tool.
-// ---------------------------------------------------------------------------
-
-/**
- * autoResolve({ content, filePath, memory })
- * After a successful write, check if it resolves any open error patterns.
- * If yes, write a [RESOLVED_BY] causal edge to close the loop.
- * This feeds the decay weighting in MAGMA's causal graph.
- *
- * @param {string} content   - Content that was written
- * @param {string} filePath  - File that was written
- * @param {object} memory    - Vektor memory instance
- * @returns {object}         - { resolved: [], written: number }
- */
-async function autoResolve({ content, filePath, memory } = {}) {
-  if (!memory || !filePath) return { resolved: [], written: 0 };
-
-  const resolved = [];
-
-  try {
-    // Query by FILE PATH not content — avoids the semantic gap where
-    // "Null reference on user.id" and "if (user && user.id)" have
-    // completely different embeddings despite one fixing the other.
-    // Pull all open errors on this file, then let REM cycle verify.
-    const candidates = await memory.recall(
-      `${ERROR_PREFIX} file:${filePath}`,
-      MAX_PATTERNS_TO_CHECK
-    );
-
-    if (!candidates || candidates.length === 0) return { resolved: [], written: 0 };
-
-    for (const candidate of candidates) {
-      // File path match is already a strong signal — use lower threshold
-      // than content matching. 0.5 avoids completely unrelated file path
-      // substring matches while catching real file-based errors.
-      if (candidate.score < 0.5) continue;
-
-      const parsed = parsePatternNode(candidate.content);
-      if (!parsed || parsed.resolvedBy) continue; // already resolved
-
-      // Only auto-resolve if the stored error references this exact file
-      if (parsed.file && parsed.file !== filePath &&
-          parsed.file !== require('path').basename(filePath)) continue;
-
-      // Write resolution node — this is the [RESOLVED_BY] causal edge
-      const resolutionStr = [
-        RESOLVED_PREFIX,
-        `resolves_pattern:${candidate.id}`,
-        `original_error:${parsed.description}`,
-        `resolved_by_file:${filePath || 'unknown'}`,
-        `resolved_at:${new Date().toISOString()}`,
-        `[RESOLVED_BY]`, // explicit causal edge marker for HippoRAG decay weighting
-      ].join(' | ');
-
-      try {
-        await memory.remember(resolutionStr);
-        resolved.push({
-          patternId  : candidate.id,
-          description: parsed.description,
-          resolution : resolutionStr,
-        });
-      } catch (err) {
-        console.warn('[cloak_cerebellum] Failed to write resolution:', err.message);
-      }
-    }
-
-  } catch (err) {
-    console.warn('[cloak_cerebellum] Auto-resolve query failed:', err.message);
-  }
-
-  return { resolved, written: resolved.length };
-}
-
-// ---------------------------------------------------------------------------
-// Do-Not-Repeat rules — project-level conventions
-// ---------------------------------------------------------------------------
-
-/**
- * addDNRRule({ keyword, rule, alternative, memory })
- * Store a Do-Not-Repeat rule. Checked on every write regardless of similarity.
- *
- * @param {string} keyword     - Trigger keyword/pattern to watch for
- * @param {string} rule        - Human description of what not to do
- * @param {string} alternative - What to do instead
- * @param {object} memory
- */
-async function addDNRRule({ keyword, rule, alternative, memory } = {}) {
-  if (!memory)  throw new Error('cloak_cerebellum: memory instance is required');
-  if (!keyword) throw new Error('cloak_cerebellum: keyword is required');
-  if (!rule)    throw new Error('cloak_cerebellum: rule is required');
-
-  const dnrStr = [
-    DNR_PREFIX,
-    `keyword:${keyword}`,
-    `rule:${rule}`,
-    alternative ? `alternative:${alternative}` : null,
-    `added_at:${new Date().toISOString()}`,
-  ].filter(Boolean).join(' | ');
-
-  try {
-    await memory.remember(dnrStr);
-    return { written: true };
-  } catch (err) {
-    console.error('[cloak_cerebellum] Failed to add DNR rule:', err.message);
-    return { written: false, error: err.message };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Claude Code hook integration
-// ---------------------------------------------------------------------------
-
-/**
- * handleHookPayload({ payload, memory })
- * Routes Claude Code PreToolUse/PostToolUse hooks to checkWrite / autoResolve.
- */
-async function handleHookPayload({ payload, memory } = {}) {
-  if (!memory || !payload) return null;
-
-  const hookName = payload?.hook_event_name || payload?.event;
-  const tool     = payload?.tool_name;
-  const input    = payload?.tool_input;
-  const output   = payload?.tool_response;
-
-  const isWrite = ['Write', 'Edit', 'MultiEdit', 'Bash'].includes(tool);
-
-  switch (hookName) {
-    case 'PreToolUse':
-    case 'pre_tool_use': {
-      if (!isWrite) return null;
-
-      // Bug fix: MultiEdit sends input.edits = [{ old_string, new_string }]
-      // not a flat input.new_string. Concatenate all new_string blocks so
-      // cerebellum actually sees the content being written in refactors.
-      let content = input?.new_string || input?.content || input?.command || '';
-      if (!content && input?.edits && Array.isArray(input.edits)) {
-        content = input.edits.map(e => e.new_string || '').filter(Boolean).join('\n');
-      }
-
-      const filePath = input?.file_path || input?.path || '';
-      return checkWrite({ content, filePath, memory });
-    }
-
-    case 'PostToolUse':
-    case 'post_tool_use': {
-      if (!isWrite) return null;
-      const success = !output?.error;
-      if (!success) return null;
-
-      // Same MultiEdit fix on the post-write resolve path
-      let content = input?.new_string || input?.content || '';
-      if (!content && input?.edits && Array.isArray(input.edits)) {
-        content = input.edits.map(e => e.new_string || '').filter(Boolean).join('\n');
-      }
-
-      const filePath = input?.file_path || input?.path || '';
-      return autoResolve({ content, filePath, memory });
-    }
-
-    default:
-      return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Parsers — extract structured data from Vektor node strings
-// ---------------------------------------------------------------------------
-function parsePatternNode(str) {
-  if (!str || !str.includes(ERROR_PREFIX)) return null;
-  const parts = str.split(' | ');
-  const get   = key => {
-    const part = parts.find(p => p.startsWith(`${key}:`));
-    return part ? part.slice(key.length + 1) : null;
-  };
-  return {
-    errorType : get('error_type'),
-    file      : get('file'),
-    description: get('description'),
-    severity  : get('severity'),
-    fix       : get('fix'),
-    resolvedBy: str.includes(RESOLVED_PREFIX) || get('resolved') === 'true' ? true : null,
-  };
-}
-
-function parseDNRNode(str) {
-  if (!str || !str.includes(DNR_PREFIX)) return null;
-  const parts = str.split(' | ');
-  const get   = key => {
-    const part = parts.find(p => p.startsWith(`${key}:`));
-    return part ? part.slice(key.length + 1) : null;
-  };
-  return {
-    keyword    : get('keyword'),
-    rule       : get('rule'),
-    alternative: get('alternative'),
-  };
-}
-
-module.exports = {
-  checkWrite,
-  recordError,
-  autoResolve,
-  addDNRRule,
-  handleHookPayload,
-  SIMILARITY_THRESHOLD,
-  ERROR_PREFIX,
-  RESOLVED_PREFIX,
-  DNR_PREFIX,
-};