shieldcortex 4.28.0 → 4.29.0

package/scripts/lib/dedup.mjs

@@ -0,0 +1,99 @@
+/**
+ * Pure, synchronous near-duplicate detection for the hook write path.
+ *
+ * No DB, no native deps, no dist dependency — this lets the hook writer
+ * (save-memory.mjs) dedup even in a dev workspace where `dist/` hasn't been
+ * built. It is deliberately a .mjs sibling rather than an import of
+ * dist/memory/similarity.js so the write path never gains a build dependency.
+ *
+ * The Jaccard algorithm below MIRRORS src/memory/similarity.ts:tokenize/
+ * jaccardSimilarity so the write-path gate and the consolidate/contradiction
+ * paths agree on what "similar" means. Keep them in lockstep if either moves.
+ *
+ * NOTE (future convergence): hooks/openclaw/cortex-memory/handler.ts has its
+ * own `inspectNovelty` Jaccard gate. This module is the candidate convergence
+ * point for all three, but the handler is intentionally left untouched here.
+ */
+
+/**
+ * Tokenize text into a set of normalized words.
+ * Lowercase, strip punctuation to whitespace, split on whitespace, drop words
+ * of length <= 2. Mirrors src/memory/similarity.ts:tokenize exactly.
+ *
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+export function tokenize(text) {
+  return new Set(
+    String(text ?? '')
+      .toLowerCase()
+      .replace(/[^\w\s]/g, ' ') // punctuation -> space
+      .split(/\s+/)
+      .filter((word) => word.length > 2), // drop very short words (and empties)
+  );
+}
+
+/**
+ * Jaccard similarity between two texts: |A ∩ B| / |A ∪ B|.
+ * Mirrors src/memory/similarity.ts:jaccardSimilarity (two empty token sets => 1.0).
+ *
+ * @param {string} textA
+ * @param {string} textB
+ * @returns {number} 0..1
+ */
+export function jaccardSimilarity(textA, textB) {
+  const setA = tokenize(textA);
+  const setB = tokenize(textB);
+
+  if (setA.size === 0 && setB.size === 0) return 1.0;
+  if (setA.size === 0 || setB.size === 0) return 0.0;
+
+  let intersection = 0;
+  for (const word of setA) {
+    if (setB.has(word)) intersection++;
+  }
+
+  const union = setA.size + setB.size - intersection;
+  return intersection / union;
+}
+
+/**
+ * Decide whether `candidate` is a near-duplicate of `existing`.
+ *
+ * Two-stage to keep cost down and avoid false merges:
+ *   1. Title-Jaccard PRE-GATE — only consider pairs whose titles already
+ *      overlap (>= titleJaccard). If titles are unrelated we never compute
+ *      content similarity. This both bounds work and stops two genuinely
+ *      different notes that happen to reuse a few content words from merging.
+ *   2. Combined score — content*0.6 + title*0.4, matching the weighting in
+ *      src/memory/consolidate.ts (~L603-613). >= combinedThreshold => dup.
+ *
+ * @param {{title: string, content: string}} candidate — the incoming write
+ * @param {{title: string, content: string}} existing  — a stored row
+ * @param {{titleJaccard: number, combinedThreshold: number}} thresholds
+ * @returns {{ duplicate: boolean, combined: number, titleSim: number }}
+ */
+export function isNearDuplicate(candidate, existing, { titleJaccard, combinedThreshold }) {
+  // Empty-title guard: jaccardSimilarity() (faithful to similarity.ts) returns
+  // 1.0 for two empty token sets, but for a dedup PRE-GATE that's a false
+  // match — two titles that tokenize to nothing (e.g. "A", "PC", a bare digit)
+  // carry no overlap signal and must NOT auto-pass the gate. Require real title
+  // tokens on both sides before trusting titleSim.
+  const candTitleTokens = tokenize(candidate.title);
+  const existTitleTokens = tokenize(existing.title);
+  if (candTitleTokens.size === 0 || existTitleTokens.size === 0) {
+    return { duplicate: false, combined: 0, titleSim: 0 };
+  }
+
+  const titleSim = jaccardSimilarity(candidate.title, existing.title);
+
+  // Pre-gate: unrelated titles short-circuit before any content work.
+  if (titleSim < titleJaccard) {
+    return { duplicate: false, combined: 0, titleSim };
+  }
+
+  const contentSim = jaccardSimilarity(candidate.content, existing.content);
+  const combined = contentSim * 0.6 + titleSim * 0.4;
+
+  return { duplicate: combined >= combinedThreshold, combined, titleSim };
+}

package/scripts/lib/openclaw-extract.mjs

@@ -0,0 +1,129 @@
+/**
+ * Pure extraction wrapper for the OpenClaw cortex-memory hook.
+ *
+ * The OpenClaw hook runs inside a LONG-LIVED gateway process. It must NOT
+ * touch the native DB path (saveAutoExtractedMemory / initDatabase install
+ * global shutdown handlers and open better-sqlite3 — a confirmed crash-loop
+ * mechanism). Persistence happens via the existing `callCortex("remember")`
+ * shell-out, which runs in a throwaway mcporter subprocess.
+ *
+ * This module exists so the hook gets the SAME extraction QUALITY as the
+ * Claude-Code side (sentence-bounded capture, rejection corpus, deterministic
+ * taxonomy, 0.6 salience cap) without importing anything native. It depends
+ * ONLY on the pure chunker — string in, plain objects out, no DB, no runtime.
+ */
+
+import {
+  extractMemorableSegments,
+  processSegments,
+  shouldRejectCandidate,
+  EXTRACTOR_TO_CATEGORY,
+  EXTRACTOR_TO_PURPOSE,
+} from './extract-memorable-segments.mjs';
+
+// Session extraction uses the lighter session-end threshold band. 0.30 is the
+// same dynamic threshold the Claude-Code session-end hook passes; the chunker
+// then applies its category-aware floors and the 0.6 cap.
+const SESSION_DYNAMIC_THRESHOLD = 0.30;
+
+// Explicit keyword captures ("remember this: ...") are plain user notes whose
+// content rarely contains a chunker trigger word. When no extractor matches
+// the content, treat it as an explicit important-note (category note,
+// purpose project) — the chunker's own taxonomy for that type.
+const KEYWORD_FALLBACK_EXTRACTOR = 'important-note';
+
+/**
+ * Extract memories from a full session transcript.
+ *
+ * Runs the chunker over the conversation text and returns the processed
+ * memories — already rejection-filtered, deduped, taxonomy-pinned,
+ * threshold-filtered, and salience-capped at 0.6.
+ *
+ * @param {string} conversationText
+ * @returns {Array<{ title: string, content: string, category: string, memoryPurpose: string, tags: string[] }>}
+ */
+export function extractSessionMemories(conversationText) {
+  if (!conversationText || typeof conversationText !== 'string') return [];
+
+  const segments = extractMemorableSegments(conversationText);
+  if (segments.length === 0) return [];
+
+  const processed = processSegments(segments, SESSION_DYNAMIC_THRESHOLD, {
+    conversationText,
+  });
+
+  return Array.isArray(processed) ? processed : [];
+}
+
+/**
+ * Derive the chunker extractor type for an explicit keyword capture.
+ *
+ * Reuses the chunker: if the content itself contains a recognised trigger
+ * shape (a decision, a fix, a learning, etc.), adopt that extractor's type so
+ * the taxonomy is accurate. Otherwise fall back to an explicit important-note.
+ * The longest captured segment wins (most context retained).
+ */
+function deriveKeywordExtractorType(content) {
+  const segments = extractMemorableSegments(content);
+  if (segments.length === 0) return KEYWORD_FALLBACK_EXTRACTOR;
+  let best = segments[0];
+  for (const seg of segments) {
+    if (seg.content.length > best.content.length) best = seg;
+  }
+  return best.extractorType || KEYWORD_FALLBACK_EXTRACTOR;
+}
+
+/**
+ * Build a single memory from an EXPLICIT keyword trigger.
+ *
+ * Explicit user intent ("remember this", "for the record", ...) must never be
+ * silently dropped by the salience threshold (design B8). So this path applies
+ * ONLY the rejection corpus (to drop true malformations) and bypasses the
+ * threshold. It still derives category + memory_purpose from the chunker's
+ * deterministic taxonomy — no new classification logic.
+ *
+ * Classification is driven by the AUTHORITATIVE extractorType passed in from
+ * the matched trigger (the trigger phrase carries the intent signal, e.g.
+ * "the fix was" → error-fix). When extractorType is absent or unknown we fall
+ * back to re-scanning the content with the chunker (the truly-generic case).
+ * We never silently collapse a typed trigger to a generic `note`.
+ *
+ * @param {string} content — the captured content after the trigger
+ * @param {string} [extractorType] — authoritative chunker extractor type from
+ *   the matched trigger (one of EXTRACTOR_TO_CATEGORY's keys). Optional.
+ * @returns {Array<{ title: string, content: string, category: string, memoryPurpose: string }>}
+ *   exactly ONE memory, or [] if the rejection corpus flags it as malformed.
+ */
+export function extractKeywordMemory(content, extractorType) {
+  if (!content || typeof content !== 'string') return [];
+  const trimmed = content.trim();
+  if (trimmed.length < 5) return [];
+
+  // The trigger's extractorType is authoritative when supplied & recognised;
+  // otherwise re-scan the content (generic triggers like "remember this" whose
+  // text may itself carry a decision/fix/learning shape).
+  const resolvedType =
+    extractorType && extractorType in EXTRACTOR_TO_CATEGORY
+      ? extractorType
+      : deriveKeywordExtractorType(trimmed);
+
+  const candidate = { title: '', content: trimmed.slice(0, 500), extractorType: resolvedType };
+
+  // Rejection corpus only — drop true malformations (bare imperatives,
+  // negation-scope drops, email-body bleed, etc.). NOT the salience threshold.
+  if (shouldRejectCandidate(candidate, trimmed).rejected) return [];
+
+  const category = EXTRACTOR_TO_CATEGORY[resolvedType] ?? 'note';
+  const memoryPurpose = EXTRACTOR_TO_PURPOSE[resolvedType] ?? 'project';
+
+  const title = trimmed.slice(0, 80).replace(/["\n]/g, ' ').trim();
+
+  return [
+    {
+      title,
+      content: candidate.content,
+      category,
+      memoryPurpose,
+    },
+  ];
+}

package/scripts/lib/recall-log.mjs

@@ -98,7 +98,22 @@ function rotate() {
  *     source?: 'fts' | 'category-boost',
  *     effectiveSalience?: number,
  *     injected?: boolean,
- *     dropReason?: string | null,
+ *     // Why a candidate was not injected (null = injected). Recognised values:
+ *     //   'dedupe'                — content hash seen in a recent turn
+ *     //   'outside_top_n'         — ranked below the MAX_RESULTS cut
+ *     //   'not_injected'          — early-exit before the dedupe filter ran
+ *     //   'below_term_coverage'   — P4 gate: matched too few distinct query terms
+ *     //   'below_relevance_floor' — P4 gate: BM25 rank below the relative floor
+ *     // The two P4 reasons appear in SHADOW mode too (the row is still
+ *     // injected then) so `shieldcortex inspect last-recall` can show
+ *     // "considered but below floor" for threshold tuning before enforcement.
+ *     dropReason?:
+ *       | 'dedupe'
+ *       | 'outside_top_n'
+ *       | 'not_injected'
+ *       | 'below_term_coverage'
+ *       | 'below_relevance_floor'
+ *       | null,
  *   }>,
  *   injectedCount?: number,
  *   finalContextChars?: number,

package/scripts/lib/recall-relevance.mjs

@@ -0,0 +1,191 @@
+/**
+ * Recall relevance gate (P4, B9 design).
+ *
+ * The per-turn UserPromptSubmit recall hook runs an FTS5 OR-of-terms query.
+ * FTS5 happily returns a row that matches just ONE common term out of six —
+ * which is how off-topic, high-salience memories ended up injected every turn
+ * ("same 5 every turn, none relevant" — EDITH, 2026-05). A relative BM25 floor
+ * alone does NOT fix this: a "what is the weather today" query still returns
+ * five hits within 35% of the best rank.
+ *
+ * The load-bearing discriminator is TERM-COVERAGE: how many DISTINCT query
+ * terms a row actually matches. A 1-of-6-terms OR-match is noise; a real match
+ * covers multiple terms.
+ *
+ * Two-stage gate:
+ *   1. TERM-COVERAGE (primary). Keep iff
+ *        matchedTerms >= minTermMatches
+ *        OR (totalQueryTerms <= minTermMatches AND matchedTerms === totalQueryTerms)
+ *      — i.e. a multi-term match, OR a terse prompt that was matched in full.
+ *      So a 1-of-6 match drops; a 2-of-2 terse match keeps.
+ *   2. RELATIVE BM25 FLOOR (secondary). Among coverage survivors that carry an
+ *      FTS `rank`, drop rows weaker than `relFactor` of this query's best rank.
+ *      SQLite bm25 ranks are negative; more negative = more relevant, so the
+ *      floor is `best * relFactor` (less negative) and we drop `rank > floor`.
+ *      Rows WITHOUT a `rank` (category-boost path) have no FTS rank and are
+ *      exempt from the BM25 floor — but are STILL subject to term-coverage.
+ *
+ * Pure: no DB, no env reads, no mutation of inputs. The caller resolves all
+ * options (mirror the pickNumber/env pattern in salience.mjs at the call site).
+ */
+
+/**
+ * Count how many DISTINCT query terms appear in the given text, matched
+ * case-insensitively on word-ish boundaries (NOT substring — "schema" must
+ * not match inside "schematics"). A term made entirely of non-word characters
+ * after lowercasing is skipped.
+ *
+ * @param {string} text
+ * @param {string[]} queryTerms
+ * @returns {number}
+ */
+function countMatchedTerms(text, queryTerms) {
+  const haystack = String(text || '').toLowerCase();
+  let matched = 0;
+  const seen = new Set();
+  for (const raw of queryTerms) {
+    const term = String(raw || '').toLowerCase();
+    if (!term || seen.has(term)) continue;
+    seen.add(term);
+    // Word-ish boundary: the term must be bounded by a non-word-char (or
+    // string edge) on both sides. Escape regex metacharacters in the term.
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(^|[^\\p{L}\\p{N}_])${escaped}([^\\p{L}\\p{N}_]|$)`, 'u');
+    if (re.test(haystack)) matched += 1;
+  }
+  return matched;
+}
+
+/**
+ * Apply the term-coverage + relative-BM25 relevance gate to a set of recall
+ * candidate rows.
+ *
+ * @param {Array<{ id?: any, title?: string, content?: string, rank?: number }>} rows
+ * @param {{
+ *   queryTerms: string[],
+ *   minTermMatches?: number,
+ *   relFactor?: number,
+ *   maxBm25?: number | null,
+ * }} opts
+ * @returns {{ kept: any[], dropped: Array<{ row: any, reason: 'below_term_coverage' | 'below_relevance_floor' }> }}
+ */
+export function filterByRelevance(rows, opts = {}) {
+  const list = Array.isArray(rows) ? rows : [];
+  const queryTerms = Array.isArray(opts.queryTerms) ? opts.queryTerms : [];
+  const minTermMatches =
+    typeof opts.minTermMatches === 'number' && Number.isFinite(opts.minTermMatches)
+      ? opts.minTermMatches
+      : 2;
+  const relFactor =
+    typeof opts.relFactor === 'number' && Number.isFinite(opts.relFactor) ? opts.relFactor : 0.35;
+  // Absolute BM25 floor is OPT-IN: null/undefined (the default) means "no
+  // absolute dreg cut". It has no safe cross-corpus default — on a small/new
+  // FTS index real bm25 ranks are tiny (~-1e-6), so an absolute floor like
+  // -0.5 would drop even a perfect full-coverage match the moment an operator
+  // turns on enforce mode. Only honour it when an explicit numeric value is
+  // passed; the relative floor + term-coverage do the gating otherwise.
+  const maxBm25 =
+    typeof opts.maxBm25 === 'number' && Number.isFinite(opts.maxBm25) ? opts.maxBm25 : null;
+
+  // Distinct, non-empty query terms (lowercased) — defines totalQueryTerms.
+  const distinctTerms = [];
+  const seenTerm = new Set();
+  for (const raw of queryTerms) {
+    const t = String(raw || '').toLowerCase();
+    if (t && !seenTerm.has(t)) {
+      seenTerm.add(t);
+      distinctTerms.push(t);
+    }
+  }
+  const totalQueryTerms = distinctTerms.length;
+
+  // With no usable query terms there is nothing to gate on — keep everything
+  // (defensive; the hook short-circuits before calling us in that case).
+  if (totalQueryTerms === 0) {
+    return { kept: [...list], dropped: [] };
+  }
+
+  const dropped = [];
+
+  // ── Stage 1: term coverage ────────────────────────────────────────────
+  const coverageSurvivors = [];
+  for (const row of list) {
+    const text = `${row && row.title ? row.title : ''} ${row && row.content ? row.content : ''}`;
+    const matchedTerms = countMatchedTerms(text, distinctTerms);
+    const multiTerm = matchedTerms >= minTermMatches;
+    const terseFullMatch = totalQueryTerms <= minTermMatches && matchedTerms === totalQueryTerms;
+    if (multiTerm || terseFullMatch) {
+      coverageSurvivors.push(row);
+    } else {
+      dropped.push({ row, reason: 'below_term_coverage' });
+    }
+  }
+
+  // ── Stage 2: relative BM25 floor (only over rows carrying an FTS rank) ──
+  const ranked = coverageSurvivors.filter(
+    (r) => typeof r.rank === 'number' && Number.isFinite(r.rank),
+  );
+  // best = most-negative (most relevant) rank among survivors.
+  let best = null;
+  for (const r of ranked) {
+    if (best === null || r.rank < best) best = r.rank;
+  }
+  // Relative floor: drop ranked rows weaker (greater, i.e. less negative) than
+  // best * relFactor. Only meaningful when best is negative (normal BM25).
+  const relativeFloor = best !== null && best < 0 ? best * relFactor : null;
+
+  const kept = [];
+  for (const row of coverageSurvivors) {
+    const hasRank = typeof row.rank === 'number' && Number.isFinite(row.rank);
+    if (hasRank) {
+      // Absolute dreg cut: a rank weaker than maxBm25 is noise regardless of
+      // the relative floor (guards a query where even the best hit is weak).
+      if (maxBm25 !== null && row.rank > maxBm25) {
+        dropped.push({ row, reason: 'below_relevance_floor' });
+        continue;
+      }
+      if (relativeFloor !== null && row.rank > relativeFloor) {
+        dropped.push({ row, reason: 'below_relevance_floor' });
+        continue;
+      }
+    }
+    // No rank (category-boost) → exempt from the BM25 floor, already passed
+    // term coverage. Or a ranked row at/under the floor.
+    kept.push(row);
+  }
+
+  return { kept, dropped };
+}
+
+/**
+ * Extract the distinct FTS query terms from a raw prompt, using the SAME
+ * normalisation the hook's escapeFts5 applies before the OR-join (strip FTS5
+ * operators, drop boolean keywords, split on whitespace, keep words longer
+ * than two chars, cap at six). Exposed here so the relevance gate and the FTS
+ * query agree on exactly which terms count.
+ *
+ * @param {string} query
+ * @returns {string[]} up to 6 distinct lowercased terms
+ */
+export function extractQueryTerms(query) {
+  const words = String(query || '')
+    .replace(/[*(){}[\]<>~^"]/g, ' ')
+    .replace(/\b(AND|OR|NOT|NEAR)\b/gi, '')
+    .split(/\s+/)
+    .filter((w) => w.length > 2);
+  // Dedup BEFORE the cap so repeated early terms don't crowd out distinct
+  // later ones (e.g. "drizzle drizzle drizzle migration migration rollback
+  // schema postgres journal" → up to 6 DISTINCT terms, not 3). First
+  // occurrence wins (order preserved); the slice then keeps the first 6.
+  const out = [];
+  const seen = new Set();
+  for (const w of words) {
+    const lw = w.toLowerCase();
+    if (!seen.has(lw)) {
+      seen.add(lw);
+      out.push(lw);
+    }
+    if (out.length >= 6) break;
+  }
+  return out;
+}

package/scripts/lib/salience.mjs

@@ -11,7 +11,7 @@
  *   effective = base × recency × access × pin × downvote_penalty
  *
  *   recency           = exp(-Δt_days / halfLifeDays)        // decay
- *   access            = log(1 + access_count) / log(1 + accessNorm)
+ *   access            = accessFloor + (1 - accessFloor) × log(1 + access_count) / log(1 + accessNorm)
  *   pin               = pinned ? pinBoost : 1
  *   downvote_penalty  = max(0.1, 1 - downvoteDecay × downvote_count)
  *
@@ -30,6 +30,7 @@
  * @param {{
  *   halfLifeDays?: number,
  *   accessNorm?: number,
+ *   accessFloor?: number,
  *   pinBoost?: number,
  *   downvoteDecay?: number,
  *   now?: number,
@@ -52,6 +53,7 @@ export function computeEffectiveSalience(memory, opts = {}) {
   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 accessFloor = pickNumber(opts.accessFloor, 'SHIELDCORTEX_ACCESS_FLOOR', 0.4);
   const now = opts.now ?? Date.now();
 
   const base = typeof memory.salience === 'number' ? memory.salience : 0;
@@ -67,9 +69,12 @@ export function computeEffectiveSalience(memory, opts = {}) {
     }
   }
 
-  // Access: log-scaled, normalised so access_count=accessNorm produces ~1.0.
+  // Access: log-scaled boost, NOT a gate. Floored at accessFloor so a
+  // never-accessed memory (access_count=0, ~44% of the live DB) keeps a
+  // non-zero multiplier instead of collapsing the whole product to 0.
+  // access_count=0 → accessFloor; access_count=accessNorm → ~1.0.
   const accessCount = Math.max(0, Number(memory.access_count) || 0);
-  const access = Math.log1p(accessCount) / Math.log1p(accessNorm);
+  const access = accessFloor + (1 - accessFloor) * (Math.log1p(accessCount) / Math.log1p(accessNorm));
 
   // Pin: SQLite stores boolean as 0/1.
   const pin = memory.pinned ? pinBoost : 1;

package/scripts/lib/save-memory.mjs

@@ -1,6 +1,32 @@
 import { randomUUID } from 'crypto';
 import { dirname, resolve } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
+import { isNearDuplicate } from './dedup.mjs';
+
+// Env-tunable dedup thresholds (pickNumber/env pattern — mirrors
+// scripts/prompt-recall-hook.mjs). A typo'd or empty env var falls back to the
+// documented default rather than silently zeroing the gate.
+function pickNumber(envName, fallback) {
+  const fromEnv = Number(process.env[envName]);
+  if (Number.isFinite(fromEnv) && process.env[envName] !== undefined && process.env[envName] !== '') {
+    return fromEnv;
+  }
+  return fallback;
+}
+
+// Title-Jaccard PRE-GATE: only pairs whose titles already overlap this much get
+// a content comparison (bounds cost + avoids merging unrelated notes).
+const DEDUP_TITLE_JACCARD = pickNumber('SHIELDCORTEX_DEDUP_TITLE_JACCARD', 0.6);
+// Combined (content*0.6 + title*0.4) score at/above which the incoming write is
+// dropped as a near-duplicate.
+//
+// DELIBERATE: this write-skip threshold (0.5) is STRICTER than
+// consolidate.ts's merge threshold (0.25). Skipping silently DISCARDS the new
+// write, so a false positive here is data loss — we demand high confidence. A
+// consolidate false-merge only concatenates two existing rows (recoverable),
+// so it can afford to be more aggressive. Do not lower this to match consolidate.
+const DEDUP_COMBINED = pickNumber('SHIELDCORTEX_DEDUP_COMBINED', 0.5);
+const DEDUP_CANDIDATE_LIMIT = 200; // bound the candidate scan per write
 
 /**
  * Insert an auto-extracted memory into the SC database, routed through the
@@ -76,16 +102,18 @@ export async function saveAutoExtractedMemory(db, memory, project, opts = {}) {
 function insertMemoryRow(db, memory, project, sourceIdentifier) {
   const timestamp = new Date().toISOString();
 
-  // Cross-call dedup: the hook fires repeatedly (per turn, or per salience
-  // bypass) over overlapping transcript windows, so the same regex match
-  // tends to surface multiple times across calls. The within-batch dedup in
-  // processSegments doesn't cover that. A single SELECT by (title, project,
-  // source_kind) keeps re-extractions from cluttering the store.
+  // Cross-call, CROSS-PATH exact-title dedup: the hook fires repeatedly (per
+  // turn, or per salience bypass) over overlapping transcript windows, so the
+  // same regex match tends to surface multiple times across calls. The
+  // within-batch dedup in processSegments doesn't cover that. We match on
+  // (title, project) WITHOUT a source_kind filter — incoming writes here are
+  // always hook, so dropping the filter just means a hook re-extraction of
+  // something the user ALREADY saved manually is caught too (the old
+  // source_kind='hook' filter let those through).
   const existing = db.prepare(
     `SELECT 1 FROM memories
        WHERE title = ?
          AND (project IS ? OR (project IS NULL AND ? IS NULL))
-         AND source_kind = 'hook'
        LIMIT 1`,
   ).get(memory.title, project || null, project || null);
   if (existing) {
@@ -93,6 +121,34 @@ function insertMemoryRow(db, memory, project, sourceIdentifier) {
     return;
   }
 
+  // Near-duplicate dedup: exact-title only catches verbatim re-saves. Reworded
+  // captures of the same fact ("Fix: X" vs "X fix") have different titles but
+  // near-identical content. Scan same-project, same-category, ACTIVE rows
+  // (most-recent first, bounded) and skip the write if any is a near-dup. This
+  // is also cross-path — a prior manual row can block a hook re-extraction.
+  const candidates = db.prepare(
+    `SELECT title, content FROM memories
+       WHERE (project IS ? OR (project IS NULL AND ? IS NULL))
+         AND category IS ?
+         AND COALESCE(status, 'active') = 'active'
+       ORDER BY created_at DESC
+       LIMIT ?`,
+  ).all(project || null, project || null, memory.category ?? null, DEDUP_CANDIDATE_LIMIT);
+
+  for (const candidate of candidates) {
+    const { duplicate, combined } = isNearDuplicate(
+      { title: memory.title, content: memory.content },
+      { title: candidate.title, content: candidate.content },
+      { titleJaccard: DEDUP_TITLE_JACCARD, combinedThreshold: DEDUP_COMBINED },
+    );
+    if (duplicate) {
+      process.stderr.write(
+        `[shieldcortex save-memory] skipped near-duplicate (combined=${combined.toFixed(2)}): ${memory.title}\n`,
+      );
+      return;
+    }
+  }
+
   db.prepare(`
     INSERT INTO memories (
       uuid, title, content, type, category, salience, tags, project,

package/scripts/lib/session-context.mjs

@@ -0,0 +1,30 @@
+/**
+ * Session-start context ordering helpers.
+ *
+ * The boot preamble used to order high-priority memories by raw
+ * `salience DESC, last_accessed DESC`. Because ~80% of rows sit at raw
+ * salience=1.0 (the "wall"), that ordering was an 80% tie and effectively
+ * random. Ranking by *effective* salience (recency × access × pin ×
+ * downvote_penalty — see scripts/lib/salience.mjs) lets fresh/relevant
+ * memories rank above stale 1.0 ones.
+ *
+ * Kept pure + side-effect-free so it's unit-testable without importing the
+ * hook entrypoint (which runs a stdin/process.exit IIFE at module load).
+ */
+
+import { computeEffectiveSalience } from './salience.mjs';
+
+/**
+ * Sort memories by effective salience, highest first. Returns a new array;
+ * the input is not mutated. `opts` is passed through to
+ * computeEffectiveSalience so tests can inject a deterministic `now`.
+ *
+ * @param {Array<object>} memories
+ * @param {object} [opts] - forwarded to computeEffectiveSalience (e.g. { now })
+ * @returns {Array<object>}
+ */
+export function orderByEffectiveSalience(memories, opts = {}) {
+  return [...memories].sort(
+    (a, b) => computeEffectiveSalience(b, opts) - computeEffectiveSalience(a, opts),
+  );
+}

package/scripts/postinstall.mjs

@@ -174,21 +174,40 @@ if (isGlobal && !isCI) {
       console.warn('[shieldcortex] To manually install after confirming OpenClaw support:');
       console.warn('[shieldcortex]   shieldcortex openclaw install --no-plugins');
     } else if (state.pluginInstalled) {
-      // Bug #15: Plugin exists from a previous install — auto-copy new files
+      // Bug #15 + Task 6b: a previous install left the plugin (and possibly the
+      // hook) on disk. Both are installed by file-copy, so a package bump
+      // leaves them stale until something re-copies them.
       console.log('');
-      console.log('[shieldcortex] Existing plugin detected. Copying updated plugin files...');
-      const copied = autoCopyPlugin(state.pluginDir, cliPath);
-      if (copied) {
-        console.log('[shieldcortex] Plugin files updated. Run full refresh for hook updates:');
-        console.log('[shieldcortex]   shieldcortex openclaw install');
-      } else {
-        // Fall back to full refresh
-        console.log('[shieldcortex] Auto-copy failed. Running full OpenClaw refresh...');
+      if (state.hookInstalled) {
+        // Hook present → run the full refresh ONLY. `shieldcortex openclaw
+        // install` re-copies the hook (copyHookFiles) AND re-installs/registers
+        // the plugin in one idempotent pass, so a standalone autoCopyPlugin()
+        // here would copy the plugin a second time for no benefit. The full
+        // refresh is the single guarantee that keeps the file-copied hook from
+        // going stale on a plugin-present update.
+        console.log('[shieldcortex] Refreshing OpenClaw hook + plugin to latest version...');
         const ok = refreshOpenClawInstall(cliPath);
         if (!ok) {
-          console.warn('[shieldcortex] ⚠  OpenClaw auto-refresh failed (non-fatal).');
+          console.warn('[shieldcortex] ⚠  OpenClaw hook + plugin refresh failed (non-fatal).');
           console.warn('[shieldcortex] Run manually: shieldcortex openclaw install');
         }
+      } else {
+        // Plugin-only (no hook) → just freshen the plugin files in place, with
+        // a full-refresh fallback if the in-place copy fails.
+        console.log('[shieldcortex] Existing plugin detected. Copying updated plugin files...');
+        const copied = autoCopyPlugin(state.pluginDir, cliPath);
+        if (copied) {
+          console.log('[shieldcortex] Plugin files updated.');
+          console.log('[shieldcortex] No hook installed. Run full setup for hook + memory:');
+          console.log('[shieldcortex]   shieldcortex openclaw install');
+        } else {
+          console.warn('[shieldcortex] ⚠  Plugin auto-copy failed — running full refresh.');
+          const ok = refreshOpenClawInstall(cliPath);
+          if (!ok) {
+            console.warn('[shieldcortex] ⚠  OpenClaw auto-refresh failed (non-fatal).');
+            console.warn('[shieldcortex] Run manually: shieldcortex openclaw install');
+          }
+        }
       }
     } else if (state.hookInstalled) {
       // Hook exists but no plugin — run full refresh