shieldcortex 4.24.2 → 4.25.0

package/scripts/lib/extract-memorable-segments.mjs

@@ -23,6 +23,37 @@ export const BASE_THRESHOLD = 0.35;
 // trust band (0.5–0.7) used elsewhere in the pipeline.
 export const AUTO_EXTRACT_SALIENCE_CAP = 0.6;
 
+// v4.25.0: deterministic taxonomy. The extractor already knows *why* a
+// segment matched (extractorType) — derive memory_purpose and category
+// from that signal instead of re-scanning the captured text. Keyword-
+// based suggestCategory() stays as a fallback for any extractorType not
+// in the map (defensive, not currently used by any in-tree extractor).
+//
+// memory_purpose follows the global taxonomy (src/memory/types.ts):
+//   user      — who the human is
+//   feedback  — corrections / instructions the human gave the agent
+//   project   — facts about the project (decisions, architecture, fixes)
+//   reference — reusable knowledge (learnings, external references)
+export const EXTRACTOR_TO_PURPOSE = {
+  preference: 'feedback',
+  decision: 'project',
+  architecture: 'project',
+  'error-fix': 'project',
+  learning: 'reference',
+  'important-note': 'project',
+};
+
+// Pinning category by extractorType eliminates the "important-note tagged
+// as 'error' because the text mentioned a bug" failure mode.
+export const EXTRACTOR_TO_CATEGORY = {
+  preference: 'preference',
+  decision: 'context',
+  architecture: 'architecture',
+  'error-fix': 'error',
+  learning: 'learning',
+  'important-note': 'note',
+};
+
 // Default category thresholds (session-end / lighter hooks).
 // Pre-compact hook uses tighter thresholds (raised +0.10 in v4.11.0) and
 // passes them via processSegments({ categoryThresholds: ... }).
@@ -222,73 +253,82 @@ export function getExtractionThreshold(category, dynamicThreshold, categoryThres
 }
 
 // ==================== EXTRACTOR DEFINITIONS ====================
-
-const FULL_EXTRACTORS = [
+//
+// All capture groups use `[^.!?\n]{N,M}[.!?]?` instead of `.{N,M}`. The
+// previous fixed-character-window form (`.{15,200}`) sliced clauses at
+// arbitrary offsets, producing memories like
+//   "Decision: python3 /home/ubuntu/clawd/scripts/beautyhair_colo..."
+// where the regex grabbed 150 chars after the keyword regardless of where
+// the sentence ended. The new form stops at the first `.`, `!`, `?`, or
+// newline, capping at 200 chars for safety, and optionally consumes the
+// terminator so the captured group ends cleanly. v4.24.3.
+
+export const FULL_EXTRACTORS = [
   {
     name: 'decision',
     titlePrefix: 'Decision: ',
     patterns: [
-      /(?:we\s+)?decided\s+(?:to\s+)?(.{15,200})/gi,
-      /(?:going|went)\s+with\s+(.{15,150})/gi,
-      /(?:chose|chosen|selected)\s+(.{15,150})/gi,
-      /the\s+(?:approach|solution|fix)\s+(?:is|was)\s+(.{15,200})/gi,
-      /(?:using|will\s+use)\s+(.{15,150})/gi,
-      /(?:opted\s+for|settled\s+on)\s+(.{15,150})/gi,
+      /(?:we\s+)?decided\s+(?:to\s+)?([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:going|went)\s+with\s+([^.!?\n]{15,150}[.!?]?)/gi,
+      /(?:chose|chosen|selected)\s+([^.!?\n]{15,150}[.!?]?)/gi,
+      /the\s+(?:approach|solution|fix)\s+(?:is|was)\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:using|will\s+use)\s+([^.!?\n]{15,150}[.!?]?)/gi,
+      /(?:opted\s+for|settled\s+on)\s+([^.!?\n]{15,150}[.!?]?)/gi,
     ],
   },
   {
     name: 'error-fix',
     titlePrefix: 'Fix: ',
     patterns: [
-      /(?:fixed|solved|resolved)\s+(?:by\s+)?(.{15,200})/gi,
-      /the\s+(?:fix|solution|workaround)\s+(?:is|was)\s+(.{15,200})/gi,
-      /(?:root\s+cause|issue)\s+(?:is|was)\s+(.{15,200})/gi,
-      /(?:error|bug)\s+(?:was\s+)?caused\s+by\s+(.{15,200})/gi,
-      /(?:problem|issue)\s+was\s+(.{15,150})/gi,
-      /(?:the\s+)?bug\s+(?:is|was)\s+(.{15,150})/gi,
-      /(?:debugging|debugged)\s+(.{15,150})/gi,
+      /(?:fixed|solved|resolved)\s+(?:by\s+)?([^.!?\n]{15,200}[.!?]?)/gi,
+      /the\s+(?:fix|solution|workaround)\s+(?:is|was)\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:root\s+cause|issue)\s+(?:is|was)\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:error|bug)\s+(?:was\s+)?caused\s+by\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:problem|issue)\s+was\s+([^.!?\n]{15,150}[.!?]?)/gi,
+      /(?:the\s+)?bug\s+(?:is|was)\s+([^.!?\n]{15,150}[.!?]?)/gi,
+      /(?:debugging|debugged)\s+([^.!?\n]{15,150}[.!?]?)/gi,
     ],
   },
   {
     name: 'learning',
     titlePrefix: 'Learned: ',
     patterns: [
-      /(?:learned|discovered|realized|found\s+out)\s+(?:that\s+)?(.{15,200})/gi,
-      /turns\s+out\s+(?:that\s+)?(.{15,200})/gi,
-      /(?:TIL|today\s+I\s+learned)[:\s]+(.{15,200})/gi,
-      /(?:now\s+)?(?:understand|know)\s+(?:that\s+)?(.{15,150})/gi,
-      /(?:figured\s+out|worked\s+out)\s+(.{15,150})/gi,
+      /(?:learned|discovered|realized|found\s+out)\s+(?:that\s+)?([^.!?\n]{15,200}[.!?]?)/gi,
+      /turns\s+out\s+(?:that\s+)?([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:TIL|today\s+I\s+learned)[:\s]+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:now\s+)?(?:understand|know)\s+(?:that\s+)?([^.!?\n]{15,150}[.!?]?)/gi,
+      /(?:figured\s+out|worked\s+out)\s+([^.!?\n]{15,150}[.!?]?)/gi,
     ],
   },
   {
     name: 'architecture',
     titlePrefix: 'Architecture: ',
     patterns: [
-      /the\s+architecture\s+(?:is|uses|consists\s+of)\s+(.{15,200})/gi,
-      /(?:design|pattern)\s+(?:is|uses)\s+(.{15,200})/gi,
-      /(?:system|api|database)\s+(?:structure|design)\s+(?:is|uses)\s+(.{15,200})/gi,
-      /(?:created|added|implemented|built)\s+(?:a\s+)?(.{15,200})/gi,
-      /(?:refactored|updated|changed)\s+(?:the\s+)?(.{15,150})/gi,
+      /the\s+architecture\s+(?:is|uses|consists\s+of)\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:design|pattern)\s+(?:is|uses)\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:system|api|database)\s+(?:structure|design)\s+(?:is|uses)\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:created|added|implemented|built)\s+(?:a\s+)?([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:refactored|updated|changed)\s+(?:the\s+)?([^.!?\n]{15,150}[.!?]?)/gi,
     ],
   },
   {
     name: 'preference',
     titlePrefix: 'Preference: ',
     patterns: [
-      /(?:always|never)\s+(.{10,150})/gi,
-      /(?:prefer|want)\s+to\s+(.{10,150})/gi,
-      /(?:should|must)\s+(?:always\s+)?(.{10,150})/gi,
+      /(?:always|never)\s+([^.!?\n]{10,150}[.!?]?)/gi,
+      /(?:prefer|want)\s+to\s+([^.!?\n]{10,150}[.!?]?)/gi,
+      /(?:should|must)\s+(?:always\s+)?([^.!?\n]{10,150}[.!?]?)/gi,
     ],
   },
   {
     name: 'important-note',
     titlePrefix: 'Note: ',
     patterns: [
-      /important[:\s]+(.{15,200})/gi,
-      /(?:note|remember)[:\s]+(.{15,200})/gi,
-      /(?:key|critical)\s+(?:point|thing)[:\s]+(.{15,200})/gi,
-      /(?:this\s+is\s+)?(?:crucial|essential)[:\s]+(.{15,150})/gi,
-      /(?:don't\s+forget|keep\s+in\s+mind)[:\s]+(.{15,150})/gi,
+      /important[:\s]+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:note|remember)[:\s]+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:key|critical)\s+(?:point|thing)[:\s]+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:this\s+is\s+)?(?:crucial|essential)[:\s]+([^.!?\n]{15,150}[.!?]?)/gi,
+      /(?:don't\s+forget|keep\s+in\s+mind)[:\s]+([^.!?\n]{15,150}[.!?]?)/gi,
     ],
   },
 ];
@@ -296,37 +336,76 @@ const FULL_EXTRACTORS = [
 // stop-hook historically used a thinner extractor set (no architecture,
 // no important-note, fewer learning + preference patterns). Preserve the
 // pre-refactor surface so its behaviour does not change with this move.
-const STOP_HOOK_EXTRACTORS = [
+// Same sentence-bounded capture form as FULL_EXTRACTORS (v4.24.3).
+export const STOP_HOOK_EXTRACTORS = [
   FULL_EXTRACTORS[0], // decision
   {
     name: 'error-fix',
     titlePrefix: 'Fix: ',
     patterns: [
-      /(?:fixed|solved|resolved)\s+(?:by\s+)?(.{15,200})/gi,
-      /the\s+(?:fix|solution|workaround)\s+(?:is|was)\s+(.{15,200})/gi,
-      /(?:root\s+cause|issue)\s+(?:is|was)\s+(.{15,200})/gi,
-      /(?:error|bug)\s+(?:was\s+)?caused\s+by\s+(.{15,200})/gi,
+      /(?:fixed|solved|resolved)\s+(?:by\s+)?([^.!?\n]{15,200}[.!?]?)/gi,
+      /the\s+(?:fix|solution|workaround)\s+(?:is|was)\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:root\s+cause|issue)\s+(?:is|was)\s+([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:error|bug)\s+(?:was\s+)?caused\s+by\s+([^.!?\n]{15,200}[.!?]?)/gi,
     ],
   },
   {
     name: 'learning',
     titlePrefix: 'Learned: ',
     patterns: [
-      /(?:learned|discovered|realized|found\s+out)\s+(?:that\s+)?(.{15,200})/gi,
-      /turns\s+out\s+(?:that\s+)?(.{15,200})/gi,
-      /(?:figured\s+out|worked\s+out)\s+(.{15,150})/gi,
+      /(?:learned|discovered|realized|found\s+out)\s+(?:that\s+)?([^.!?\n]{15,200}[.!?]?)/gi,
+      /turns\s+out\s+(?:that\s+)?([^.!?\n]{15,200}[.!?]?)/gi,
+      /(?:figured\s+out|worked\s+out)\s+([^.!?\n]{15,150}[.!?]?)/gi,
     ],
   },
   {
     name: 'preference',
     titlePrefix: 'Preference: ',
     patterns: [
-      /(?:always|never)\s+(.{10,150})/gi,
-      /(?:prefer|want)\s+to\s+(.{10,150})/gi,
+      /(?:always|never)\s+([^.!?\n]{10,150}[.!?]?)/gi,
+      /(?:prefer|want)\s+to\s+([^.!?\n]{10,150}[.!?]?)/gi,
     ],
   },
 ];
 
+/**
+ * Defensive JSON-escape unescape. Some upstream paths re-emit
+ * conversation text after a stringify/parse round-trip without unescaping
+ * the inner string, so literal `\n` / `\t` / `\r` sequences leak through
+ * into matched segments. This fixes the most common leaks idempotently —
+ * sequences that are already real newlines / tabs / carriage returns are
+ * different characters from the literal 2-char `\n` / `\t` / `\r` so the
+ * replacement is a no-op on already-unescaped input. The lookbehind keeps
+ * `\\n` (genuine literal backslash + n) intact.
+ */
+function defensiveUnescape(text) {
+  return text
+    .replace(/(?<!\\)\\n/g, '\n')
+    .replace(/(?<!\\)\\t/g, '\t')
+    .replace(/(?<!\\)\\r/g, '\r');
+}
+
+/**
+ * Take a captured snippet and return the first sentence (or first
+ * word-bounded slice up to `maxLen` if no sentence terminator is nearby).
+ * Replaces the old `slice(0, 50)` headline which produced mid-clause
+ * garbage like "Decision: any command you must be authenticated. Run x..."
+ * where the first 50 chars meant nothing without their context.
+ */
+function extractFirstSentence(text, maxLen = 80) {
+  const trimmed = text.trim().replace(/\s+/g, ' ');
+  // Find first sentence terminator within reasonable bounds. The terminator
+  // must be followed by whitespace OR end-of-string so URLs / decimals /
+  // version strings ("v4.24.3") don't fool it.
+  const match = trimmed.match(/^([^.!?\n]{15,160}[.!?])(?:\s|$)/);
+  if (match) return match[1].slice(0, maxLen);
+  // No sentence boundary — trim to maxLen at the nearest word boundary.
+  if (trimmed.length <= maxLen) return trimmed;
+  const truncated = trimmed.slice(0, maxLen);
+  const lastSpace = truncated.lastIndexOf(' ');
+  return lastSpace > maxLen * 0.5 ? truncated.slice(0, lastSpace) : truncated;
+}
+
 /**
  * Extract memorable segments from conversation text.
  *
@@ -338,16 +417,23 @@ export function extractMemorableSegments(conversationText, opts = {}) {
   const extractors = opts.mode === 'stop' ? STOP_HOOK_EXTRACTORS : FULL_EXTRACTORS;
   const segments = [];
 
+  // v4.24.3: unescape JSON-encoded escapes before regex matching so
+  // captured content doesn't include literal `\n` / `\t` sequences.
+  const text = defensiveUnescape(conversationText);
+
   for (const extractor of extractors) {
     for (const pattern of extractor.patterns) {
       // Reset lastIndex defensively — patterns are module-level globals.
       pattern.lastIndex = 0;
       let match;
-      while ((match = pattern.exec(conversationText)) !== null) {
+      while ((match = pattern.exec(text)) !== null) {
         const content = match[1].trim();
         if (content.length >= 20) {
-          const titleContent = content.slice(0, 50).replace(/\s+/g, ' ').trim();
-          const title = extractor.titlePrefix + (titleContent.length < 50 ? titleContent : titleContent + '...');
+          // v4.24.3: headline = first sentence (sentence-bounded), not
+          // the first 50 chars. Eliminates mid-clause garbage in the
+          // MEMORY.md index.
+          const headline = extractFirstSentence(content, 80);
+          const title = extractor.titlePrefix + headline;
           segments.push({
             title,
             content: content.slice(0, 500),
@@ -543,11 +629,17 @@ export function processSegments(segments, dynamicThreshold = BASE_THRESHOLD, opt
     if (!isDupe) {
       const text = seg.title + ' ' + seg.content;
       const baseSalience = calculateSalience(text);
-      const category = suggestCategory(text);
+      // v4.25.0: extractorType drives category and memory_purpose. Fall
+      // back to keyword-based suggestCategory only when extractorType is
+      // unknown (defensive; no in-tree extractor produces a name outside
+      // EXTRACTOR_TO_CATEGORY).
+      const category = EXTRACTOR_TO_CATEGORY[seg.extractorType] ?? suggestCategory(text);
+      const memoryPurpose = EXTRACTOR_TO_PURPOSE[seg.extractorType] ?? 'project';
       unique.push({
         ...seg,
         baseSalience,
         category,
+        memoryPurpose,
         tags: extractTags(text, hookTag, seg.extractorType),
       });
     }

package/scripts/lib/precompact-log.mjs

@@ -0,0 +1,142 @@
+/**
+ * Precompact ring buffer (v4.25.0).
+ *
+ * Each precompact hook run writes a debug log of "what did the extractor
+ * propose this time, and which proposals actually landed in `memories`?"
+ * Operators can read it via `shieldcortex inspect last-precompact` when
+ * tuning thresholds or chasing weird auto-extract behaviour.
+ *
+ * Ring buffer at `~/.shieldcortex/precompact-log/{0..9}.json` — index 0 is
+ * the most recent. On every write we rotate (delete 9, rename 8→9, ..., 0→1)
+ * and atomically write the new run to index 0 via a temp-file + rename so a
+ * crash mid-rotation never leaves a torn JSON file.
+ *
+ * Size cap: 10 files × ~5KB each = ~50KB. Negligible disk impact.
+ *
+ * Designed to be best-effort — never throws into the caller. The hook
+ * absolutely must not block compaction on a missing ~/.shieldcortex
+ * directory or a transient EBUSY.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const RING_SIZE = 10;
+
+// Resolved per-call so tests can swap HOME between cases. Read
+// `process.env.HOME` directly rather than going through `os.homedir()`
+// because jest's ESM VM loader doesn't reliably reflect HOME mutations
+// through homedir(), causing test-suite cross-contamination.
+function logDir() {
+  return join(process.env.HOME || homedir(), '.shieldcortex', 'precompact-log');
+}
+
+function logPath(index) {
+  return join(logDir(), `${index}.json`);
+}
+
+function ensureDir() {
+  const dir = logDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Rotate the ring buffer one slot. Oldest entry (index 9) is unlinked,
+ * remaining entries shift up by one. Safe to call when slots are missing.
+ */
+function rotate() {
+  try {
+    unlinkSync(logPath(RING_SIZE - 1));
+  } catch {
+    // No file at the oldest slot — fine.
+  }
+  for (let i = RING_SIZE - 2; i >= 0; i--) {
+    const from = logPath(i);
+    const to = logPath(i + 1);
+    if (existsSync(from)) {
+      try {
+        renameSync(from, to);
+      } catch {
+        // Best-effort — skip if EBUSY/EACCES.
+      }
+    }
+  }
+}
+
+/**
+ * Atomically write a precompact run entry to slot 0 (the newest slot).
+ * Rotates the ring beforehand.
+ *
+ * @param {{
+ *   ranAt?: string,
+ *   thresholdUsed?: number,
+ *   contextFullnessPct?: number,
+ *   totalMemories?: number,
+ *   candidates: Array<{
+ *     extractorType?: string,
+ *     category?: string,
+ *     memoryPurpose?: string,
+ *     title?: string,
+ *     salience?: number,
+ *     saved?: boolean,
+ *     memoryId?: number | null,
+ *     dropReason?: string | null,
+ *   }>,
+ * }} entry
+ */
+export function writePrecompactLog(entry) {
+  try {
+    ensureDir();
+    rotate();
+    const payload = {
+      ranAt: entry.ranAt ?? new Date().toISOString(),
+      thresholdUsed: entry.thresholdUsed ?? null,
+      contextFullnessPct: entry.contextFullnessPct ?? null,
+      totalMemories: entry.totalMemories ?? null,
+      candidates: Array.isArray(entry.candidates) ? entry.candidates : [],
+    };
+    const target = logPath(0);
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+    renameSync(tmp, target);
+  } catch {
+    // Best-effort. The hook continues without a log entry rather than
+    // blocking compaction on a disk error.
+  }
+}
+
+/**
+ * Read a precompact log entry by ring index.
+ *
+ * @param {number} index — 0 = newest, RING_SIZE-1 = oldest
+ * @returns {object | null} parsed entry, or null if missing/corrupt
+ */
+export function readPrecompactLog(index = 0) {
+  try {
+    const raw = readFileSync(logPath(index), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read all present precompact log entries, newest first. Missing slots are
+ * skipped (no nulls in the returned array).
+ *
+ * @returns {Array<{ index: number, entry: object }>}
+ */
+export function listPrecompactLogs() {
+  const out = [];
+  for (let i = 0; i < RING_SIZE; i++) {
+    const entry = readPrecompactLog(i);
+    if (entry) out.push({ index: i, entry });
+  }
+  return out;
+}
+
+export const PRECOMPACT_RING_SIZE = RING_SIZE;
+export { logDir as getPrecompactLogDir };

package/scripts/lib/recall-rank.mjs

@@ -1,14 +1,12 @@
 /**
- * Recall result ranking helpers (v4.23.0).
+ * Recall result ranking helpers.
  *
- * Field context (edith, jarvis 2026-05-24): the UserPromptSubmit recall hook
- * was filtering candidates by FTS5 keyword match but then doing a final sort
- * by RAW salience, discarding the relevance signal. Result: high-salience-
- * but-off-topic memories bubbled to the top of the per-prompt recall preamble
- * ("Decision: that path for the rest of this conversation"-style fragments).
+ * v4.23.0 — FTS rank primary, raw salience tiebreaker (fixed: high-salience-
+ * but-off-topic memories bubbling to the top of the per-prompt recall preamble).
  *
- * v4.23.0 picks the simplest of the three candidate approaches (A in the
- * v4.22.0 plan): **FTS rank is primary, raw salience is the tiebreaker**.
+ * v4.25.0 — tiebreaker now uses *effective* salience instead of raw:
+ *   recency × access × pin × downvote_penalty. See scripts/lib/salience.mjs.
+ *   The DB column stays untouched — this is a read-time computation only.
  *
  * SQLite FTS5 BM25 ranks are negative numbers — more negative = more
  * relevant. So `a.rank - b.rank` (ascending) puts the most-relevant result
@@ -16,21 +14,36 @@
  * field; they sort below all FTS results.
  */
 
+import { computeEffectiveSalience } from './salience.mjs';
+
 /**
  * Sort comparator for memory recall results.
  *
  * Behaviour:
  * - Both rows have `rank` (FTS results): lower rank wins (more relevant)
  * - Only one has `rank`: that one wins (FTS beats category-only fallback)
- * - Neither has `rank` (or tied): higher salience wins
+ * - Neither has `rank` (or tied): higher *effective* salience wins
  *
  * Stable behaviour for equal-rank-equal-salience: original order preserved
  * (Array.prototype.sort in modern engines is stable).
  *
- * @param {{ rank?: number, salience?: number }} a
- * @param {{ rank?: number, salience?: number }} b
+ * @param {{ rank?: number, salience?: number, last_accessed?: string, access_count?: number, pinned?: number, downvote_count?: number }} a
+ * @param {{ rank?: number, salience?: number, last_accessed?: string, access_count?: number, pinned?: number, downvote_count?: number }} b
  * @returns {number} negative if a comes first, positive if b comes first
  */
+// A row carries the v4.25 salience-formula inputs only when the SELECT
+// projected pinned/access_count/last_accessed/downvote_count. Older call
+// sites and recall-rank tests pass rows with just {id, rank, salience} —
+// for those, fall back to raw salience comparison (v4.23 behaviour).
+function hasSalienceFormulaInputs(row) {
+  return (
+    row.access_count !== undefined ||
+    row.last_accessed !== undefined ||
+    row.pinned !== undefined ||
+    row.downvote_count !== undefined
+  );
+}
+
 export function compareRecallResults(a, b) {
   const aHasRank = typeof a.rank === 'number' && Number.isFinite(a.rank);
   const bHasRank = typeof b.rank === 'number' && Number.isFinite(b.rank);
@@ -41,6 +54,10 @@ export function compareRecallResults(a, b) {
   } else if (aHasRank !== bHasRank) {
     return aHasRank ? -1 : 1;
   }
-  // Neither has rank (both from category fallback), or tied rank → salience
+  // v4.25.0: effective salience if both rows carry the formula inputs.
+  // Otherwise (legacy or test rows) preserve v4.23 raw-salience behaviour.
+  if (hasSalienceFormulaInputs(a) && hasSalienceFormulaInputs(b)) {
+    return computeEffectiveSalience(b) - computeEffectiveSalience(a);
+  }
   return (b.salience ?? 0) - (a.salience ?? 0);
 }

package/scripts/lib/salience.mjs

@@ -0,0 +1,83 @@
+/**
+ * Effective salience computation (v4.25.0).
+ *
+ * Pre-4.25 the recall hook ranked tied FTS results by raw `salience` only.
+ * That ignored real signal: a memory that was last accessed 3 months ago
+ * carries less weight than a memory accessed yesterday; a pinned memory
+ * deserves more weight than an identical unpinned one; a memory the user
+ * downvoted via `shieldcortex memory downvote <id>` should be demoted.
+ *
+ * Formula:
+ *   effective = base × recency × access × pin × downvote_penalty
+ *
+ *   recency           = exp(-Δt_days / halfLifeDays)        // decay
+ *   access            = log(1 + access_count) / log(1 + accessNorm)
+ *   pin               = pinned ? pinBoost : 1
+ *   downvote_penalty  = max(0.1, 1 - downvoteDecay × downvote_count)
+ *
+ * All constants are env-var-tunable (no recompile needed for field tuning).
+ *
+ * The function returns the *multiplier-adjusted* salience. The base salience
+ * column in SQLite stays untouched — this is a read-time computation.
+ *
+ * @param {{
+ *   salience?: number,
+ *   last_accessed?: string | null,
+ *   access_count?: number | null,
+ *   pinned?: number | boolean | null,
+ *   downvote_count?: number | null
+ * }} memory
+ * @param {{
+ *   halfLifeDays?: number,
+ *   accessNorm?: number,
+ *   pinBoost?: number,
+ *   downvoteDecay?: number,
+ *   now?: number,
+ * }} [opts]
+ * @returns {number}
+ */
+// Resolve a numeric tuning constant from opts (explicit override), then
+// SHIELDCORTEX_* env var, then the documented default. Returns the default
+// if either of the first two is NaN — we never want a typo'd env var to
+// silently zero out a multiplier.
+function pickNumber(override, envName, fallback) {
+  if (typeof override === 'number' && Number.isFinite(override)) return override;
+  const fromEnv = Number(process.env[envName]);
+  if (Number.isFinite(fromEnv) && fromEnv !== 0) return fromEnv;
+  return fallback;
+}
+
+export function computeEffectiveSalience(memory, opts = {}) {
+  const halfLifeDays = pickNumber(opts.halfLifeDays, 'SHIELDCORTEX_SALIENCE_HALF_LIFE_DAYS', 14);
+  const accessNorm = pickNumber(opts.accessNorm, 'SHIELDCORTEX_SALIENCE_ACCESS_NORM', 10);
+  const pinBoost = pickNumber(opts.pinBoost, 'SHIELDCORTEX_SALIENCE_PIN_BOOST', 1.5);
+  const downvoteDecay = pickNumber(opts.downvoteDecay, 'SHIELDCORTEX_SALIENCE_DOWNVOTE_DECAY', 0.3);
+  const now = opts.now ?? Date.now();
+
+  const base = typeof memory.salience === 'number' ? memory.salience : 0;
+
+  // Recency: exp(-Δt_days / halfLife). last_accessed missing → assume "now"
+  // (a brand-new memory should not be penalised for never having been read).
+  let recency = 1;
+  if (memory.last_accessed) {
+    const lastMs = Date.parse(memory.last_accessed);
+    if (Number.isFinite(lastMs)) {
+      const deltaDays = Math.max(0, (now - lastMs) / 86_400_000);
+      recency = Math.exp(-deltaDays / halfLifeDays);
+    }
+  }
+
+  // Access: log-scaled, normalised so access_count=accessNorm produces ~1.0.
+  const accessCount = Math.max(0, Number(memory.access_count) || 0);
+  const access = Math.log1p(accessCount) / Math.log1p(accessNorm);
+
+  // Pin: SQLite stores boolean as 0/1.
+  const pin = memory.pinned ? pinBoost : 1;
+
+  // Downvote: each downvote lops downvoteDecay off the multiplier, floored
+  // at 0.1 so a 4×-downvoted memory can still surface when truly relevant.
+  const downvotes = Math.max(0, Number(memory.downvote_count) || 0);
+  const downvotePenalty = Math.max(0.1, 1 - downvoteDecay * downvotes);
+
+  return base * recency * access * pin * downvotePenalty;
+}

package/scripts/lib/save-memory.mjs

@@ -20,7 +20,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
  * Async: the pipeline lives in dist/ as ESM and is loaded via dynamic import.
  *
  * @param {import('better-sqlite3').Database} db
- * @param {{ title: string, content: string, category: string, salience: number, tags: string[] }} memory
+ * @param {{ title: string, content: string, category: string, salience: number, tags: string[], memoryPurpose?: string }} memory
  * @param {string|null} [project]
  * @param {{ source?: string }} [opts] — `source` identifies the calling hook
  *   ('session-end-hook' | 'pre-compact-hook' | 'stop-hook' | 'hook').
@@ -50,7 +50,7 @@ export async function saveAutoExtractedMemory(db, memory, project, opts = {}) {
   const decision = result.firewall.result;
 
   if (decision === 'ALLOW') {
-    insertMemoryRow(db, memory, project);
+    insertMemoryRow(db, memory, project, sourceIdentifier);
     return;
   }
 
@@ -73,11 +73,21 @@ export async function saveAutoExtractedMemory(db, memory, project, opts = {}) {
 
 // ==================== Internal: writes ====================
 
-function insertMemoryRow(db, memory, project) {
+function insertMemoryRow(db, memory, project, sourceIdentifier) {
   const timestamp = new Date().toISOString();
+  // v4.25.0: pre-4.25 the INSERT omitted memory_purpose / source / source_kind
+  // / capture_method, so every hook write looked identical to a user-typed
+  // memory at the SQL level. The hook already knows which hook is calling
+  // (sourceIdentifier) and the extractor already computed memoryPurpose —
+  // thread both through so `shieldcortex inspect last-precompact` and any
+  // memory-source SQL query can distinguish hook writes from user writes.
   db.prepare(`
-    INSERT INTO memories (uuid, title, content, type, category, salience, tags, project, created_at, last_accessed)
-    VALUES (?, ?, ?, 'short_term', ?, ?, ?, ?, ?, ?)
+    INSERT INTO memories (
+      uuid, title, content, type, category, salience, tags, project,
+      memory_purpose, source, source_kind, capture_method,
+      created_at, last_accessed
+    )
+    VALUES (?, ?, ?, 'short_term', ?, ?, ?, ?, ?, ?, 'hook', 'auto', ?, ?)
   `).run(
     randomUUID(),
     memory.title,
@@ -86,6 +96,8 @@ function insertMemoryRow(db, memory, project) {
     memory.salience,
     JSON.stringify(memory.tags),
     project || null,
+    memory.memoryPurpose ?? 'project',
+    `hook:${sourceIdentifier}`,
     timestamp,
     timestamp,
   );