shieldcortex 4.28.1 → 4.29.0

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 {

package/hooks/openclaw/cortex-memory/handler.ts

@@ -10,14 +10,34 @@ import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { createOpenClawRuntime } from "./runtime.mjs";
 
 // ==================== SERVER COMMAND RESOLUTION ====================
 
+// Transcript line format shared by the producer (getRecentMessages builds
+// `${role}: ${text}`) and the consumer (assistantConversationText filters on
+// this prefix). Centralised so a format change can't silently break the filter.
+const ASSISTANT_PREFIX = "assistant:";
+
+// Process-global by design: these one-shot notice flags and the load-null
+// cache live for the lifetime of the long-lived gateway process. A gateway
+// restart is the intended upgrade boundary that resets them.
 let _autoMemoryNoticeShown = false;
+let _noExtractNoticeShown = false;
 const runtime = createOpenClawRuntime({ logPrefix: "[cortex-memory]" });
 const loadShieldConfig = runtime.loadShieldConfig;
 const callCortex = runtime.callCortex;
+// Pure chunker wrapper loader (resolves the local install's hardened
+// extractor). Returns null when no local install is resolvable — in which
+// case auto-capture is simply skipped (we do NOT regrow the old high-salience
+// bespoke-extractor path). The wrapper imports nothing native; persistence
+// still flows only through callCortex's mcporter shell-out.
+const loadOpenClawExtract = runtime.loadOpenClawExtract;
+// Resolves the ShieldCortex package root from the resolved server binary (no
+// DB access). Used by selfCheckAndHeal to compare the running hook against the
+// packaged source for staleness — warn-only, never re-copies from the gateway.
+const resolvePackageRoot = runtime.resolvePackageRoot;
 
 async function isOpenClawAutoMemoryEnabled() {
   const config = await loadShieldConfig();
@@ -251,67 +271,29 @@ async function scanInstalledHooks() {
 }
 
 // ==================== CONTENT EXTRACTION ====================
-
-const PATTERNS = {
-  architecture: [
-    /\b(?:architecture|designed|structured|pattern|approach)\b.*?(?:uses?|is|with)\b/i,
-    /\b(?:created|implemented|refactored|built|set up)\b/i,
-    /\b(?:decided?\s+to|going\s+with|chose|opted?\s+for|using)\b/i,
-  ],
-  error: [
-    /\b(?:fixed|resolved|solved)\s+(?:by|with|using)\b/i,
-    /\b(?:the\s+)?(?:solution|fix|root\s*cause|bug)\s+(?:was|is)\b/i,
-  ],
-  learning: [
-    /\b(?:learned|discovered|turns?\s+out|figured\s+out|realized)\b/i,
-    /\b(?:TIL|today\s+I\s+learned)\b/i,
-  ],
-  preference: [
-    /\b(?:I|we|you\s+should)\s+(?:always|never)\b/i,
-    /\b(?:always\s+use|never\s+use|never\s+commit)\b/i,
-    /\bprefer(?:\s+to)?\s+\w+/i,
-    /\bshould\s+always\b/i,
-  ],
-  note: [
-    /\b(?:important|remember|key\s+point|crucial|note)\s*:/i,
-  ],
-};
+//
+// Extraction is delegated to the hardened centralized chunker via the pure
+// `openclaw-extract` wrapper (resolved through runtime.loadOpenClawExtract).
+// The old bespoke regex extractor lived here and mislabelled categories,
+// produced clause fragments, and minted high/critical-salience memories (the
+// "salience wall"). It is intentionally gone — the chunker is now the single
+// source of truth for extraction quality and taxonomy. Persistence below is
+// uniformly importance:"normal" (0.5, capped well under the wall).
 
 /**
- * Extract high-salience content from session messages
- * @param {string[]} messages - Array of "role: content" strings
- * @returns {Array<{title: string, content: string, category: string}>}
+ * Join transcript lines into conversation text, keeping ONLY assistant-authored
+ * lines. getRecentMessages returns "role: content" strings for both user and
+ * assistant turns; for the first ship we extract from assistant text only
+ * (lowest-risk: don't mine user-typed prose). Returns "" if nothing qualifies.
  */
-function extractMemories(messages) {
-  const extracted = [];
-  const seen = new Set();
-
+function assistantConversationText(messages: string[]): string {
+  const parts: string[] = [];
   for (const msg of messages) {
-    if (!msg.startsWith("assistant:")) continue;
-    const text = msg.slice("assistant:".length).trim();
-    if (text.length < 20) continue;
-
-    for (const [category, patterns] of Object.entries(PATTERNS)) {
-      for (const pattern of patterns) {
-        if (pattern.test(text)) {
-          const title = text.slice(0, 80).replace(/["\n]/g, " ").trim();
-          if (seen.has(title)) break;
-          seen.add(title);
-
-          extracted.push({
-            title,
-            content: text.slice(0, 500),
-            category,
-          });
-          break;
-        }
-      }
-      if (extracted.length >= 5) break;
-    }
-    if (extracted.length >= 5) break;
+    if (typeof msg !== "string" || !msg.startsWith(ASSISTANT_PREFIX)) continue;
+    const text = msg.slice(ASSISTANT_PREFIX.length).trim();
+    if (text.length > 0) parts.push(text);
   }
-
-  return extracted;
+  return parts.join("\n");
 }
 
 // ==================== SESSION FILE READER ====================
@@ -338,7 +320,11 @@ async function getRecentMessages(sessionFilePath) {
               ? msg.content.find((c) => c.type === "text")?.text
               : msg.content;
             if (text && !text.startsWith("/")) {
-              messages.push(`${msg.role}: ${text}`);
+              // Producer side of the transcript line format. The assistant
+              // prefix is tied to ASSISTANT_PREFIX so the consumer
+              // (assistantConversationText) filter can't silently drift.
+              const prefix = msg.role === "assistant" ? ASSISTANT_PREFIX : `${msg.role}:`;
+              messages.push(`${prefix} ${text}`);
             }
           }
         }
@@ -355,9 +341,16 @@ async function getRecentMessages(sessionFilePath) {
 // ==================== EVENT HANDLERS ====================
 
 /**
- * Handle command:new — extract memories from ending session
+ * Shared session-extraction routine for both /new (onSessionEnd) and
+ * /stop|/clear|/exit (onSessionStop). They were ~95% identical; the only
+ * differences are which sessionEntry to read, the persisted tags +
+ * source-identifier, and the user-facing "done" message. Behaviour is
+ * otherwise identical — gateway-safe persistence via callCortex only.
+ *
+ * @param {object} event
+ * @param {{ sessionEntry: object, tags: string, sourceIdentifier: string, doneMessage: (n: number) => string }} opts
  */
-async function onSessionEnd(event) {
+async function runSessionExtraction(event, { sessionEntry, tags, sourceIdentifier, doneMessage }) {
   if (!(await isOpenClawAutoMemoryEnabled())) {
     if (!_autoMemoryNoticeShown) {
       console.log("[cortex-memory] Auto memory extraction disabled (set openclawAutoMemory=true to enable)");
@@ -367,7 +360,6 @@ async function onSessionEnd(event) {
   }
 
   const context = event.context || {};
-  const sessionEntry = context.previousSessionEntry || context.sessionEntry || {};
   const sessionFile = sessionEntry.sessionFile;
 
   if (!sessionFile) {
@@ -381,7 +373,22 @@ async function onSessionEnd(event) {
     return;
   }
 
-  const memories = extractMemories(messages);
+  const conversationText = assistantConversationText(messages);
+  if (conversationText.length === 0) {
+    console.log("[cortex-memory] No assistant content to extract");
+    return;
+  }
+
+  const extract = await loadOpenClawExtract();
+  if (!extract) {
+    if (!_noExtractNoticeShown) {
+      console.log("[cortex-memory] No resolvable local install — skipping auto-extraction (no fallback)");
+      _noExtractNoticeShown = true;
+    }
+    return;
+  }
+
+  const memories = extract.extractSessionMemories(conversationText);
   if (memories.length === 0) {
     console.log("[cortex-memory] No high-salience content found");
     return;
@@ -401,12 +408,13 @@ async function onSessionEnd(event) {
       title: mem.title,
       content: mem.content,
       category: mem.category,
+      memoryPurpose: mem.memoryPurpose,
       project: "openclaw",
       scope: "global",
-      importance: "high",
-      tags: "auto-extracted,openclaw-hook",
+      importance: "normal",
+      tags,
       sourceType: "hook",
-      sourceIdentifier: "openclaw-session-end",
+      sourceIdentifier,
       workspaceDir: context.workspaceDir || "",
     });
     if (result) {
@@ -420,79 +428,37 @@ async function onSessionEnd(event) {
 
   // Provide visible feedback to user
   if (saved > 0 && event.messages) {
-    event.messages.push(`🧠 ShieldCortex: Saved ${saved} memor${saved === 1 ? 'y' : 'ies'} from this session`);
+    event.messages.push(doneMessage(saved));
   }
 }
 
+/**
+ * Handle command:new — extract memories from ending session
+ */
+async function onSessionEnd(event) {
+  const context = event.context || {};
+  await runSessionExtraction(event, {
+    sessionEntry: context.previousSessionEntry || context.sessionEntry || {},
+    tags: "auto-extracted,openclaw-hook",
+    sourceIdentifier: "openclaw-session-end",
+    doneMessage: (n) =>
+      `🧠 ShieldCortex: Saved ${n} memor${n === 1 ? "y" : "ies"} from this session`,
+  });
+}
+
 /**
  * Handle command:stop — extract memories before session ends
  * This fires when user explicitly calls /stop
  */
 async function onSessionStop(event) {
-  if (!(await isOpenClawAutoMemoryEnabled())) {
-    if (!_autoMemoryNoticeShown) {
-      console.log("[cortex-memory] Auto memory extraction disabled (set openclawAutoMemory=true to enable)");
-      _autoMemoryNoticeShown = true;
-    }
-    return;
-  }
-
   const context = event.context || {};
-  const sessionEntry = context.sessionEntry || {};
-  const sessionFile = sessionEntry.sessionFile;
-
-  if (!sessionFile) {
-    console.log("[cortex-memory] No session file found for stop, skipping extraction");
-    return;
-  }
-
-  const messages = await getRecentMessages(sessionFile);
-  if (messages.length === 0) {
-    console.log("[cortex-memory] No messages to extract on stop");
-    return;
-  }
-
-  const memories = extractMemories(messages);
-  if (memories.length === 0) {
-    console.log("[cortex-memory] No high-salience content found on stop");
-    return;
-  }
-
-  const noveltyGate = await getSharedNoveltyGate();
-  let saved = 0;
-  let skipped = 0;
-  for (const mem of memories) {
-    const novelty = noveltyGate.inspect(mem.content);
-    if (!novelty.allow) {
-      skipped++;
-      continue;
-    }
-
-    const result = await callCortex("remember", {
-      title: mem.title,
-      content: mem.content,
-      category: mem.category,
-      project: "openclaw",
-      scope: "global",
-      importance: "high",
-      tags: "auto-extracted,openclaw-hook,session-stop",
-      sourceType: "hook",
-      sourceIdentifier: "openclaw-session-stop",
-      workspaceDir: context.workspaceDir || "",
-    });
-    if (result) {
-      saved++;
-      noveltyGate.remember(mem, novelty);
-    }
-  }
-  await noveltyGate.flush();
-
-  console.log(`[cortex-memory] Saved ${saved}/${memories.length} memories on session stop (${skipped} skipped as duplicates)`);
-  
-  // Provide visible feedback to user
-  if (saved > 0 && event.messages) {
-    event.messages.push(`🧠 ShieldCortex: Saved ${saved} memor${saved === 1 ? 'y' : 'ies'} before session end`);
-  }
+  await runSessionExtraction(event, {
+    sessionEntry: context.sessionEntry || {},
+    tags: "auto-extracted,openclaw-hook,session-stop",
+    sourceIdentifier: "openclaw-session-stop",
+    doneMessage: (n) =>
+      `🧠 ShieldCortex: Saved ${n} memor${n === 1 ? "y" : "ies"} before session end`,
+  });
 }
 
 /**
@@ -531,43 +497,54 @@ async function onBootstrap(event) {
 }
 
 /**
- * Keyword triggers with their categories and importance levels
- * Order matters: more specific triggers should come first
+ * Keyword trigger phrases. Order matters: more specific triggers should come
+ * first (the first match wins). Each entry carries the AUTHORITATIVE chunker
+ * extractorType for its phrase — the trigger phrase is the classification
+ * signal ("the fix was" → error-fix, "i prefer" → preference), so we pass it
+ * straight into extractKeywordMemory rather than re-guessing from content
+ * (which collapsed everything to `note`). Salience stays uniform across all
+ * triggers (importance:"normal" → 0.5, capped well under the wall); the old
+ * per-trigger category/importance fields are gone — they minted high/critical
+ * salience and mislabelled categories.
+ *
+ * extractorType must be one of the chunker's keys (EXTRACTOR_TO_CATEGORY /
+ * EXTRACTOR_TO_PURPOSE in extract-memorable-segments.mjs):
+ *   decision | error-fix | learning | architecture | preference | important-note
  */
 const KEYWORD_TRIGGERS = [
   // Learning triggers
-  { phrase: "lesson learned", category: "learning", importance: "high" },
-  { phrase: "i learned", category: "learning", importance: "normal" },
-  { phrase: "til:", category: "learning", importance: "normal" },
-  { phrase: "today i learned", category: "learning", importance: "normal" },
-  
+  { phrase: "lesson learned", extractorType: "learning" },
+  { phrase: "i learned", extractorType: "learning" },
+  { phrase: "til:", extractorType: "learning" },
+  { phrase: "today i learned", extractorType: "learning" },
+
   // Error/prevention triggers
-  { phrase: "never again", category: "error", importance: "critical" },
-  { phrase: "root cause was", category: "error", importance: "high" },
-  { phrase: "the fix was", category: "error", importance: "high" },
-  
+  { phrase: "never again", extractorType: "error-fix" },
+  { phrase: "root cause was", extractorType: "error-fix" },
+  { phrase: "the fix was", extractorType: "error-fix" },
+
   // Preference triggers
-  { phrase: "always do", category: "preference", importance: "high" },
-  { phrase: "never do", category: "preference", importance: "high" },
-  { phrase: "i prefer", category: "preference", importance: "normal" },
-  { phrase: "we should always", category: "preference", importance: "high" },
-  
+  { phrase: "always do", extractorType: "preference" },
+  { phrase: "never do", extractorType: "preference" },
+  { phrase: "i prefer", extractorType: "preference" },
+  { phrase: "we should always", extractorType: "preference" },
+
   // Architecture/decision triggers
-  { phrase: "we decided", category: "architecture", importance: "high" },
-  { phrase: "decision made", category: "architecture", importance: "high" },
-  { phrase: "going with", category: "architecture", importance: "normal" },
-  
-  // Explicit memory triggers (highest priority - always critical)
-  { phrase: "remember this", category: "note", importance: "critical" },
-  { phrase: "don't forget", category: "note", importance: "critical" },
-  { phrase: "dont forget", category: "note", importance: "critical" },
-  { phrase: "this is important", category: "note", importance: "critical" },
-  { phrase: "make a note", category: "note", importance: "critical" },
-  { phrase: "for the record", category: "note", importance: "critical" },
-  { phrase: "note to self", category: "note", importance: "critical" },
-  { phrase: "important:", category: "note", importance: "critical" },
-  { phrase: "key point:", category: "note", importance: "high" },
-  { phrase: "crucial:", category: "note", importance: "critical" },
+  { phrase: "we decided", extractorType: "decision" },
+  { phrase: "decision made", extractorType: "decision" },
+  { phrase: "going with", extractorType: "decision" },
+
+  // Explicit memory triggers (generic — important-note)
+  { phrase: "remember this", extractorType: "important-note" },
+  { phrase: "don't forget", extractorType: "important-note" },
+  { phrase: "dont forget", extractorType: "important-note" },
+  { phrase: "this is important", extractorType: "important-note" },
+  { phrase: "make a note", extractorType: "important-note" },
+  { phrase: "for the record", extractorType: "important-note" },
+  { phrase: "note to self", extractorType: "important-note" },
+  { phrase: "important:", extractorType: "important-note" },
+  { phrase: "key point:", extractorType: "important-note" },
+  { phrase: "crucial:", extractorType: "important-note" },
 ];
 
 /**
@@ -604,35 +581,62 @@ async function checkAndSaveKeywordTrigger(messageText, event) {
     content = messageText;
   }
 
-  const title = content.slice(0, 80).replace(/["\n]/g, " ").trim();
+  // Route through the chunker wrapper: applies the rejection corpus (drops true
+  // malformations) and derives category + memory_purpose from the chunker's
+  // taxonomy. Explicit keyword intent BYPASSES the salience threshold (B8) —
+  // the wrapper returns a memory for any non-malformed content.
+  const extract = await loadOpenClawExtract();
+  if (!extract) {
+    if (!_noExtractNoticeShown) {
+      console.log("[cortex-memory] No resolvable local install — skipping keyword capture (no fallback)");
+      _noExtractNoticeShown = true;
+    }
+    return false;
+  }
+
+  // The trigger phrase carries the authoritative classification — pass its
+  // extractorType so the wrapper pins category/purpose instead of re-guessing
+  // from content (which collapsed typed triggers to `note`).
+  const candidates = extract.extractKeywordMemory(content, matchedTrigger.extractorType);
+  if (candidates.length === 0) {
+    console.log(`[cortex-memory] Keyword trigger skipped (rejected as malformed): "${matchedTrigger.phrase}"`);
+    return false;
+  }
+  const mem = candidates[0];
 
   // Deduplicate via shared novelty gate (same gate used by session-end/stop extraction)
   const noveltyGate = await getSharedNoveltyGate();
-  const novelty = noveltyGate.inspect(content.slice(0, 500));
+  const novelty = noveltyGate.inspect(mem.content);
   if (!novelty.allow) {
-    console.log(`[cortex-memory] Keyword trigger skipped (duplicate): "${title}"`);
+    console.log(`[cortex-memory] Keyword trigger skipped (duplicate): "${mem.title}"`);
+    // M2: an EXPLICIT "remember this" must never be silently dropped — make the
+    // dedup decision visible even though we skip the duplicate store.
+    if (event.messages) {
+      event.messages.push(`🧠 Already remembered.`);
+    }
     return false;
   }
 
   const result = await callCortex("remember", {
-    title,
-    content: content.slice(0, 500),
-    category: matchedTrigger.category,
+    title: mem.title,
+    content: mem.content,
+    category: mem.category,
+    memoryPurpose: mem.memoryPurpose,
     project: "openclaw",
     scope: "global",
-    importance: matchedTrigger.importance,
+    importance: "normal",
     tags: `keyword-trigger,openclaw-hook,trigger:${matchedTrigger.phrase.replace(/\s+/g, "-")}`,
     sourceType: "hook",
     sourceIdentifier: `openclaw-keyword:${matchedTrigger.phrase.replace(/\s+/g, "-")}`,
   });
 
   if (result) {
-    noveltyGate.remember({ content: content.slice(0, 500), title, category: matchedTrigger.category }, novelty);
+    noveltyGate.remember({ content: mem.content, title: mem.title, category: mem.category }, novelty);
     await noveltyGate.flush();
     if (event.messages) {
-      event.messages.push(`✅ Saved to Cortex memory (${matchedTrigger.category}): "${title}"`);
+      event.messages.push(`✅ Saved to Cortex memory (${mem.category}): "${mem.title}"`);
     }
-    console.log(`[cortex-memory] Keyword trigger "${matchedTrigger.phrase}" saved: ${title}`);
+    console.log(`[cortex-memory] Keyword trigger "${matchedTrigger.phrase}" saved: ${mem.title}`);
     return true;
   }
   return false;
@@ -724,8 +728,11 @@ async function selfCheckAndHeal(event) {
     const { homedir } = await import("node:os");
     const home = homedir();
 
-    // Where am I running from?
-    const myDir = path.dirname(new URL(import.meta.url).pathname);
+    // Where am I running from? Use fileURLToPath, not URL.pathname — the latter
+    // does NOT decode percent-encoding, so an install path with spaces/special
+    // chars would yield a path that fails every downstream fs read (staleness
+    // comparison + self-heal copy below).
+    const myDir = path.dirname(fileURLToPath(import.meta.url));
 
     // Expected locations (newest first)
     const expectedDirs = [
@@ -761,6 +768,51 @@ async function selfCheckAndHeal(event) {
         }
       }
 
+      // Task 6b: staleness signal. The hook is installed by file-copy, so a
+      // package update can leave THIS running copy behind the packaged source
+      // (e.g. an OpenClaw version-lag where the global package is newer than
+      // the hook last copied into ~/.openclaw). Compare our running files
+      // against the package's hooks/openclaw/cortex-memory source by content.
+      //
+      // WARN-ONLY by design — we do NOT re-copy from inside the long-lived
+      // gateway. Re-copying would overwrite the very files this process is
+      // executing from, racing any concurrently-bootstrapping agent's jiti
+      // load. The real auto-refresh happens in the npm postinstall; the
+      // user-invoked repair is `shieldcortex openclaw install` (also surfaced
+      // by `shieldcortex doctor`). No DB, no persistence — pure fs reads.
+      try {
+        const root = await resolvePackageRoot();
+        if (root) {
+          const sourceDir = path.join(root, "hooks", "openclaw", "cortex-memory");
+          const hookFiles = ["HOOK.md", "handler.ts", "runtime.mjs"];
+          let stale = false;
+          for (const file of hookFiles) {
+            const srcPath = path.join(sourceDir, file);
+            const minePath = path.join(myDir, file);
+            try {
+              const srcBuf = await fs.readFile(srcPath);
+              const mineBuf = await fs.readFile(minePath);
+              if (!srcBuf.equals(mineBuf)) { stale = true; break; }
+            } catch {
+              // Source file missing/unreadable (can't prove staleness for it)
+              // or our own file unreadable — don't flip `stale` on a read error.
+              // DELIBERATE ASYMMETRY with src/setup/openclaw.ts `hookFilesStale`,
+              // which returns `true` (stale) on a read error so the doctor nags
+              // on a broken install. Here we stay quiet: this runs inside the
+              // long-lived gateway, where a transient read error must not emit a
+              // spurious bootstrap "out of date" warning. Keep them divergent.
+            }
+          }
+          if (stale) {
+            console.warn(
+              "[cortex-memory] Installed hook is OUT OF DATE — it differs from the " +
+              "packaged version. Run `shieldcortex openclaw install` to refresh it " +
+              "(then restart the gateway) so memory capture uses the latest logic."
+            );
+          }
+        }
+      } catch { /* staleness check is best-effort — never blocks bootstrap */ }
+
       return; // All good
     }