@soleri/core 2.1.0 → 2.5.0

package/src/brain/brain.ts

@@ -17,6 +17,9 @@ import type {
   CaptureResult,
   BrainStats,
   QueryContext,
+  FeedbackInput,
+  FeedbackEntry,
+  FeedbackStats,
 } from './types.js';
 
 // Re-export types for backward compatibility
@@ -44,7 +47,7 @@ const DEFAULT_WEIGHTS: ScoringWeights = {
   semantic: 0.4,
   vector: 0.0,
   severity: 0.15,
-  recency: 0.15,
+  temporalDecay: 0.15,
   tagOverlap: 0.15,
   domainMatch: 0.15,
 };
@@ -53,7 +56,7 @@ const COGNEE_WEIGHTS: ScoringWeights = {
   semantic: 0.25,
   vector: 0.35,
   severity: 0.1,
-  recency: 0.1,
+  temporalDecay: 0.1,
   tagOverlap: 0.1,
   domainMatch: 0.1,
 };
@@ -268,14 +271,109 @@ export class Brain {
     return result;
   }
 
-  recordFeedback(query: string, entryId: string, action: 'accepted' | 'dismissed'): void {
+  recordFeedback(query: string, entryId: string, action: 'accepted' | 'dismissed'): void;
+  recordFeedback(input: FeedbackInput): FeedbackEntry;
+  recordFeedback(
+    queryOrInput: string | FeedbackInput,
+    entryId?: string,
+    action?: 'accepted' | 'dismissed',
+  ): void | FeedbackEntry {
     const db = this.vault.getDb();
-    db.prepare('INSERT INTO brain_feedback (query, entry_id, action) VALUES (?, ?, ?)').run(
-      query,
-      entryId,
-      action,
+
+    // Normalize to FeedbackInput
+    const input: FeedbackInput =
+      typeof queryOrInput === 'string'
+        ? { query: queryOrInput, entryId: entryId!, action: action! }
+        : queryOrInput;
+
+    db.prepare(
+      `INSERT INTO brain_feedback (query, entry_id, action, source, confidence, duration, context, reason)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      input.query,
+      input.entryId,
+      input.action,
+      input.source ?? 'search',
+      input.confidence ?? 0.6,
+      input.duration ?? null,
+      input.context ?? '{}',
+      input.reason ?? null,
     );
     this.recomputeWeights();
+
+    // Return FeedbackEntry only for the object overload
+    if (typeof queryOrInput !== 'string') {
+      const row = db
+        .prepare(
+          'SELECT * FROM brain_feedback WHERE query = ? AND entry_id = ? ORDER BY id DESC LIMIT 1',
+        )
+        .get(input.query, input.entryId) as {
+        id: number;
+        query: string;
+        entry_id: string;
+        action: string;
+        source: string;
+        confidence: number;
+        duration: number | null;
+        context: string;
+        reason: string | null;
+        created_at: number;
+      };
+      return {
+        id: row.id,
+        query: row.query,
+        entryId: row.entry_id,
+        action: row.action as FeedbackEntry['action'],
+        source: row.source as FeedbackEntry['source'],
+        confidence: row.confidence,
+        duration: row.duration,
+        context: row.context,
+        reason: row.reason,
+        createdAt: row.created_at,
+      };
+    }
+  }
+
+  getFeedbackStats(): FeedbackStats {
+    const db = this.vault.getDb();
+
+    const total = (
+      db.prepare('SELECT COUNT(*) as count FROM brain_feedback').get() as { count: number }
+    ).count;
+
+    const byAction: Record<string, number> = {};
+    const actionRows = db
+      .prepare('SELECT action, COUNT(*) as count FROM brain_feedback GROUP BY action')
+      .all() as Array<{ action: string; count: number }>;
+    for (const row of actionRows) {
+      byAction[row.action] = row.count;
+    }
+
+    const bySource: Record<string, number> = {};
+    const sourceRows = db
+      .prepare('SELECT source, COUNT(*) as count FROM brain_feedback GROUP BY source')
+      .all() as Array<{ source: string; count: number }>;
+    for (const row of sourceRows) {
+      bySource[row.source] = row.count;
+    }
+
+    const accepted = byAction['accepted'] ?? 0;
+    const acceptanceRate = total > 0 ? accepted / total : 0;
+
+    const avgConf =
+      (
+        db.prepare('SELECT AVG(confidence) as avg FROM brain_feedback').get() as {
+          avg: number | null;
+        }
+      ).avg ?? 0;
+
+    return {
+      total,
+      byAction,
+      bySource,
+      acceptanceRate,
+      averageConfidence: avgConf,
+    };
   }
 
   async getRelevantPatterns(context: QueryContext): Promise<RankedResult[]> {
@@ -356,6 +454,42 @@ export class Brain {
     return this.vocabulary.size;
   }
 
+  async getDecayReport(
+    query: string,
+    limit: number = 10,
+  ): Promise<
+    Array<{
+      id: string;
+      title: string;
+      decayScore: number;
+      validUntil: number | null;
+      status: 'active' | 'expiring' | 'expired';
+    }>
+  > {
+    const results = await this.intelligentSearch(query, { limit });
+    const now = Math.floor(Date.now() / 1000);
+    return results.map((r) => {
+      const validUntil = r.entry.validUntil ?? null;
+      let status: 'active' | 'expiring' | 'expired' = 'active';
+      if (validUntil) {
+        if (validUntil <= now) status = 'expired';
+        else {
+          const validFrom = r.entry.validFrom ?? now;
+          const totalWindow = validUntil - validFrom;
+          const remaining = validUntil - now;
+          if (remaining <= totalWindow * 0.25) status = 'expiring';
+        }
+      }
+      return {
+        id: r.entry.id,
+        title: r.entry.title,
+        decayScore: r.breakdown.temporalDecay,
+        validUntil,
+        status,
+      };
+    });
+  }
+
   // ─── Private methods ─────────────────────────────────────────────
 
   private scoreEntry(
@@ -385,9 +519,7 @@ export class Brain {
 
     const severity = SEVERITY_SCORES[entry.severity] ?? 0.4;
 
-    const entryAge = now - (entry as unknown as { created_at?: number }).created_at!;
-    const halfLifeSeconds = RECENCY_HALF_LIFE_DAYS * 86400;
-    const recency = entryAge > 0 ? Math.exp((-Math.LN2 * entryAge) / halfLifeSeconds) : 1;
+    const temporalDecay = computeTemporalDecay(entry, now);
 
     const tagOverlap = queryTags.length > 0 ? jaccardSimilarity(queryTags, entry.tags) : 0;
 
@@ -399,11 +531,11 @@ export class Brain {
       w.semantic * semantic +
       w.vector * vector +
       w.severity * severity +
-      w.recency * recency +
+      w.temporalDecay * temporalDecay +
       w.tagOverlap * tagOverlap +
       w.domainMatch * domainMatch;
 
-    return { semantic, vector, severity, recency, tagOverlap, domainMatch, total };
+    return { semantic, vector, severity, temporalDecay, tagOverlap, domainMatch, total };
   }
 
   private generateTags(title: string, description: string, context?: string): string[] {
@@ -503,8 +635,11 @@ export class Brain {
 
   private recomputeWeights(): void {
     const db = this.vault.getDb();
+    // Exclude 'failed' from weight computation — system errors don't indicate relevance
     const feedbackCount = (
-      db.prepare('SELECT COUNT(*) as count FROM brain_feedback').get() as { count: number }
+      db.prepare("SELECT COUNT(*) as count FROM brain_feedback WHERE action != 'failed'").get() as {
+        count: number;
+      }
     ).count;
     if (feedbackCount < FEEDBACK_THRESHOLD) {
       this.weights = { ...DEFAULT_WEIGHTS };
@@ -516,7 +651,13 @@ export class Brain {
         .prepare("SELECT COUNT(*) as count FROM brain_feedback WHERE action = 'accepted'")
         .get() as { count: number }
     ).count;
-    const acceptRate = feedbackCount > 0 ? accepted / feedbackCount : 0.5;
+    // 'modified' counts as 0.5 positive — user adjusted but didn't dismiss
+    const modified = (
+      db
+        .prepare("SELECT COUNT(*) as count FROM brain_feedback WHERE action = 'modified'")
+        .get() as { count: number }
+    ).count;
+    const acceptRate = feedbackCount > 0 ? (accepted + modified * 0.5) / feedbackCount : 0.5;
 
     const semanticDelta = (acceptRate - 0.5) * WEIGHT_BOUND * 2;
 
@@ -533,12 +674,12 @@ export class Brain {
     const remaining = 1.0 - newWeights.semantic - newWeights.vector;
     const otherSum =
       DEFAULT_WEIGHTS.severity +
-      DEFAULT_WEIGHTS.recency +
+      DEFAULT_WEIGHTS.temporalDecay +
       DEFAULT_WEIGHTS.tagOverlap +
       DEFAULT_WEIGHTS.domainMatch;
     const scale = remaining / otherSum;
     newWeights.severity = DEFAULT_WEIGHTS.severity * scale;
-    newWeights.recency = DEFAULT_WEIGHTS.recency * scale;
+    newWeights.temporalDecay = DEFAULT_WEIGHTS.temporalDecay * scale;
     newWeights.tagOverlap = DEFAULT_WEIGHTS.tagOverlap * scale;
     newWeights.domainMatch = DEFAULT_WEIGHTS.domainMatch * scale;
 
@@ -546,6 +687,34 @@ export class Brain {
   }
 }
 
+function computeTemporalDecay(entry: IntelligenceEntry, now: number): number {
+  const entryRecord = entry as unknown as {
+    created_at?: number;
+    updated_at?: number;
+    valid_until?: number;
+    valid_from?: number;
+  };
+  const validUntil = entry.validUntil ?? entryRecord.valid_until;
+
+  if (!validUntil) {
+    // No expiry — use existing age-based exponential decay
+    const updatedAt = entryRecord.updated_at ?? entryRecord.created_at ?? now;
+    const ageSeconds = now - updatedAt;
+    const halfLifeSeconds = RECENCY_HALF_LIFE_DAYS * 86400;
+    return ageSeconds > 0 ? Math.exp((-Math.LN2 * ageSeconds) / halfLifeSeconds) : 1;
+  }
+
+  // With valid_until: linear ramp-down in last 25% of validity window
+  const validFrom = entry.validFrom ?? entryRecord.valid_from ?? entryRecord.created_at ?? now;
+  const totalWindow = validUntil - validFrom;
+  const remaining = validUntil - now;
+  if (remaining <= 0) return 0; // expired
+  if (totalWindow <= 0) return 1; // edge case: bad data
+  const decayZone = totalWindow * 0.25;
+  if (remaining > decayZone) return 1.0; // fully valid
+  return remaining / decayZone; // linear decay in last quarter
+}
+
 function clamp(value: number, min: number, max: number): number {
   return Math.max(min, Math.min(max, value));
 }

package/src/brain/intelligence.ts

@@ -77,7 +77,8 @@ export class BrainIntelligence {
         tools_used TEXT NOT NULL DEFAULT '[]',
         files_modified TEXT NOT NULL DEFAULT '[]',
         plan_id TEXT,
-        plan_outcome TEXT
+        plan_outcome TEXT,
+        extracted_at TEXT
       );
 
       CREATE TABLE IF NOT EXISTS brain_proposals (
@@ -161,9 +162,34 @@ export class BrainIntelligence {
     values.push(sessionId);
     db.prepare(`UPDATE brain_sessions SET ${updates.join(', ')} WHERE id = ?`).run(...values);
 
+    // Auto-extract knowledge if session has enough signal
+    this.autoExtractIfReady(this.getSession(sessionId)!);
+
+    // Return fresh session (extractedAt may have been set by auto-extract)
     return this.getSession(sessionId)!;
   }
 
+  /**
+   * Attempt auto-extraction after session end if the session has enough signal.
+   * Gate: at least 1 tool used OR 1 file modified OR a plan was associated.
+   * Silently skips if already extracted or insufficient data.
+   */
+  private autoExtractIfReady(session: BrainSession): void {
+    if (!session.endedAt) return;
+    if (session.extractedAt) return;
+
+    const hasSignal =
+      session.toolsUsed.length > 0 || session.filesModified.length > 0 || session.planId !== null;
+
+    if (!hasSignal) return;
+
+    try {
+      this.extractKnowledge(session.id);
+    } catch {
+      // Non-critical — don't break session end
+    }
+  }
+
   getSessionContext(limit = 10): SessionContext {
     const db = this.vault.getDb();
 
@@ -179,6 +205,7 @@ export class BrainIntelligence {
       files_modified: string;
       plan_id: string | null;
       plan_outcome: string | null;
+      extracted_at: string | null;
     }>;
 
     const sessions = rows.map((r) => this.rowToSession(r));
@@ -230,6 +257,8 @@ export class BrainIntelligence {
                 COUNT(*) as total,
                 SUM(CASE WHEN action = 'accepted' THEN 1 ELSE 0 END) as accepted,
                 SUM(CASE WHEN action = 'dismissed' THEN 1 ELSE 0 END) as dismissed,
+                SUM(CASE WHEN action = 'modified' THEN 1 ELSE 0 END) as modified,
+                SUM(CASE WHEN action = 'failed' THEN 1 ELSE 0 END) as failed,
                 MAX(created_at) as last_used
          FROM brain_feedback
          GROUP BY entry_id`,
@@ -239,6 +268,8 @@ export class BrainIntelligence {
       total: number;
       accepted: number;
       dismissed: number;
+      modified: number;
+      failed: number;
       last_used: string;
     }>;
 
@@ -265,7 +296,10 @@ export class BrainIntelligence {
       const spreadScore = Math.min(25, (uniqueContexts / SPREAD_MAX) * 25);
 
       // Success score: 25 * successRate
-      const successRate = row.total > 0 ? row.accepted / row.total : 0;
+      // modified = 0.5 positive, failed = excluded (system error, not relevance)
+      const relevantTotal = row.total - row.failed;
+      const successRate =
+        relevantTotal > 0 ? (row.accepted + row.modified * 0.5) / relevantTotal : 0;
       const successScore = 25 * successRate;
 
       // Recency score: max(0, 25 * (1 - daysSince / RECENCY_DECAY_DAYS))
@@ -364,12 +398,17 @@ export class BrainIntelligence {
     }));
   }
 
-  recommend(context: { domain?: string; task?: string; limit?: number }): PatternStrength[] {
+  recommend(context: {
+    domain?: string;
+    task?: string;
+    source?: string;
+    limit?: number;
+  }): PatternStrength[] {
     const limit = context.limit ?? 5;
     const strengths = this.getStrengths({
       domain: context.domain,
       minStrength: 30,
-      limit: limit * 2,
+      limit: limit * 3,
     });
 
     // If task context provided, boost patterns with matching terms
@@ -383,9 +422,36 @@ export class BrainIntelligence {
           (s as { strength: number }).strength += overlap * 5;
         }
       }
-      strengths.sort((a, b) => b.strength - a.strength);
     }
 
+    // Boost patterns with high source-specific acceptance rates
+    if (context.source) {
+      const db = this.vault.getDb();
+      for (const s of strengths) {
+        const row = db
+          .prepare(
+            `SELECT COUNT(*) as total,
+                    SUM(CASE WHEN action = 'accepted' THEN 1 ELSE 0 END) as accepted,
+                    SUM(CASE WHEN action = 'modified' THEN 1 ELSE 0 END) as modified
+             FROM brain_feedback
+             WHERE entry_id = (SELECT id FROM entries WHERE title = ? LIMIT 1)
+               AND source = ?`,
+          )
+          .get(s.pattern, context.source) as {
+          total: number;
+          accepted: number;
+          modified: number;
+        };
+
+        if (row.total >= 3) {
+          const sourceRate = (row.accepted + row.modified * 0.5) / row.total;
+          // Boost up to +10 points for high source-specific acceptance
+          (s as { strength: number }).strength += sourceRate * 10;
+        }
+      }
+    }
+
+    strengths.sort((a, b) => b.strength - a.strength);
     return strengths.slice(0, limit);
   }
 
@@ -510,6 +576,11 @@ export class BrainIntelligence {
       }
     }
 
+    // Mark session as extracted
+    db.prepare("UPDATE brain_sessions SET extracted_at = datetime('now') WHERE id = ?").run(
+      sessionId,
+    );
+
     return {
       sessionId,
       proposals,
@@ -517,6 +588,37 @@ export class BrainIntelligence {
     };
   }
 
+  resetExtracted(options?: { sessionId?: string; since?: string; all?: boolean }): {
+    reset: number;
+  } {
+    const db = this.vault.getDb();
+
+    if (options?.sessionId) {
+      const info = db
+        .prepare(
+          'UPDATE brain_sessions SET extracted_at = NULL WHERE id = ? AND extracted_at IS NOT NULL',
+        )
+        .run(options.sessionId);
+      return { reset: info.changes };
+    }
+
+    if (options?.since) {
+      const info = db
+        .prepare('UPDATE brain_sessions SET extracted_at = NULL WHERE extracted_at >= ?')
+        .run(options.since);
+      return { reset: info.changes };
+    }
+
+    if (options?.all) {
+      const info = db
+        .prepare('UPDATE brain_sessions SET extracted_at = NULL WHERE extracted_at IS NOT NULL')
+        .run();
+      return { reset: info.changes };
+    }
+
+    return { reset: 0 };
+  }
+
   getProposals(options?: {
     sessionId?: string;
     promoted?: boolean;
@@ -556,10 +658,36 @@ export class BrainIntelligence {
     return rows.map((r) => this.rowToProposal(r));
   }
 
-  promoteProposals(proposalIds: string[]): { promoted: number; failed: string[] } {
+  promoteProposals(
+    proposalIds: string[],
+    governanceGate?: {
+      evaluateCapture: (
+        projectPath: string,
+        entry: { type: string; category: string; title?: string },
+      ) => { action: string; reason?: string };
+      propose: (
+        projectPath: string,
+        entryData: {
+          entryId?: string;
+          title: string;
+          type: string;
+          category: string;
+          data?: Record<string, unknown>;
+        },
+        source?: string,
+      ) => number;
+    },
+    projectPath?: string,
+  ): {
+    promoted: number;
+    failed: string[];
+    gated: Array<{ id: string; action: string; reason?: string }>;
+  } {
     const db = this.vault.getDb();
     let promoted = 0;
     const failed: string[] = [];
+    const gated: Array<{ id: string; action: string; reason?: string }> = [];
+    const pp = projectPath ?? '.';
 
     for (const id of proposalIds) {
       const row = db.prepare('SELECT * FROM brain_proposals WHERE id = ?').get(id) as
@@ -583,10 +711,46 @@ export class BrainIntelligence {
 
       if (row.promoted) continue; // Already promoted
 
-      // Add to vault as intelligence entry — map workflow to pattern since vault only accepts pattern/anti-pattern/rule
+      // Map type for vault
       const rawType = row.type;
       const vaultType: 'pattern' | 'anti-pattern' | 'rule' =
         rawType === 'anti-pattern' ? 'anti-pattern' : 'pattern';
+
+      // Governance gate (when provided)
+      if (governanceGate) {
+        const decision = governanceGate.evaluateCapture(pp, {
+          type: vaultType,
+          category: 'brain-intelligence',
+          title: row.title,
+        });
+
+        if (decision.action === 'propose') {
+          governanceGate.propose(
+            pp,
+            {
+              entryId: `proposal-${id}`,
+              title: row.title,
+              type: vaultType,
+              category: 'brain-intelligence',
+              data: {
+                severity: 'suggestion',
+                description: row.description,
+                tags: ['auto-extracted', row.rule],
+              },
+            },
+            'brain-promote',
+          );
+          gated.push({ id, action: 'propose', reason: decision.reason });
+          continue;
+        }
+
+        if (decision.action !== 'capture') {
+          gated.push({ id, action: decision.action, reason: decision.reason });
+          continue;
+        }
+      }
+
+      // Capture into vault
       this.brain.enrichAndCapture({
         id: `proposal-${id}`,
         type: vaultType,
@@ -601,7 +765,7 @@ export class BrainIntelligence {
       promoted++;
     }
 
-    return { promoted, failed };
+    return { promoted, failed, gated };
   }
 
   // ─── Intelligence Pipeline ────────────────────────────────────────
@@ -725,6 +889,7 @@ export class BrainIntelligence {
       files_modified: string;
       plan_id: string | null;
       plan_outcome: string | null;
+      extracted_at: string | null;
     }>;
     const sessions = sessionRows.map((r) => this.rowToSession(r));
 
@@ -790,8 +955,8 @@ export class BrainIntelligence {
       // Import sessions
       const insertSession = db.prepare(
         `INSERT OR IGNORE INTO brain_sessions
-         (id, started_at, ended_at, domain, context, tools_used, files_modified, plan_id, plan_outcome)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+         (id, started_at, ended_at, domain, context, tools_used, files_modified, plan_id, plan_outcome, extracted_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       );
       for (const s of data.sessions) {
         const changes = insertSession.run(
@@ -804,6 +969,7 @@ export class BrainIntelligence {
           JSON.stringify(s.filesModified),
           s.planId,
           s.planOutcome,
+          s.extractedAt ?? null,
         );
         if (changes.changes > 0) result.imported.sessions++;
       }
@@ -883,6 +1049,7 @@ export class BrainIntelligence {
           files_modified: string;
           plan_id: string | null;
           plan_outcome: string | null;
+          extracted_at: string | null;
         }
       | undefined;
 
@@ -900,6 +1067,7 @@ export class BrainIntelligence {
     files_modified: string;
     plan_id: string | null;
     plan_outcome: string | null;
+    extracted_at: string | null;
   }): BrainSession {
     return {
       id: row.id,
@@ -911,6 +1079,7 @@ export class BrainIntelligence {
       filesModified: JSON.parse(row.files_modified) as string[],
       planId: row.plan_id,
       planOutcome: row.plan_outcome,
+      extractedAt: row.extracted_at,
     };
   }
 

package/src/brain/types.ts

@@ -6,7 +6,7 @@ export interface ScoringWeights {
   semantic: number;
   vector: number;
   severity: number;
-  recency: number;
+  temporalDecay: number;
   tagOverlap: number;
   domainMatch: number;
 }
@@ -15,7 +15,7 @@ export interface ScoreBreakdown {
   semantic: number;
   vector: number;
   severity: number;
-  recency: number;
+  temporalDecay: number;
   tagOverlap: number;
   domainMatch: number;
   total: number;
@@ -55,6 +55,43 @@ export interface QueryContext {
   tags?: string[];
 }
 
+// ─── Feedback Types ───────────────────────────────────────────────
+
+export type FeedbackType = 'accepted' | 'dismissed' | 'modified' | 'failed';
+export type FeedbackSource = 'search' | 'recommendation' | 'tool-execution' | 'explicit';
+
+export interface FeedbackInput {
+  query: string;
+  entryId: string;
+  action: FeedbackType;
+  source?: FeedbackSource;
+  confidence?: number;
+  duration?: number;
+  context?: string;
+  reason?: string;
+}
+
+export interface FeedbackEntry {
+  id: number;
+  query: string;
+  entryId: string;
+  action: FeedbackType;
+  source: FeedbackSource;
+  confidence: number;
+  duration: number | null;
+  context: string;
+  reason: string | null;
+  createdAt: number;
+}
+
+export interface FeedbackStats {
+  total: number;
+  byAction: Record<string, number>;
+  bySource: Record<string, number>;
+  acceptanceRate: number;
+  averageConfidence: number;
+}
+
 // ─── Brain Intelligence Types ──────────────────────────────────────
 
 export interface PatternStrength {
@@ -87,6 +124,7 @@ export interface BrainSession {
   filesModified: string[];
   planId: string | null;
   planOutcome: string | null;
+  extractedAt: string | null;
 }
 
 export interface SessionLifecycleInput {