prism-mcp-server 8.0.2 → 9.0.4

package/dist/dashboard/ui.js

@@ -615,6 +615,9 @@ export function renderDashboardHTML(version) {
     </div>
 
     <div id="content" class="grid grid-main fade-in">
+      <div style="grid-column: 1 / -1; display: flex; align-items: center; gap: 1rem; margin-bottom: -1rem; padding: 0 1rem;">
+        <h1 id="activeProjectTitle" style="margin: 0; font-size: 2.2rem; color: var(--text-primary); text-shadow: 0 0 15px rgba(168, 85, 247, 0.4); font-weight: 700; letter-spacing: -0.02em;"></h1>
+      </div>
       <!-- Left Column -->
       <div class="grid" style="align-content: start;">
         <!-- Current State -->
@@ -1048,12 +1051,70 @@ export function renderDashboardHTML(version) {
             <div class="setting-label">Storage Backend</div>
             <div class="setting-desc">Switch between SQLite and Supabase</div>
           </div>
-          <select id="storageBackendSelect" onchange="window.saveBootSetting('PRISM_STORAGE', this.value)" style="padding: 0.2rem 0.4rem; background: var(--bg-hover); color: var(--text-primary); border: 1px solid var(--border-color); border-radius: 4px; font-size: 0.85rem; font-family: var(--font-mono); cursor: pointer;">
+          <select id="storageBackendSelect" onchange="onStorageProviderChange(this.value)" style="padding: 0.2rem 0.4rem; background: var(--bg-hover); color: var(--text-primary); border: 1px solid var(--border-color); border-radius: 4px; font-size: 0.85rem; font-family: var(--font-mono); cursor: pointer;">
             <option value="local">SQLite</option>
             <option value="supabase">Supabase</option>
           </select>
         </div>
 
+        <!-- Supabase fields -->
+        <div id="provider-fields-supabase" style="display:none; padding: 1rem; background: rgba(139,92,246,0.05); border-radius: var(--radius-sm); border: 1px solid var(--border-glass); margin-top: 0.5rem;">
+          <div class="setting-section" style="margin-top:0">Supabase Connection Setup</div>
+          <div style="font-size:0.75rem; color:var(--text-muted); margin-bottom: 1rem; line-height: 1.5;">
+            Configure your Supabase backend. This will run the migration schema to set up tables automatically before saving credentials.
+          </div>
+          
+          <div class="setting-row" style="border:none; padding:0.25rem 0">
+            <div>
+              <div class="setting-label">Supabase URL</div>
+            </div>
+            <input type="text" id="input-supabase-url"
+              placeholder="https://xyz.supabase.co"
+              style="padding: 0.3rem 0.5rem; background: var(--bg-hover); color: var(--text-primary); border: 1px solid var(--border-color); border-radius: 4px; font-size: 0.85rem; font-family: var(--font-mono); width: 220px;" />
+          </div>
+          <div class="setting-row" style="border:none; padding:0.25rem 0">
+            <div>
+              <div class="setting-label">Service Role Key</div>
+            </div>
+            <input type="password" id="input-supabase-key"
+              placeholder="eyJh..."
+              style="padding: 0.3rem 0.5rem; background: var(--bg-hover); color: var(--text-primary); border: 1px solid var(--border-color); border-radius: 4px; font-size: 0.85rem; font-family: var(--font-mono); width: 220px;" />
+          </div>
+          <div class="setting-row" style="border:none; padding:0.25rem 0">
+            <div>
+              <div class="setting-label">Database Password</div>
+              <div class="setting-desc">Needed once to bootstrap tables. Never saved.</div>
+            </div>
+            <input type="password" id="input-supabase-dbpass"
+              placeholder="••••••••"
+              style="padding: 0.3rem 0.5rem; background: var(--bg-hover); color: var(--text-primary); border: 1px solid var(--border-color); border-radius: 4px; font-size: 0.85rem; font-family: var(--font-mono); width: 220px;" />
+          </div>
+
+          <div style="margin-top: 1rem; display: flex; align-items: center; gap: 0.5rem;">
+            <button onclick="setupSupabase()" id="btn-setup-supabase" style="background: var(--accent-purple); color: white; border: none; padding: 0.5rem 1rem; border-radius: var(--radius-sm); font-size: 0.85rem; font-weight: 600; cursor: pointer; transition: opacity 0.2s;">
+              Set Up &amp; Migrate
+            </button>
+            <span id="setup-supabase-status" style="font-size: 0.8rem; font-weight: 500;"></span>
+          </div>
+
+          <!-- Migration progress bar (hidden until setup starts) -->
+          <div id="migration-progress-wrap" style="display:none; margin-top: 0.75rem;">
+            <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom: 0.35rem;">
+              <span id="migration-step-label" style="font-size:0.75rem; color:var(--text-muted); font-weight:500;">Initializing…</span>
+              <span id="migration-pct-label" style="font-size:0.75rem; color:var(--accent-purple); font-weight:700;">0%</span>
+            </div>
+            <div style="height:6px; border-radius:99px; background:var(--bg-hover); overflow:hidden;">
+              <div id="migration-progress-bar"
+                style="height:100%; width:0%; border-radius:99px;
+                       background: linear-gradient(90deg, #7c3aed, #a78bfa);
+                       transition: width 0.4s cubic-bezier(0.4,0,0.2,1);"></div>
+            </div>
+            <!-- Step dots -->
+            <div id="migration-step-dots" style="display:flex; gap:0.35rem; margin-top:0.5rem; flex-wrap:wrap;"></div>
+          </div>
+
+        </div>
+
         <div class="setting-row" style="align-items:flex-start">
           <div>
             <div class="setting-label">Auto-Load Projects</div>
@@ -1810,6 +1871,7 @@ function loadProject() {
                     document.getElementById('welcome').style.display = 'none';
                     document.getElementById('content').style.display = 'none';
                     document.getElementById('loading').style.display = 'block';
+                    document.getElementById('activeProjectTitle').textContent = "📁 " + project;
                     _a.label = 1;
                 case 1:
                     _a.trys.push([1, 9, 10, 11]);
@@ -3196,6 +3258,146 @@ function onEmbeddingProviderChange(value) {
     refreshAnthropicWarning(textVal, value);
     saveBootSetting('embedding_provider', value);
 }
+
+function onStorageProviderChange(value) {
+    var supFields = document.getElementById('provider-fields-supabase');
+    if (supFields) supFields.style.display = value === 'supabase' ? '' : 'none';
+    
+    // Only auto-save if switching to local. Supabase is saved via the migrate button.
+    if (value === 'local') {
+        saveBootSetting('PRISM_STORAGE', value);
+    }
+}
+
+function setupSupabase() {
+    var url = document.getElementById('input-supabase-url').value.trim();
+    var serviceKey = document.getElementById('input-supabase-key').value.trim();
+    var dbPassword = document.getElementById('input-supabase-dbpass').value.trim();
+    var statusEl = document.getElementById('setup-supabase-status');
+    var btn = document.getElementById('btn-setup-supabase');
+
+    if (!url || !serviceKey || !dbPassword) {
+        statusEl.innerText = "All fields required.";
+        statusEl.style.color = "var(--accent-rose)";
+        return;
+    }
+    if (url.indexOf('https://') !== 0) {
+        statusEl.innerText = "URL must start with https://";
+        statusEl.style.color = "var(--accent-rose)";
+        return;
+    }
+    if (serviceKey.indexOf('eyJ') !== 0) {
+        statusEl.innerText = "Service key appears invalid. Expected JWT.";
+        statusEl.style.color = "var(--accent-rose)";
+        return;
+    }
+
+    // Reset UI state
+    statusEl.innerText = "Connecting & Migrating…";
+    statusEl.style.color = "var(--text-muted)";
+    btn.disabled = true;
+    btn.style.opacity = "0.5";
+
+    // Show progress bar
+    var progressWrap = document.getElementById('migration-progress-wrap');
+    var progressBar = document.getElementById('migration-progress-bar');
+    var stepLabel  = document.getElementById('migration-step-label');
+    var pctLabel   = document.getElementById('migration-pct-label');
+    var stepDots   = document.getElementById('migration-step-dots');
+    progressWrap.style.display = '';
+    progressBar.style.width = '0%';
+    stepDots.innerHTML = '';
+
+    // Helper: update bar
+    function setProgress(pct, label, ok) {
+        progressBar.style.width = pct + '%';
+        if (ok === false) progressBar.style.background = 'linear-gradient(90deg,#dc2626,#f87171)';
+        stepLabel.innerText = label;
+        pctLabel.innerText = Math.round(pct) + '%';
+    }
+
+    // Helper: add step dot
+    function addDot(label, state) {
+        var dot = document.createElement('span');
+        var colors = { pending: 'var(--text-muted)', ok: 'var(--accent-green)', err: 'var(--accent-rose)' };
+        var icons  = { pending: '○', ok: '✓', err: '×' };
+        dot.title = label;
+        dot.style.cssText = 'display:inline-flex;align-items:center;gap:2px;font-size:0.7rem;color:' + colors[state] + ';font-weight:600;';
+        dot.innerText = icons[state] + ' ' + label;
+        stepDots.appendChild(dot);
+    }
+
+    setProgress(5, 'Connecting to Supabase…');
+
+    // Subscribe to server-sent progress events for this session
+    var evtKey = Date.now().toString();
+    var sse = new EventSource('/api/migration/progress?key=' + evtKey);
+    var sseTimeout = setTimeout(function() {
+        if (sse) { sse.close(); sse = null; }
+    }, 120000); // 2-min safety timeout
+
+    if (sse) {
+        sse.onmessage = function(e) {
+            try {
+                var msg = JSON.parse(e.data);
+                // msg: { step, total, label, pct?, done?, error? }
+                var pct = msg.pct !== undefined ? msg.pct : Math.round((msg.step / msg.total) * 100);
+                if (msg.error) {
+                    setProgress(pct, '⚠ ' + msg.label, false);
+                    addDot(msg.label, 'err');
+                } else if (msg.done) {
+                    setProgress(100, '✓ All migrations applied');
+                    addDot('Done', 'ok');
+                    if (sse) { sse.close(); sse = null; }
+                    clearTimeout(sseTimeout);
+                } else {
+                    setProgress(pct, msg.label);
+                    if (msg.step > 1) addDot(msg.prevLabel || msg.label, 'ok');
+                }
+            } catch(_) {}
+        };
+        sse.onerror = function() {
+            // SSE closed server-side after completion — normal
+            if (sse) { sse.close(); sse = null; }
+            clearTimeout(sseTimeout);
+        };
+    }
+
+    fetch('/api/setup-supabase', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ url: url, serviceKey: serviceKey, dbPassword: dbPassword, progressKey: evtKey })
+    })
+    .then(function(res) {
+        return res.json().then(function(data) {
+            if (res.ok && data.ok) {
+                setProgress(100, '✓ All done!');
+                statusEl.innerText = "✓ Configured. Restart Prism.";
+                statusEl.style.color = "var(--accent-green)";
+                setTimeout(function() {
+                    alert("Supabase configured!\\n\\nRestart Prism MCP server for changes to take effect.");
+                }, 300);
+            } else {
+                var errMsg = data.error || "Setup failed.";
+                setProgress(progressBar ? parseFloat(progressBar.style.width) : 0, '⚠ ' + errMsg, false);
+                statusEl.innerText = errMsg;
+                statusEl.style.color = "var(--accent-rose)";
+            }
+        });
+    })
+    .catch(function() {
+        setProgress(0, 'Network error', false);
+        statusEl.innerText = "Network error.";
+        statusEl.style.color = "var(--accent-rose)";
+    })
+    .finally(function() {
+        btn.disabled = false;
+        btn.style.opacity = "1";
+        if (sse) { sse.close(); sse = null; }
+        clearTimeout(sseTimeout);
+    });
+}
+
 // Shows/hides the Anthropic+auto warning.
 // Warning appears when: text=anthropic AND embedding=auto (auto-bridges to Gemini).
 function refreshAnthropicWarning(textVal, embedVal) {
@@ -3438,6 +3640,14 @@ function loadSettings() {
                     // Storage Backend
                     if (s.PRISM_STORAGE) {
                         document.getElementById('storageBackendSelect').value = s.PRISM_STORAGE;
+                        var supFields = document.getElementById('provider-fields-supabase');
+                        if (supFields) supFields.style.display = s.PRISM_STORAGE === 'supabase' ? '' : 'none';
+                    }
+                    if (s.SUPABASE_URL) {
+                        document.getElementById('input-supabase-url').value = s.SUPABASE_URL;
+                    }
+                    if (s.SUPABASE_SERVICE_KEY) {
+                        document.getElementById('input-supabase-key').placeholder = '(key saved — paste to update)';
                     }
                     // Agent Identity
                     if (s.default_role)

package/dist/memory/cognitiveBudget.js

@@ -0,0 +1,224 @@
+/**
+ * Cognitive Budget — Token-Economic RL (v9.0)
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * PURPOSE:
+ *   Implements a strict token economy for agent memory operations.
+ *   Instead of having infinite memory budgets, agents must learn to
+ *   save high-signal, compressed entries — through physics, not prompts.
+ *
+ * ECONOMY DESIGN:
+ *   - Budget is PERSISTENT (stored in session_handoffs.cognitive_budget)
+ *   - Budget belongs to the PROJECT, not the ephemeral session
+ *   - This prevents the "Reset Exploit" (close & reopen to get free tokens)
+ *   - Revenue comes from Universal Basic Income (time-based) + success bonuses
+ *   - No retrieval-based earning (prevents the "Minting Exploit" / search spam)
+ *
+ * COST MULTIPLIERS:
+ *   Incoming entry surprisal determines the budget cost multiplier:
+ *   - Low surprisal (boilerplate): 2.0× cost — penalizes "I updated CSS"
+ *   - Normal surprisal:            1.0× cost — standard rate
+ *   - High surprisal (novel):      0.5× cost — rewards novel insights
+ *
+ * GRACEFUL DEGRADATION:
+ *   Budget exhaustion produces a WARNING in the MCP response but NEVER
+ *   blocks the SQL insert. We never lose agent work due to verbosity.
+ *
+ * MINIMUM BASE COST:
+ *   Empty/trivial summaries still bleed the budget (10 token minimum)
+ *   to prevent zero-cost gaming with empty saves.
+ *
+ * UBI (UNIVERSAL BASIC INCOME):
+ *   Instead of earning through arbitrary search spam, agents earn
+ *   budget passively through time elapsed since last save:
+ *   - +100 tokens per hour since last ledger save (capped at +500/session)
+ *   - +200 bonus for a `success` experience event
+ *   - +100 bonus for a `learning` experience event
+ *
+ * FILES THAT IMPORT THIS:
+ *   - src/tools/ledgerHandlers.ts (budget tracking + diagnostics)
+ *   - src/tools/ledgerHandlers.ts (budget persistence in handoff)
+ * ═══════════════════════════════════════════════════════════════════
+ */
+// ─── Constants ────────────────────────────────────────────────
+/** Default initial budget per project (tokens) */
+export const DEFAULT_BUDGET_SIZE = 2000;
+/** Minimum base cost per save operation (tokens) — prevents zero-cost gaming */
+export const MINIMUM_BASE_COST = 10;
+/** UBI: tokens earned per hour since last save */
+export const UBI_TOKENS_PER_HOUR = 100;
+/** UBI: maximum tokens earnable via time-based UBI per session */
+export const UBI_MAX_PER_SESSION = 500;
+/** Bonus tokens for saving a `success` experience event */
+export const SUCCESS_BONUS = 200;
+/** Bonus tokens for saving a `learning` experience event */
+export const LEARNING_BONUS = 100;
+/** Budget warning threshold (below this, show advisory) */
+export const LOW_BUDGET_THRESHOLD = 300;
+// ─── Cost Multipliers ────────────────────────────────────────
+/** Surprisal thresholds for cost multiplier tiers */
+export const BOILERPLATE_THRESHOLD = 0.2;
+export const NOVEL_THRESHOLD = 0.7;
+/**
+ * Compute the cost multiplier based on content surprisal.
+ *
+ * - Low surprisal (< 0.2): 2.0× — penalizes boilerplate
+ * - Normal surprisal (0.2 - 0.7): 1.0× — standard rate
+ * - High surprisal (> 0.7): 0.5× — rewards novel insights
+ *
+ * @param surprisal - Surprisal score in [0.0, 1.0]
+ * @returns Cost multiplier
+ */
+export function computeCostMultiplier(surprisal) {
+    if (!Number.isFinite(surprisal))
+        return 1.0;
+    if (surprisal < BOILERPLATE_THRESHOLD)
+        return 2.0;
+    if (surprisal > NOVEL_THRESHOLD)
+        return 0.5;
+    return 1.0;
+}
+// ─── Token Counting ───────────────────────────────────────────
+/**
+ * Estimate token count from text using the standard 1 token ≈ 4 chars.
+ * Enforces the minimum base cost to prevent zero-cost gaming.
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated token count (minimum: MINIMUM_BASE_COST)
+ */
+export function estimateTokens(text) {
+    if (!text || text.trim().length === 0)
+        return MINIMUM_BASE_COST;
+    return Math.max(MINIMUM_BASE_COST, Math.ceil(text.length / 4));
+}
+// ─── UBI Calculator ───────────────────────────────────────────
+/**
+ * Compute Universal Basic Income tokens earned since last save.
+ *
+ * @param lastSaveTime - ISO timestamp of last ledger save (or null if first save)
+ * @param currentTime - Current time (default: now)
+ * @returns Tokens earned via UBI (capped at UBI_MAX_PER_SESSION)
+ */
+export function computeUBI(lastSaveTime, currentTime = new Date()) {
+    if (!lastSaveTime)
+        return 0; // First save — no UBI
+    const lastSave = new Date(lastSaveTime);
+    if (isNaN(lastSave.getTime()))
+        return 0;
+    const hoursSinceLastSave = (currentTime.getTime() - lastSave.getTime()) / (1000 * 60 * 60);
+    if (hoursSinceLastSave <= 0)
+        return 0;
+    // NOTE: Do NOT use Math.floor here — it destroys fractional earnings.
+    // An agent saving every 15 min computes floor(0.25 * 100) = 0 tokens.
+    // Since cognitive_budget is REAL (SQLite) / float8 (Postgres), fractional
+    // values are natively supported. Only round at the UI display layer.
+    const earned = hoursSinceLastSave * UBI_TOKENS_PER_HOUR;
+    return Math.min(earned, UBI_MAX_PER_SESSION);
+}
+/**
+ * Compute bonus tokens for specific experience event types.
+ *
+ * @param eventType - The experience event type
+ * @returns Bonus tokens to add to budget
+ */
+export function computeEventBonus(eventType) {
+    switch (eventType) {
+        case 'success': return SUCCESS_BONUS;
+        case 'learning': return LEARNING_BONUS;
+        default: return 0;
+    }
+}
+// ─── Budget Manager ───────────────────────────────────────────
+/**
+ * Stateless budget operations.
+ *
+ * The budget is stored as a number in session_handoffs.cognitive_budget.
+ * These functions compute the new balance — they don't persist anything.
+ * The caller (ledgerHandlers.ts) is responsible for persistence.
+ */
+/**
+ * Process a budget spend operation.
+ *
+ * @param currentBalance - Current budget balance
+ * @param rawTokenCost - Raw token cost of the entry
+ * @param surprisal - Surprisal score of the content [0, 1]
+ * @param budgetSize - Initial budget size (for diagnostics)
+ * @returns BudgetResult with new balance, warnings, and diagnostics
+ */
+export function spendBudget(currentBalance, rawTokenCost, surprisal, budgetSize = DEFAULT_BUDGET_SIZE) {
+    const safeCost = Math.max(MINIMUM_BASE_COST, rawTokenCost);
+    const multiplier = computeCostMultiplier(surprisal);
+    const adjustedCost = Math.ceil(safeCost * multiplier);
+    const newBalance = currentBalance - adjustedCost;
+    const remaining = Math.max(0, newBalance);
+    let warning;
+    if (newBalance <= 0) {
+        warning = `⚠️ Cognitive budget exhausted (${remaining}/${budgetSize} tokens). ` +
+            'Consider saving more concise, high-signal entries. ' +
+            'Budget recovers passively over time (+100 tokens/hour).';
+    }
+    else if (newBalance < LOW_BUDGET_THRESHOLD) {
+        warning = `⚡ Cognitive budget running low (${remaining}/${budgetSize} tokens). ` +
+            'Prioritize novel, dense entries to reduce cost.';
+    }
+    return {
+        allowed: true, // Always allow — graceful degradation
+        spent: adjustedCost,
+        remaining,
+        warning,
+        surprisal,
+        costMultiplier: multiplier,
+    };
+}
+/**
+ * Apply Universal Basic Income + event bonuses to a budget balance.
+ *
+ * @param currentBalance - Current budget balance
+ * @param lastSaveTime - ISO timestamp of last save
+ * @param eventType - Optional event type for bonus
+ * @param budgetSize - Maximum budget cap
+ * @returns New balance after UBI + bonuses (capped at budgetSize)
+ */
+export function applyEarnings(currentBalance, lastSaveTime, eventType, budgetSize = DEFAULT_BUDGET_SIZE) {
+    const ubiEarned = computeUBI(lastSaveTime);
+    const bonusEarned = computeEventBonus(eventType);
+    // Cap at initial budget size — can't exceed maximum
+    const newBalance = Math.min(budgetSize, currentBalance + ubiEarned + bonusEarned);
+    return { newBalance, ubiEarned, bonusEarned };
+}
+/**
+ * Format budget diagnostics for inclusion in MCP response text.
+ *
+ * @param result - The BudgetResult from spendBudget()
+ * @param budgetSize - Initial budget size
+ * @param ubiEarned - Tokens earned from UBI this operation
+ * @param bonusEarned - Tokens earned from event bonus
+ * @returns Formatted diagnostic string
+ */
+export function formatBudgetDiagnostics(result, budgetSize = DEFAULT_BUDGET_SIZE, ubiEarned = 0, bonusEarned = 0) {
+    const parts = [];
+    // Budget line
+    const barLength = 20;
+    const fillLength = Math.round((result.remaining / budgetSize) * barLength);
+    const bar = '█'.repeat(Math.max(0, fillLength)) + '░'.repeat(Math.max(0, barLength - fillLength));
+    parts.push(`💰 Budget: ${bar} ${result.remaining}/${budgetSize}`);
+    // Surprisal line
+    if (result.surprisal !== undefined) {
+        const surprisalLabel = result.surprisal < BOILERPLATE_THRESHOLD ? 'boilerplate'
+            : result.surprisal > NOVEL_THRESHOLD ? 'novel'
+                : 'standard';
+        parts.push(`📊 Surprisal: ${result.surprisal.toFixed(2)} (${surprisalLabel}) — cost: ${result.costMultiplier?.toFixed(1)}×`);
+    }
+    // Cost line
+    parts.push(`🪙 Spent: ${result.spent} tokens`);
+    // Earnings line (if any)
+    if (ubiEarned > 0 || bonusEarned > 0) {
+        const earningParts = [];
+        if (ubiEarned > 0)
+            earningParts.push(`+${Math.round(ubiEarned)} UBI`);
+        if (bonusEarned > 0)
+            earningParts.push(`+${Math.round(bonusEarned)} bonus`);
+        parts.push(`📈 Earned: ${earningParts.join(', ')}`);
+    }
+    return parts.join('\n');
+}

package/dist/memory/surprisalGate.js

@@ -0,0 +1,119 @@
+/**
+ * Surprisal Gate — Vector-Based Novelty Scoring (v9.0)
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * PURPOSE:
+ *   Computes the information-theoretic "surprisal" of an incoming
+ *   memory entry by measuring its semantic distance from recent entries.
+ *
+ * WHY NOT TF-IDF:
+ *   A naive TF-IDF approach would require downloading all summaries
+ *   into V8 memory and running a custom JS tokenizer. On projects with
+ *   10K+ entries (common after Universal Import), this blocks the
+ *   Node.js event loop for seconds, causing MCP handshake timeouts.
+ *
+ * VECTOR-BASED SURPRISAL:
+ *   Surprisal = 1 - max_similarity_to_recent_entries
+ *
+ *   When the agent tries to save an entry, we embed the summary
+ *   (already happening in the save flow) and query the DB for the
+ *   single most similar entry from the last 7 days.
+ *
+ *   - Similarity 0.95 → Surprisal 0.05 → "You're repeating yourself" → 2× cost
+ *   - Similarity 0.40 → Surprisal 0.60 → "Completely novel thought" → 0.5× cost
+ *
+ *   This uses the existing native sqlite-vec index, takes < 5ms,
+ *   uses zero extra memory, and is far more accurate than word counting.
+ *
+ * FILES THAT IMPORT THIS:
+ *   - src/tools/ledgerHandlers.ts (surprisal computation during save)
+ * ═══════════════════════════════════════════════════════════════════
+ */
+import { debugLog } from "../utils/logger.js";
+// ─── Constants ────────────────────────────────────────────────
+/** Maximum age of entries to compare against (days) */
+export const RECENCY_WINDOW_DAYS = 7;
+/** Number of similar entries to fetch for comparison */
+export const TOP_K = 1;
+/** Similarity above which content is considered boilerplate */
+export const BOILERPLATE_SIMILARITY = 0.80;
+/** Similarity below which content is considered novel */
+export const NOVEL_SIMILARITY = 0.30;
+// ─── Core Computation ─────────────────────────────────────────
+/**
+ * Compute surprisal from a semantic similarity score.
+ *
+ * This is the pure math core — no I/O. The caller is responsible
+ * for running the actual vector search to find maxSimilarity.
+ *
+ * @param maxSimilarity - Cosine similarity to the most similar recent entry (0-1)
+ * @returns SurprisalResult with classification
+ */
+export function computeSurprisal(maxSimilarity) {
+    // Guard: no recent entries found (first entry in project) → maximum novelty
+    if (!Number.isFinite(maxSimilarity) || maxSimilarity < 0) {
+        return {
+            surprisal: 1.0,
+            maxSimilarity: 0.0,
+            isBoilerplate: false,
+            isNovel: true,
+        };
+    }
+    // Clamp to [0, 1]
+    const clamped = Math.min(1.0, Math.max(0.0, maxSimilarity));
+    const surprisal = 1.0 - clamped;
+    return {
+        surprisal,
+        maxSimilarity: clamped,
+        isBoilerplate: clamped >= BOILERPLATE_SIMILARITY,
+        isNovel: clamped <= NOVEL_SIMILARITY,
+    };
+}
+/**
+ * Compute surprisal using the existing storage backend's vector search.
+ *
+ * This is the integration wrapper. It:
+ * 1. Takes the query embedding (already generated for the save flow)
+ * 2. Finds the most similar recent entry via sqlite-vec
+ * 3. Computes surprisal = 1 - max_similarity
+ *
+ * Falls back to surprisal=0.5 (neutral) on any error, to avoid
+ * blocking saves due to search failures.
+ *
+ * @param searchFn - The storage backend's searchMemory function
+ * @param queryEmbedding - JSON-stringified embedding of the new entry
+ * @param project - Project scope
+ * @param userId - Tenant ID
+ * @returns SurprisalResult
+ */
+export async function computeVectorSurprisal(searchFn, queryEmbedding, project, userId) {
+    try {
+        // Search for the single most similar recent entry
+        // Using a very low threshold (0.0) to get the closest match regardless
+        const results = await searchFn({
+            queryEmbedding,
+            project,
+            limit: TOP_K,
+            similarityThreshold: 0.0, // Get closest match regardless of distance
+            userId,
+        });
+        if (results.length === 0) {
+            // No existing entries → fully novel
+            debugLog('[surprisal] No recent entries found — maximum novelty');
+            return computeSurprisal(-1);
+        }
+        const maxSimilarity = results[0].similarity;
+        debugLog(`[surprisal] Max similarity to recent entries: ${maxSimilarity.toFixed(3)}`);
+        return computeSurprisal(maxSimilarity);
+    }
+    catch (err) {
+        // Non-fatal: fall back to neutral surprisal
+        debugLog(`[surprisal] Vector search failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            surprisal: 0.5,
+            maxSimilarity: 0.5,
+            isBoilerplate: false,
+            isNovel: false,
+        };
+    }
+}

package/dist/memory/synapseEngine.js

@@ -107,6 +107,11 @@ export async function propagateActivation(anchors, linkFetcher, config = {}) {
     const hopDistance = new Map();
     // Track visited edges to prevent cyclic re-traversal
     const visitedEdges = new Set();
+    // v9.0: Track energy flow weights for valence propagation
+    // Maps targetId → Array<{ sourceId, weight }> representing which nodes
+    // contributed energy and how much. Used by propagateValence() to compute
+    // energy-weighted average valence for discovered nodes.
+    const flowWeights = new Map();
     // Total edges traversed for telemetry
     let totalEdgesTraversed = 0;
     // Initialize with anchor scores
@@ -120,6 +125,7 @@ export async function propagateActivation(anchors, linkFetcher, config = {}) {
         return {
             results,
             telemetry: buildTelemetry(results, anchors, 0, 0, startMs),
+            flowWeights: new Map(),
         };
     }
     // ─── Propagation Loop ────────────────────────────────────
@@ -138,13 +144,20 @@ export async function propagateActivation(anchors, linkFetcher, config = {}) {
             break;
         }
         totalEdgesTraversed += edges.length;
-        // Compute out-degree per active source node (for fan effect)
+        // Compute out-degree per active source node (for forward fan effect)
         const outDegree = new Map();
         for (const edge of edges) {
             if (activeNodes.has(edge.source_id)) {
                 outDegree.set(edge.source_id, (outDegree.get(edge.source_id) || 0) + 1);
             }
         }
+        // Compute in-degree per active target node (for backward fan effect)
+        const inDegree = new Map();
+        for (const edge of edges) {
+            if (activeNodes.has(edge.target_id)) {
+                inDegree.set(edge.target_id, (inDegree.get(edge.target_id) || 0) + 1);
+            }
+        }
         // Next-iteration activation: starts with current values (activation persists)
         const nextNodes = new Map(activeNodes);
         for (const edge of edges) {
@@ -159,6 +172,10 @@ export async function propagateActivation(anchors, linkFetcher, config = {}) {
                 const dampedFan = Math.log(degree + Math.E);
                 const flow = cfg.spreadFactor * (strength * sourceEnergy / dampedFan);
                 nextNodes.set(edge.target_id, (nextNodes.get(edge.target_id) || 0) + flow);
+                // v9.0: Record flow for valence propagation
+                if (!flowWeights.has(edge.target_id))
+                    flowWeights.set(edge.target_id, []);
+                flowWeights.get(edge.target_id).push({ sourceId: edge.source_id, weight: flow });
                 // Track hop distance (minimum)
                 const sourceHops = hopDistance.get(edge.source_id) ?? 0;
                 const currentTargetHops = hopDistance.get(edge.target_id);
@@ -171,8 +188,16 @@ export async function propagateActivation(anchors, linkFetcher, config = {}) {
             if (activeNodes.has(edge.target_id) && !visitedEdges.has(reverseEdgeKey)) {
                 visitedEdges.add(reverseEdgeKey);
                 const targetEnergy = activeNodes.get(edge.target_id);
-                const flow = (cfg.spreadFactor * 0.5) * (strength * targetEnergy);
+                // Dampened fan effect for backward flow: prevents hub nodes with many
+                // inbound edges from blasting energy to all sources equally.
+                const inDegreeCount = inDegree.get(edge.target_id) || 1;
+                const dampedFanBack = Math.log(inDegreeCount + Math.E);
+                const flow = (cfg.spreadFactor * 0.5) * (strength * targetEnergy / dampedFanBack);
                 nextNodes.set(edge.source_id, (nextNodes.get(edge.source_id) || 0) + flow);
+                // v9.0: Record backward flow for valence propagation
+                if (!flowWeights.has(edge.source_id))
+                    flowWeights.set(edge.source_id, []);
+                flowWeights.get(edge.source_id).push({ sourceId: edge.target_id, weight: flow });
                 // Track hop distance for backward discoveries
                 const targetHops = hopDistance.get(edge.target_id) ?? 0;
                 const currentSourceHops = hopDistance.get(edge.source_id);
@@ -190,6 +215,7 @@ export async function propagateActivation(anchors, linkFetcher, config = {}) {
     return {
         results,
         telemetry: buildTelemetry(results, anchors, cfg.iterations, totalEdgesTraversed, startMs),
+        flowWeights,
     };
 }
 // ─── Helpers ──────────────────────────────────────────────────