shieldcortex 4.28.0 → 4.29.0

package/dist/memory/consolidate.js

@@ -10,11 +10,21 @@
 import { getDatabase, withTransaction } from '../database/init.js';
 import { DEFAULT_CONFIG, } from './types.js';
 import { getMemoriesByType, getRecentMemories, promoteMemory, deleteMemory, searchMemories, getMemoryStats, updateDecayScores, addMemory, rowToMemory, } from './store.js';
-import { runDefencePipeline } from '../defence/index.js';
 import { processDecay, } from './decay.js';
 import { detectContradictions, linkContradictions, } from './contradiction.js';
 import { jaccardSimilarity } from './similarity.js';
 import { pruneActivationCache } from './activation.js';
+// Static import of the shared effective-salience helper. Every other src/ file
+// (cli/memory.ts, the recall hook) reaches salience.mjs via a relative path
+// because `scripts/` lives outside tsconfig's rootDir; a static top-level
+// import compiles clean (tsc keeps the dist layout intact and emits the same
+// '../../scripts/lib/salience.mjs' specifier the dynamic import did) and lets
+// these consolidation functions stay SYNCHRONOUS — better-sqlite3 transactions
+// cannot await, and consolidate()/deduplicateMemories() have several sync
+// callers. One source of truth: this is the same computeEffectiveSalience the
+// recall hook and `shieldcortex memory downvote` use.
+// @ts-expect-error — importing a .mjs hook util that has no .d.ts
+import { computeEffectiveSalience } from '../../scripts/lib/salience.mjs';
 /**
  * Run full consolidation process
  * This is like the brain's sleep consolidation - should be run periodically
@@ -254,49 +264,80 @@ export function findDuplicateMemoryPairs(options) {
     return pairs;
 }
 /**
- * Find memories with very similar titles/content and merge them.
- * Keeps the newer one, appends unique content from the older one.
+ * De-duplicate long-term memories found as duplicate PAIRS by
+ * findDuplicateMemoryPairs (same project|category, similar title + >0.5 content
+ * overlap). Runs every ~4h on the auto path: server.ts setInterval → fullCleanup
+ * → consolidate → deduplicateMemories.
+ *
+ * B11 (memory-quality fix): the previous implementation built
+ * `kept.content + "\n\nMerged from duplicate:\n" + uniqueSentences` and wrote it
+ * back with `UPDATE memories SET content = ?`. That was the SECOND lossy-append
+ * site (mergeSimilarMemories was the first) and kept generating ever-growing
+ * "frankenmemories" on this path even after the first site was fixed. The kept
+ * memory's `content` is now NEVER modified.
+ *
+ * New policy (identical to mergeSimilarMemories — one source of truth):
+ *   - KEEP the higher-EFFECTIVE-salience member of the pair (computeEffectiveSalience
+ *     via the shared salience.mjs — recency/access/pin/downvote, same ranking as
+ *     recall and the downvote CLI). NOTE: this can differ from the pair's raw
+ *     `recommendedKeepId`, which only considered raw salience + recency.
+ *   - Dispose the loser via the shared disposeLoser: combined similarity
+ *     (re-measured vs the kept row) ≥ 0.85 → DELETE; below → DOWNVOTE (reversible).
+ *   - Tags are unioned onto the kept row (metadata only, non-lossy). The kept
+ *     content and salience are untouched.
+ *
+ * Defence re-scan removed (B11): the old re-scan existed ONLY to validate the
+ * SYNTHESIZED concatenated merged body before persisting it (two individually-
+ * clean rows could straddle a credential pattern across the join). Now that no
+ * concatenation happens here, there is no synthesized content to scan — the kept
+ * row's bytes are written verbatim and unchanged, exactly as they already exist
+ * in `memories`. So this pass introduces no new bytes to validate. (This is a
+ * narrow claim about THIS path: it does not assume every row was scanned at write
+ * time — e.g. importMemories inserts rows with no scan — only that the dedup no
+ * longer fabricates a new body that would need scanning.) Dropping the re-scan
+ * also avoids re-auditing unchanged content on every 4h pass.
+ *
+ * Only rows clustered in THIS pass are acted on; historical merged rows are not
+ * rewritten (effective salience demotes them over time). STM→LTM promotion is
+ * handled separately by processDecay/promoteMemory in consolidate().
  */
 export function deduplicateMemories(options) {
     const dryRun = options?.dryRun ?? false;
     return withTransaction(() => {
         const db = getDatabase();
         const pairs = [];
-        const removed = new Set();
+        const disposed = new Set();
+        const nowIso = new Date().toISOString();
+        const downvoteStmt = db.prepare(DOWNVOTE_SQL);
+        // findDuplicateMemoryPairs returns rowToMemory-converted objects, which omit
+        // downvote_count. Fetch raw rows on demand so effective-salience ranking and
+        // the loser disposal see the full signal.
+        const rawRowStmt = db.prepare('SELECT * FROM memories WHERE id = ?');
+        const rawRow = (id) => rawRowStmt.get(id);
         for (const pair of findDuplicateMemoryPairs()) {
-            if (removed.has(pair.memoryA.id) || removed.has(pair.memoryB.id))
+            if (disposed.has(pair.memoryA.id) || disposed.has(pair.memoryB.id))
                 continue;
-            const removedId = pair.recommendedKeepId === pair.memoryA.id ? pair.memoryB.id : pair.memoryA.id;
+            const rowA = rawRow(pair.memoryA.id);
+            const rowB = rawRow(pair.memoryB.id);
+            if (!rowA || !rowB)
+                continue; // already gone (e.g. deleted earlier this pass)
+            // KEEP the higher-effective-salience member (tie → keep A, the older row
+            // by findDuplicateMemoryPairs' created_at ASC ordering).
+            const keepA = effectiveSalienceOfRow(rowA) >= effectiveSalienceOfRow(rowB);
+            const kept = keepA ? pair.memoryA : pair.memoryB;
+            const loser = keepA ? pair.memoryB : pair.memoryA;
             if (!dryRun) {
-                const kept = pair.recommendedKeepId === pair.memoryA.id ? pair.memoryA : pair.memoryB;
-                const discarded = pair.recommendedKeepId === pair.memoryA.id ? pair.memoryB : pair.memoryA;
-                const keptSentences = new Set(kept.content.split(/[.!?\n]+/).map(s => s.trim().toLowerCase()).filter(s => s.length > 0));
-                const uniqueSentences = discarded.content
-                    .split(/[.!?\n]+/)
-                    .map(s => s.trim())
-                    .filter(s => s.length > 0 && !keptSentences.has(s.toLowerCase()));
-                if (uniqueSentences.length > 0) {
-                    const mergedContent = kept.content + '\n\nMerged from duplicate:\n' + uniqueSentences.join('. ') + '.';
-                    // DEFENCE PIPELINE: re-scan the merged content. Two individually-clean
-                    // memories can produce content that straddles a credential pattern
-                    // across the join. Without this re-scan the "every byte in `memories`
-                    // has been scanned" invariant is broken. If the merge is blocked, skip
-                    // both the content update AND the delete so the source rows survive.
-                    const dedupSource = { type: 'hook', identifier: 'hook:consolidation' };
-                    const defenceResult = runDefencePipeline(mergedContent, kept.title, dedupSource, undefined, kept.project ?? discarded.project ?? undefined);
-                    if (defenceResult.firewall.result !== 'ALLOW') {
-                        // Surface in audit (already written by the pipeline) and skip this pair.
-                        console.warn(`[shieldcortex] Dedup merge blocked for memory ${kept.id} + ${removedId}: ${defenceResult.firewall.reason}`);
-                        continue;
-                    }
-                    db.prepare('UPDATE memories SET content = ? WHERE id = ?').run(mergedContent, kept.id);
-                }
-                deleteMemory(removedId);
+                // Union the loser's tags onto the kept row (metadata only, non-lossy).
+                const mergedTags = [...new Set([...kept.tags, ...loser.tags])];
+                db.prepare('UPDATE memories SET tags = ? WHERE id = ?')
+                    .run(JSON.stringify(mergedTags), kept.id);
+                // Shared disposal policy — identical to mergeSimilarMemories.
+                disposeLoser({ content: kept.content, title: kept.title }, { id: loser.id, content: loser.content, title: loser.title }, downvoteStmt, nowIso);
             }
-            removed.add(removedId);
+            disposed.add(loser.id);
             pairs.push({
-                kept: pair.recommendedKeepId,
-                removed: removedId,
+                kept: kept.id,
+                removed: loser.id,
                 similarity: pair.similarity,
             });
         }
@@ -422,10 +463,79 @@ export function enforceMemoryLimits(config = DEFAULT_CONFIG) {
     return deleted;
 }
 /**
- * Find and merge similar short-term memories into coherent long-term entries.
- * Groups memories by project|category, then clusters by Jaccard similarity
- * on content (0.6 weight) + title (0.4 weight).
- * Returns count of deleted (merged) memories.
+ * Combined-similarity bar at/above which a clustered loser is considered a
+ * NEAR-IDENTICAL duplicate of the kept memory. Such a loser's content is, by
+ * construction, almost entirely contained in the kept memory, so deleting it
+ * loses no real information — this is the non-lossy successor to the old
+ * concatenate-then-delete behaviour, minus the concatenation. Moderate
+ * near-dups (similarityThreshold ≤ combined < this) keep some distinct content,
+ * so we DOWNVOTE rather than delete them (reversible, non-lossy).
+ */
+const NEAR_IDENTICAL_DELETE_THRESHOLD = 0.85;
+/**
+ * Effective salience of a raw `memories` row, via the shared
+ * scripts/lib/salience.mjs helper (recency × access × pin × downvote_penalty).
+ * One source of truth with recall ranking and the `shieldcortex memory
+ * downvote` CLI, so "highest-salience to keep" and "downvoted to demote" agree.
+ */
+function effectiveSalienceOfRow(m) {
+    return computeEffectiveSalience({
+        salience: m.salience ?? 0,
+        last_accessed: m.last_accessed ?? null,
+        access_count: m.access_count ?? 0,
+        pinned: m.pinned ?? 0,
+        downvote_count: m.downvote_count ?? 0,
+    });
+}
+function disposeLoser(kept, loser, downvoteStmt, nowIso) {
+    const cSim = jaccardSimilarity(kept.content, loser.content);
+    const tSim = jaccardSimilarity(kept.title, loser.title);
+    const combinedToKept = cSim * 0.6 + tSim * 0.4;
+    if (combinedToKept >= NEAR_IDENTICAL_DELETE_THRESHOLD) {
+        deleteMemory(loser.id);
+        return 'deleted';
+    }
+    downvoteStmt.run(nowIso, loser.id);
+    return 'downvoted';
+}
+/**
+ * The shared downvote SQL — prepared once per pass by each caller and handed to
+ * disposeLoser. Reversible soft demotion: bumps downvote_count (effective
+ * salience reads it) and stamps last_downvoted_at.
+ */
+const DOWNVOTE_SQL = `
+  UPDATE memories
+  SET downvote_count = COALESCE(downvote_count, 0) + 1,
+      last_downvoted_at = ?
+  WHERE id = ?
+`;
+/**
+ * Find clusters of similar short-term memories within each project|category,
+ * KEEP the single highest-effective-salience member, and demote the rest
+ * WITHOUT destroying or concatenating their content.
+ *
+ * B11 (memory-quality fix): the previous implementation appended every loser's
+ * body into the kept memory ("Consolidated context:" bullets) and deleted the
+ * losers. Over ~417 live rows this produced 188 ever-growing "frankenmemories"
+ * — exactly the garbled content users complained about. The kept memory's
+ * `content` is now NEVER modified.
+ *
+ * Disposition per loser (see NEAR_IDENTICAL_DELETE_THRESHOLD):
+ *   - combined ≥ 0.85  → DELETE (near-identical; content already in the kept row)
+ *   - combined < 0.85  → DOWNVOTE (reversible; sinks via effective salience)
+ *
+ * Why the split exists at all: NO reaping path (decay.ts shouldDelete,
+ * prune.ts, expiry.ts, enforceMemoryLimits) reads `downvote_count` or effective
+ * salience — they all order by raw `salience`. So downvote-ONLY would leave the
+ * store unbounded (the dups sink in recall but never get pruned). Deleting the
+ * near-identical losers keeps the store bounded with zero information loss; the
+ * moderate near-dups are preserved and merely demoted.
+ *
+ * Tags are unioned onto the kept row and access counts summed (metadata only,
+ * non-lossy). STM→LTM promotion is handled separately by processDecay/
+ * promoteMemory in consolidate(); this function only de-duplicates.
+ *
+ * Returns the count of deleted (near-identical) losers.
  */
 export function mergeSimilarMemories(project, similarityThreshold = 0.25) {
     return withTransaction(() => {
@@ -466,6 +576,21 @@ export function mergeSimilarMemories(project, similarityThreshold = 0.25) {
                     const contentSim = jaccardSimilarity(memA.content, memB.content);
                     const titleSim = jaccardSimilarity(memA.title, memB.title);
                     const combinedSim = contentSim * 0.6 + titleSim * 0.4;
+                    // THRESHOLD RECONCILIATION (B11, reconciled with Task 8's write-path
+                    // dedup):
+                    //   - Task 8's write-path SKIP fires at combined ≥ 0.5 and is STRICT
+                    //     because skipping a write is IRREVERSIBLE data loss — the memory
+                    //     is never stored.
+                    //   - Consolidate stays AGGRESSIVE at 0.25 because its action is now
+                    //     REVERSIBLE: moderate near-dups are DOWNVOTED — a soft demotion
+                    //     that leaves the row + its content intact (clearing
+                    //     downvote_count restores the prior ranking), not the old
+                    //     concatenate-into-kept + delete, which destroyed data.
+                    //   The two thresholds no longer conflict: a pair at combined ~0.3
+                    //   (below the 0.5 write-skip, above this 0.25 bar) survives the
+                    //   write but is demoted here via reversible downvote. Only
+                    //   near-IDENTICAL losers (≥ 0.85, content already in the kept row)
+                    //   are deleted — see NEAR_IDENTICAL_DELETE_THRESHOLD.
                     if (combinedSim >= similarityThreshold) {
                         cluster.push(j);
                     }
@@ -475,18 +600,17 @@ export function mergeSimilarMemories(project, similarityThreshold = 0.25) {
                 // Mark all as clustered
                 for (const idx of cluster)
                     clustered.add(idx);
-                // Step 4: Merge cluster
-                // Sort by salience desc, pick highest as base
+                // Step 4: Resolve the cluster WITHOUT lossy concatenation.
+                // KEEP the single highest-EFFECTIVE-salience member (downvotes,
+                // recency, pins and access all factor in — same ranking the recall
+                // hook uses). The kept row's `content` is NEVER touched.
                 const clusterMems = cluster.map(idx => group[idx]);
-                clusterMems.sort((a, b) => b.salience - a.salience);
-                const base = clusterMems[0];
-                const others = clusterMems.slice(1);
-                // Merge content
-                const bulletPoints = others
-                    .map(m => `- ${m.title}: ${m.content}`)
-                    .join('\n');
-                const mergedContent = `${base.content}\n\nConsolidated context:\n${bulletPoints}`;
-                // Merge tags (union)
+                clusterMems.sort((a, b) => effectiveSalienceOfRow(b) - effectiveSalienceOfRow(a));
+                const kept = clusterMems[0];
+                const losers = clusterMems.slice(1);
+                // Merge tags onto the kept row (union — metadata only, non-lossy) and
+                // accumulate the losers' access counts so reinforcement history isn't
+                // lost. The kept content and salience stay exactly as they were.
                 const allTags = new Set();
                 for (const m of clusterMems) {
                     try {
@@ -498,24 +622,31 @@ export function mergeSimilarMemories(project, similarityThreshold = 0.25) {
                         // skip invalid tags
                     }
                 }
-                // Sum access counts
                 const totalAccessCount = clusterMems.reduce((sum, m) => sum + (m.access_count || 0), 0);
-                // New salience: base + 0.1, capped at 1.0
-                const newSalience = Math.min(1.0, base.salience + 0.1);
-                // Update base memory
+                // Promote the kept memory to long-term and absorb the union'd tags +
+                // summed access count. NOTE: content is deliberately omitted from this
+                // UPDATE — no frankenmerge.
                 db.prepare(`
           UPDATE memories
           SET type = 'long_term',
-              content = ?,
               tags = ?,
-              salience = ?,
               access_count = ?
           WHERE id = ?
-        `).run(mergedContent, JSON.stringify([...allTags]), newSalience, totalAccessCount, base.id);
-                // Delete others
-                for (const other of others) {
-                    deleteMemory(other.id);
-                    deleted++;
+        `).run(JSON.stringify([...allTags]), totalAccessCount, kept.id);
+                // Dispose of each loser via the SHARED disposal policy (disposeLoser):
+                // near-identical (≥ 0.85 vs the kept row) → DELETE; moderate → DOWNVOTE.
+                // Identical policy to deduplicateMemories — one source of truth.
+                const nowIso = new Date().toISOString();
+                const downvoteStmt = db.prepare(DOWNVOTE_SQL);
+                const keptText = { content: kept.content, title: kept.title };
+                for (const loser of losers) {
+                    const disposition = disposeLoser(keptText, {
+                        id: loser.id,
+                        content: loser.content,
+                        title: loser.title,
+                    }, downvoteStmt, nowIso);
+                    if (disposition === 'deleted')
+                        deleted++;
                 }
             }
         }
@@ -782,70 +913,109 @@ export function fullCleanup(config = DEFAULT_CONFIG) {
  * 1. Find near-duplicates by embedding similarity >0.9, merge them
  * 2. Flag memories >30 days old with no access as archival candidates
  * 3. Detect and flag contradictions
+ *
+ * DISPOSAL POLICY — deliberately DIVERGES from the auto path:
+ * This is the EXPLICIT, user-invoked `shieldcortex consolidate` command (and the
+ * public `consolidateMemories` export). Because the user has actively asked for a
+ * consolidation, aggressive cleanup is the intended behaviour: the loser of every
+ * duplicate pair is HARD-DELETED. This is on purpose and must NOT be replaced with
+ * the gentle `disposeLoser` policy.
+ *
+ * Contrast with the 4-hourly AUTO path (deduplicateMemories / mergeSimilarMemories),
+ * which runs UNATTENDED and therefore uses the conservative `disposeLoser`: it only
+ * deletes near-identical losers (combined ≥ 0.85, content already contained in the
+ * kept row) and merely DOWNVOTES (reversible) the moderate near-dups. That caution
+ * is right for an unsupervised background job, but wrong for a deliberate manual
+ * cleanup the user explicitly triggered.
+ *
+ * The two paths DO share keep-selection: both pick the kept row by EFFECTIVE
+ * salience (effectiveSalienceOfRow — recency/access/pin/downvote), so the row that
+ * survives is consistent across all three dedup sites. Effective salience also
+ * discriminates where the pair's raw `recommendedKeepId` (raw salience + recency)
+ * ties at 1.0.
  */
 export function consolidateMemories() {
-    const db = getDatabase();
-    let nearDuplicatesMerged = 0;
-    let archivalCandidates = 0;
-    let contradictionsDetected = 0;
-    // Step 1: Find and merge near-duplicates
-    const duplicatePairs = findDuplicateMemoryPairs({ limit: 100 });
-    for (const pair of duplicatePairs) {
-        try {
-            const memA = pair.memoryA;
-            const memB = pair.memoryB;
-            if (!memA || !memB)
-                continue;
-            // Keep the recommended one, delete the other
-            const removedId = pair.recommendedKeepId === memA.id ? memB.id : memA.id;
-            const keptId = pair.recommendedKeepId;
-            // Merge tags from both
-            const kept = keptId === memA.id ? memA : memB;
-            const removed = keptId === memA.id ? memB : memA;
-            const mergedTags = [...new Set([...kept.tags, ...removed.tags])];
-            db.prepare('UPDATE memories SET tags = ? WHERE id = ?')
-                .run(JSON.stringify(mergedTags), keptId);
-            deleteMemory(removedId);
-            nearDuplicatesMerged++;
+    // Wrap the dedup delete loop in a transaction for atomicity: previously each
+    // pair was deleted on a bare getDatabase() with no transaction, so a mid-loop
+    // failure left partial deletes (some losers gone, tag-merges half-applied).
+    return withTransaction(() => {
+        const db = getDatabase();
+        let nearDuplicatesMerged = 0;
+        let archivalCandidates = 0;
+        let contradictionsDetected = 0;
+        // findDuplicateMemoryPairs returns rowToMemory-converted objects, which omit
+        // downvote_count. Fetch raw rows on demand so effective-salience keep-selection
+        // sees the full signal (same pattern as deduplicateMemories).
+        const rawRowStmt = db.prepare('SELECT * FROM memories WHERE id = ?');
+        const rawRow = (id) => rawRowStmt.get(id);
+        // Step 1: Find and merge near-duplicates
+        const duplicatePairs = findDuplicateMemoryPairs({ limit: 100 });
+        for (const pair of duplicatePairs) {
+            try {
+                const memA = pair.memoryA;
+                const memB = pair.memoryB;
+                if (!memA || !memB)
+                    continue;
+                // KEEP the higher-EFFECTIVE-salience member (recency/access/pin/downvote),
+                // consistent with deduplicateMemories and mergeSimilarMemories — one source
+                // of truth via effectiveSalienceOfRow. This can differ from the pair's raw
+                // `recommendedKeepId` (raw salience + recency), which can't break a 1.0 tie.
+                const rowA = rawRow(memA.id);
+                const rowB = rawRow(memB.id);
+                if (!rowA || !rowB)
+                    continue; // already gone (deleted earlier this pass)
+                // Tie → keep A (the older row by findDuplicateMemoryPairs' created_at ASC).
+                const keepA = effectiveSalienceOfRow(rowA) >= effectiveSalienceOfRow(rowB);
+                const kept = keepA ? memA : memB;
+                const removed = keepA ? memB : memA;
+                // Merge tags from both onto the kept row (metadata only, non-lossy).
+                const mergedTags = [...new Set([...kept.tags, ...removed.tags])];
+                db.prepare('UPDATE memories SET tags = ? WHERE id = ?')
+                    .run(JSON.stringify(mergedTags), kept.id);
+                // Aggressive hard-DELETE of the loser — intended for this manual command
+                // (see the disposal-policy note in the function header).
+                deleteMemory(removed.id);
+                nearDuplicatesMerged++;
+            }
+            catch {
+                // Skip problematic pairs
+            }
         }
-        catch {
-            // Skip problematic pairs
+        // Step 2: Flag stale memories for archival (>30 days, no access)
+        const thirtyDaysAgo = new Date(Date.now() - 30 * 86_400_000).toISOString();
+        const staleRows = db.prepare(`
+      SELECT id FROM memories
+      WHERE status = 'active'
+        AND last_accessed < ?
+        AND access_count <= 1
+        AND pinned = 0
+    `).all(thirtyDaysAgo);
+        for (const row of staleRows) {
+            try {
+                db.prepare("UPDATE memories SET status = 'archived', updated_at = CURRENT_TIMESTAMP WHERE id = ?")
+                    .run(row.id);
+                archivalCandidates++;
+            }
+            catch {
+                // Skip
+            }
         }
-    }
-    // Step 2: Flag stale memories for archival (>30 days, no access)
-    const thirtyDaysAgo = new Date(Date.now() - 30 * 86_400_000).toISOString();
-    const staleRows = db.prepare(`
-    SELECT id FROM memories
-    WHERE status = 'active'
-      AND last_accessed < ?
-      AND access_count <= 1
-      AND pinned = 0
-  `).all(thirtyDaysAgo);
-    for (const row of staleRows) {
+        // Step 3: Detect contradictions
         try {
-            db.prepare("UPDATE memories SET status = 'archived', updated_at = CURRENT_TIMESTAMP WHERE id = ?")
-                .run(row.id);
-            archivalCandidates++;
+            const contradictions = detectContradictions();
+            if (contradictions.length > 0) {
+                contradictionsDetected = linkContradictions(contradictions);
+            }
         }
         catch {
-            // Skip
+            // Contradiction detection may fail on empty/small DBs
         }
-    }
-    // Step 3: Detect contradictions
-    try {
-        const contradictions = detectContradictions();
-        if (contradictions.length > 0) {
-            contradictionsDetected = linkContradictions(contradictions);
-        }
-    }
-    catch {
-        // Contradiction detection may fail on empty/small DBs
-    }
-    const totalProcessed = duplicatePairs.length + staleRows.length;
-    return {
-        nearDuplicatesMerged,
-        archivalCandidates,
-        contradictionsDetected,
-        totalProcessed,
-    };
+        const totalProcessed = duplicatePairs.length + staleRows.length;
+        return {
+            nearDuplicatesMerged,
+            archivalCandidates,
+            contradictionsDetected,
+            totalProcessed,
+        };
+    });
 }

package/dist/setup/openclaw.d.ts

@@ -20,6 +20,32 @@ export declare function isDockerEnvironment(): boolean;
  * Creates the hooks/ subdirectory if the parent config dir exists.
  */
 export declare function findAllHooksDirs(): string[];
+/**
+ * The standard installed-hook destination: `~/.openclaw/hooks/cortex-memory`.
+ * Resolves the real user's home (sudo-aware) so doctor/postinstall agree with
+ * the install path.
+ */
+export declare function defaultHookDestDir(): string;
+/**
+ * Single source of truth for "the installed hook copy is out of date".
+ *
+ * The cortex-memory hook is installed by FILE COPY (see `copyHookFiles`) into
+ * `~/.openclaw/hooks/cortex-memory/`. A package update does NOT automatically
+ * re-copy it, so the installed `handler.ts` / `runtime.mjs` can drift behind
+ * the package's `HOOK_SOURCE` version. This compares every HOOK_FILE in
+ * `destDir` against the packaged source by content.
+ *
+ * Pure + synchronous (fs reads only, no writes, no side effects). Returns
+ * `true` if any required file is missing from `destDir` OR differs byte-for-byte
+ * from the packaged source. Returns `false` only when every file is present and
+ * identical. On any unexpected read error it returns `true` (fail toward
+ * "refresh needed") so a half-readable install is never reported as current.
+ *
+ * If the package's own `HOOK_SOURCE` is missing (corrupt/partial package), the
+ * comparison is impossible, so this returns `false` — we can't claim the
+ * install is stale relative to a source we can't read.
+ */
+export declare function hookFilesStale(destDir?: string): boolean;
 /**
  * Pure idempotency check for the openclaw.json plugin registration.
  *

package/dist/setup/openclaw.js

@@ -209,6 +209,67 @@ function legacyHookDirs(hooksDir) {
 function hasRequiredHookFiles(dir) {
     return HOOK_FILES.every(file => fs.existsSync(path.join(dir, file)));
 }
+/**
+ * The standard installed-hook destination: `~/.openclaw/hooks/cortex-memory`.
+ * Resolves the real user's home (sudo-aware) so doctor/postinstall agree with
+ * the install path.
+ */
+export function defaultHookDestDir() {
+    return path.join(resolveUserHome(), '.openclaw', 'hooks', HOOK_NAME);
+}
+/**
+ * Single source of truth for "the installed hook copy is out of date".
+ *
+ * The cortex-memory hook is installed by FILE COPY (see `copyHookFiles`) into
+ * `~/.openclaw/hooks/cortex-memory/`. A package update does NOT automatically
+ * re-copy it, so the installed `handler.ts` / `runtime.mjs` can drift behind
+ * the package's `HOOK_SOURCE` version. This compares every HOOK_FILE in
+ * `destDir` against the packaged source by content.
+ *
+ * Pure + synchronous (fs reads only, no writes, no side effects). Returns
+ * `true` if any required file is missing from `destDir` OR differs byte-for-byte
+ * from the packaged source. Returns `false` only when every file is present and
+ * identical. On any unexpected read error it returns `true` (fail toward
+ * "refresh needed") so a half-readable install is never reported as current.
+ *
+ * If the package's own `HOOK_SOURCE` is missing (corrupt/partial package), the
+ * comparison is impossible, so this returns `false` — we can't claim the
+ * install is stale relative to a source we can't read.
+ */
+export function hookFilesStale(destDir = defaultHookDestDir()) {
+    // No installed copy at all → definitely needs (re)install.
+    if (!fs.existsSync(destDir))
+        return true;
+    // No packaged source to compare against → can't prove staleness.
+    if (!fs.existsSync(HOOK_SOURCE))
+        return false;
+    for (const file of HOOK_FILES) {
+        const srcPath = path.join(HOOK_SOURCE, file);
+        const destPath = path.join(destDir, file);
+        try {
+            if (!fs.existsSync(srcPath)) {
+                // Packaged source is missing this file — can't compare it; skip.
+                continue;
+            }
+            if (!fs.existsSync(destPath))
+                return true; // installed copy missing a file
+            const srcBuf = fs.readFileSync(srcPath);
+            const destBuf = fs.readFileSync(destPath);
+            if (!srcBuf.equals(destBuf))
+                return true; // content differs → stale
+        }
+        catch {
+            // Unreadable file on either side — treat as stale so the user re-copies.
+            // DELIBERATE ASYMMETRY with the inline staleness loop in
+            // hooks/openclaw/cortex-memory/handler.ts (selfCheckAndHeal), which does
+            // NOT flip `stale` on a read error: that runs in the long-lived gateway
+            // and must stay quiet on transient errors. This path backs `doctor`, which
+            // SHOULD nag on a half-readable install. Keep them divergent.
+            return true;
+        }
+    }
+    return false;
+}
 function copyHookFiles(sourceDir, destDir) {
     fs.mkdirSync(destDir, { recursive: true });
     for (const file of HOOK_FILES) {

package/dist/tools/remember.js

@@ -5,7 +5,7 @@
  */
 import { z } from 'zod';
 import { addMemory, searchMemories, detectRelationships, createMemoryLink, getLastTruncationInfo } from '../memory/store.js';
-import { analyzeSalienceFactors, explainSalience } from '../memory/salience.js';
+import { calculateSalience, analyzeSalienceFactors, explainSalience } from '../memory/salience.js';
 import { formatErrorForMcp } from '../errors.js';
 import { resolveProject } from '../context/project-context.js';
 import { shouldFilterMemory } from '../memory/save-filter.js';
@@ -116,7 +116,7 @@ export async function executeRemember(input) {
                 error: `Memory filtered: ${filterResult.reason}${filterResult.warning ? ' — ' + filterResult.warning : ''}`,
             };
         }
-        const memory = addMemory({
+        const memoryInput = {
             title,
             content,
             category: input.category,
@@ -129,7 +129,28 @@ export async function executeRemember(input) {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
             memoryPurpose: input.memoryPurpose,
             memoryScope: input.memoryScope,
-        }, undefined, derivedSource ?? { type: 'cli', identifier: 'mcp' });
+        };
+        // Defence-in-depth against the "salience wall": automated/hook callers
+        // (e.g. the OpenClaw hook, which shells out `remember` with importance:"high"
+        // /"critical" and sourceType:"hook") must not mint 0.8/1.0-salience memories
+        // the way a human deliberately saving something can. Cap the FINAL resolved
+        // salience — covering BOTH the importance-derived override and the
+        // calculateSalience fall-through — at the same 0.6 the dedicated auto-extract
+        // writer enforces, so even a stale/un-refactored hook can't exceed it by ANY
+        // path. Interactive remembers (no source, or a user/cli/agent source) stay
+        // uncapped — deliberate intent is honoured. Resolve salience exactly as
+        // addMemory does, from the SAME memoryInput object, so there is no input-shape
+        // drift, then clamp and pass it verbatim.
+        //
+        // Canonical constant: scripts/lib/extract-memorable-segments.mjs:24
+        // (AUTO_EXTRACT_SALIENCE_CAP = 0.6). It lives in a build-script .mjs outside
+        // the compiled src/ surface, so the value is mirrored here.
+        if (derivedSource?.type === 'hook') {
+            const AUTO_EXTRACT_SALIENCE_CAP = 0.6;
+            const effective = memoryInput.salience ?? calculateSalience(memoryInput);
+            memoryInput.salience = Math.min(effective, AUTO_EXTRACT_SALIENCE_CAP);
+        }
+        const memory = addMemory(memoryInput, undefined, derivedSource ?? { type: 'cli', identifier: 'mcp' });
         // Auto-detect and create relationships with existing memories
         let linksCreated = 0;
         try {