shieldcortex 2.20.1 → 3.0.1

package/dist/memory/types.d.ts

@@ -52,6 +52,27 @@ export interface SearchResult {
         title: string;
         score: number;
     }[];
+    explanation?: SearchExplanation;
+}
+export interface SearchScoreBreakdown {
+    ftsScore: number;
+    vectorSimilarity: number;
+    vectorBoost: number;
+    decayedScore: number;
+    priorityBoost: number;
+    recencyBoost: number;
+    categoryBoost: number;
+    linkBoost: number;
+    tagBoost: number;
+    activationBoost: number;
+    finalScore: number;
+    matchedTags: string[];
+    matchedCategory: string | null;
+}
+export interface SearchExplanation {
+    query: string;
+    reasons: string[];
+    breakdown: SearchScoreBreakdown;
 }
 export interface ConsolidationResult {
     consolidated: number;
@@ -95,4 +116,3 @@ export declare const DEFAULT_CONFIG: MemoryConfig;
  * Lower threshold = harder to delete (more valuable)
  */
 export declare const DELETION_THRESHOLDS: Record<MemoryCategory, number>;
-//# sourceMappingURL=types.d.ts.map

package/dist/memory/types.js

@@ -27,4 +27,3 @@ export const DELETION_THRESHOLDS = {
     todo: 0.25, // Todos - easier to delete
     custom: 0.22, // Custom memories
 };
-//# sourceMappingURL=types.js.map

package/dist/server.d.ts

@@ -9,4 +9,3 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * Create and configure the MCP server
  */
 export declare function createServer(dbPath?: string): McpServer;
-//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -992,4 +992,3 @@ Runs injection detection (40+ patterns) and credential leak scanning (25+ provid
     }, CONSOLIDATION_INTERVAL);
     return server;
 }
-//# sourceMappingURL=server.js.map

package/dist/service/install.d.ts

@@ -12,4 +12,3 @@ export declare function uninstallService(options?: {
 }): Promise<void>;
 export declare function serviceStatus(): Promise<void>;
 export declare function handleServiceCommand(subcommand: string): Promise<void>;
-//# sourceMappingURL=install.d.ts.map

package/dist/service/install.js

@@ -175,4 +175,3 @@ export async function handleServiceCommand(subcommand) {
             process.exit(1);
     }
 }
-//# sourceMappingURL=install.js.map

package/dist/service/templates.d.ts

@@ -10,4 +10,3 @@ export interface ServiceConfig {
 export declare function launchdPlist(config: ServiceConfig): string;
 export declare function systemdUnit(config: ServiceConfig): string;
 export declare function windowsVbs(config: ServiceConfig): string;
-//# sourceMappingURL=templates.d.ts.map

package/dist/service/templates.js

@@ -55,4 +55,3 @@ export function windowsVbs(config) {
     return `Set WshShell = CreateObject("WScript.Shell")
 WshShell.Run """${nodePath}"" ""${entryPoint}"" --mode dashboard", 0, False`;
 }
-//# sourceMappingURL=templates.js.map

package/dist/setup/claude-md.d.ts

@@ -11,4 +11,3 @@
 export declare function setupClaudeMd(options?: {
     stopHook?: boolean;
 }): Promise<void>;
-//# sourceMappingURL=claude-md.d.ts.map

package/dist/setup/claude-md.js

@@ -109,4 +109,3 @@ export async function setupClaudeMd(options) {
     }
     console.log('\nSetup complete.');
 }
-//# sourceMappingURL=claude-md.js.map

package/dist/setup/copilot.d.ts

@@ -9,4 +9,3 @@ export declare function installCopilot(): Promise<void>;
 export declare function uninstallCopilot(): Promise<void>;
 export declare function copilotStatus(): Promise<void>;
 export declare function handleCopilotCommand(subcommand: string): Promise<void>;
-//# sourceMappingURL=copilot.d.ts.map

package/dist/setup/copilot.js

@@ -287,4 +287,3 @@ export async function handleCopilotCommand(subcommand) {
             process.exit(1);
     }
 }
-//# sourceMappingURL=copilot.js.map

package/dist/setup/doctor.d.ts

@@ -2,4 +2,3 @@
  * `npx shieldcortex doctor` — diagnostic checks for Cortex installation health.
  */
 export declare function handleDoctorCommand(): Promise<void>;
-//# sourceMappingURL=doctor.d.ts.map

package/dist/setup/doctor.js

@@ -206,4 +206,3 @@ export async function handleDoctorCommand() {
     console.log(`\n${passed} passed, ${warns} warnings, ${fails} failed\n`);
     process.exit(fails > 0 ? 1 : 0);
 }
-//# sourceMappingURL=doctor.js.map

package/dist/setup/hooks.d.ts

@@ -6,4 +6,3 @@
  * Custom hooks: user-defined in ~/.shieldcortex/config.json → customHooks
  */
 export declare function handleHookCommand(hookName: string): Promise<void>;
-//# sourceMappingURL=hooks.d.ts.map

package/dist/setup/hooks.js

@@ -98,4 +98,3 @@ export async function handleHookCommand(hookName) {
     }
     process.exit(1);
 }
-//# sourceMappingURL=hooks.js.map

package/dist/setup/migrate.d.ts

@@ -37,4 +37,3 @@ export declare function migrateOpenClawHooks(): {
     cleanedLegacy: boolean;
 };
 export declare function handleMigrateCommand(): Promise<void>;
-//# sourceMappingURL=migrate.d.ts.map

package/dist/setup/migrate.js

@@ -378,4 +378,3 @@ export async function handleMigrateCommand() {
         console.log('\nRestart Claude Code to use the new configuration.');
     }
 }
-//# sourceMappingURL=migrate.js.map

package/dist/setup/openclaw.d.ts

@@ -16,4 +16,3 @@ export declare function installOpenClawHook(): Promise<void>;
 export declare function uninstallOpenClawHook(): Promise<void>;
 export declare function openClawHookStatus(): Promise<void>;
 export declare function handleOpenClawCommand(subcommand: string): Promise<void>;
-//# sourceMappingURL=openclaw.d.ts.map

package/dist/setup/openclaw.js

@@ -443,4 +443,3 @@ export async function handleOpenClawCommand(subcommand) {
             process.exit(1);
     }
 }
-//# sourceMappingURL=openclaw.js.map

package/dist/setup/quickstart.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Quickstart helper for the most common installation paths.
+ *
+ * `shieldcortex quickstart` is intentionally non-destructive by default:
+ * it detects likely environments and tells the user which single command
+ * to run next. Explicit targets perform the install.
+ */
+export declare function handleQuickstartCommand(target?: string): Promise<void>;

package/dist/setup/quickstart.js

@@ -0,0 +1,108 @@
+/**
+ * Quickstart helper for the most common installation paths.
+ *
+ * `shieldcortex quickstart` is intentionally non-destructive by default:
+ * it detects likely environments and tells the user which single command
+ * to run next. Explicit targets perform the install.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { setupClaudeMd } from './claude-md.js';
+import { handleOpenClawCommand } from './openclaw.js';
+import { handleCopilotCommand } from './copilot.js';
+function detectEnvironment() {
+    const home = os.homedir();
+    const platform = process.platform;
+    const claude = fs.existsSync(path.join(home, '.claude')) ||
+        fs.existsSync(path.join(home, '.claude.json'));
+    const openclaw = fs.existsSync(path.join(home, '.openclaw'));
+    const cursor = fs.existsSync(path.join(home, '.cursor'));
+    const vscodeDirs = platform === 'darwin'
+        ? [
+            path.join(home, 'Library', 'Application Support', 'Code', 'User'),
+            path.join(home, 'Library', 'Application Support', 'Code - Insiders', 'User'),
+        ]
+        : platform === 'win32'
+            ? [
+                path.join(process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming'), 'Code', 'User'),
+                path.join(process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming'), 'Code - Insiders', 'User'),
+            ]
+            : [
+                path.join(home, '.config', 'Code', 'User'),
+                path.join(home, '.config', 'Code - Insiders', 'User'),
+            ];
+    const copilot = cursor || vscodeDirs.some((dir) => fs.existsSync(dir));
+    return { claude, openclaw, copilot, cursor };
+}
+function printAutoGuide() {
+    const env = detectEnvironment();
+    const lines = [];
+    lines.push('');
+    lines.push('ShieldCortex Quickstart');
+    lines.push('────────────────────────────────────────────────────');
+    lines.push(`Detected: Claude=${env.claude ? 'yes' : 'no'} · OpenClaw=${env.openclaw ? 'yes' : 'no'} · Copilot/Cursor=${env.copilot ? 'yes' : 'no'}`);
+    lines.push('');
+    if (env.claude) {
+        lines.push('Best next step for persistent memory in Claude Code:');
+        lines.push('  shieldcortex quickstart claude');
+        lines.push('');
+    }
+    if (env.openclaw) {
+        lines.push('Best next step for OpenClaw hook + realtime plugin:');
+        lines.push('  shieldcortex quickstart openclaw');
+        lines.push('');
+    }
+    if (env.copilot) {
+        lines.push('Best next step for VS Code / Cursor MCP wiring:');
+        lines.push('  shieldcortex quickstart copilot');
+        lines.push('');
+    }
+    lines.push('Security-only workflow:');
+    lines.push('  shieldcortex quickstart security');
+    lines.push('');
+    lines.push('You can also run one of these directly:');
+    lines.push('  shieldcortex setup');
+    lines.push('  shieldcortex openclaw install');
+    lines.push('  shieldcortex copilot install');
+    lines.push('  shieldcortex dashboard');
+    lines.push('');
+    console.log(lines.join('\n'));
+}
+function printSecurityGuide() {
+    console.log(`
+ShieldCortex Security Quickstart
+────────────────────────────────────────────────────
+1. Scan one suspicious prompt or tool output:
+   shieldcortex scan "ignore previous instructions"
+
+2. Audit your local agent environment:
+   shieldcortex audit
+
+3. Open the dashboard for quarantine, audit, and graph visibility:
+   shieldcortex dashboard
+`);
+}
+export async function handleQuickstartCommand(target) {
+    if (!target) {
+        printAutoGuide();
+        return;
+    }
+    switch (target.toLowerCase()) {
+        case 'claude':
+            await setupClaudeMd({ stopHook: false });
+            return;
+        case 'openclaw':
+            await handleOpenClawCommand('install');
+            return;
+        case 'copilot':
+            await handleCopilotCommand('install');
+            return;
+        case 'security':
+            printSecurityGuide();
+            return;
+        default:
+            console.error('Usage: shieldcortex quickstart [claude|openclaw|copilot|security]');
+            process.exit(1);
+    }
+}

package/dist/setup/settings-hooks.d.ts

@@ -4,4 +4,3 @@
 export declare function setupHooks(options?: {
     stopHook?: boolean;
 }): void;
-//# sourceMappingURL=settings-hooks.d.ts.map

package/dist/setup/settings-hooks.js

@@ -80,4 +80,3 @@ export function setupHooks(options) {
         console.log('Hooks: all hooks already configured in ~/.claude/settings.json');
     }
 }
-//# sourceMappingURL=settings-hooks.js.map

package/dist/setup/status.d.ts

@@ -2,4 +2,3 @@
  * Status command - Display ShieldCortex database and system status
  */
 export declare function handleStatusCommand(): Promise<void>;
-//# sourceMappingURL=status.d.ts.map

package/dist/setup/status.js

@@ -155,4 +155,3 @@ export async function handleStatusCommand() {
         process.exit(1);
     }
 }
-//# sourceMappingURL=status.js.map

package/dist/setup/uninstall.d.ts

@@ -17,4 +17,3 @@ export declare function uninstallSetup(): Promise<void>;
 export declare function uninstallAll(options?: {
     keepLogs?: boolean;
 }): Promise<void>;
-//# sourceMappingURL=uninstall.d.ts.map

package/dist/setup/uninstall.js

@@ -196,4 +196,3 @@ export async function uninstallAll(options) {
     console.log('  npx cache clean shieldcortex  (npm 9+)');
     console.log('  rm -rf ~/.npm/_npx             (older npm)\n');
 }
-//# sourceMappingURL=uninstall.js.map

package/dist/tools/context.d.ts

@@ -150,4 +150,3 @@ export declare function executeImport(input: {
     imported?: number;
     error?: string;
 };
-//# sourceMappingURL=context.d.ts.map

package/dist/tools/context.js

@@ -276,4 +276,3 @@ export function executeImport(input) {
         };
     }
 }
-//# sourceMappingURL=context.js.map

package/dist/tools/forget.d.ts

@@ -68,4 +68,3 @@ export declare function executeForget(input: ForgetInput): Promise<{
  * Format the forget result for MCP response
  */
 export declare function formatForgetResult(result: Awaited<ReturnType<typeof executeForget>>): string;
-//# sourceMappingURL=forget.d.ts.map

package/dist/tools/forget.js

@@ -187,4 +187,3 @@ export function formatForgetResult(result) {
         deleted,
     ].join('\n');
 }
-//# sourceMappingURL=forget.js.map

package/dist/tools/graph.d.ts

@@ -43,4 +43,3 @@ export declare function handleGraphExplain(args: {
         text: string;
     }[];
 };
-//# sourceMappingURL=graph.d.ts.map

package/dist/tools/graph.js

@@ -203,4 +203,3 @@ export function handleGraphExplain(args) {
     }
     return mcpText({ paths: [{ hops }], sourceMemories });
 }
-//# sourceMappingURL=graph.js.map

package/dist/tools/recall.d.ts

@@ -114,4 +114,3 @@ export declare function executeGetMemory(input: {
     memory?: Memory;
     error?: string;
 };
-//# sourceMappingURL=recall.d.ts.map

package/dist/tools/recall.js

@@ -72,6 +72,7 @@ export async function executeRecall(input) {
                             limit: input.limit,
                             project: projectFilter,
                             threshold: 0.3,
+                            existingResults: results,
                         });
                         // Merge: keep FTS results, add new embedding results
                         const existingIds = new Set(memories.map(m => m.id));
@@ -186,4 +187,3 @@ export function executeGetMemory(input) {
         };
     }
 }
-//# sourceMappingURL=recall.js.map

package/dist/tools/remember.d.ts

@@ -80,4 +80,3 @@ export declare function executeRemember(input: RememberInput): Promise<{
  * Format the remember result for MCP response
  */
 export declare function formatRememberResult(result: Awaited<ReturnType<typeof executeRemember>>): string;
-//# sourceMappingURL=remember.d.ts.map

package/dist/tools/remember.js

@@ -163,4 +163,3 @@ export function formatRememberResult(result) {
     }
     return lines.join('\n');
 }
-//# sourceMappingURL=remember.js.map

package/dist/worker/brain-worker.d.ts

@@ -19,6 +19,7 @@ import { WorkerConfig, LightTickResult, MediumTickResult, WorkerStatus } from '.
 export declare class BrainWorker {
     private lightTimer;
     private mediumTimer;
+    private initialLightTickTimer;
     private isRunning;
     private config;
     private stats;
@@ -97,4 +98,3 @@ export declare function startDefaultWorker(): BrainWorker;
  * Stop the default worker
  */
 export declare function stopDefaultWorker(): void;
-//# sourceMappingURL=brain-worker.d.ts.map

package/dist/worker/brain-worker.js

@@ -31,6 +31,7 @@ import { isFeatureEnabled } from '../license/gate.js';
 export class BrainWorker {
     lightTimer = null;
     mediumTimer = null;
+    initialLightTickTimer = null;
     isRunning = false;
     config;
     // Statistics tracking
@@ -66,8 +67,10 @@ export class BrainWorker {
         console.log(`[BrainWorker] Medium tick interval: ${this.config.mediumTickIntervalMs / 1000}s`);
         // Light tick every 5 minutes (by default)
         this.lightTimer = setInterval(() => this.lightTick(), this.config.lightTickIntervalMs);
+        this.lightTimer.unref();
         // Medium tick every 30 minutes (by default)
         this.mediumTimer = setInterval(() => this.mediumTick(), this.config.mediumTickIntervalMs);
+        this.mediumTimer.unref();
         // Apply cached cloud Iron Dome patterns immediately on start (requires Pro+)
         if (isFeatureEnabled('custom_injection_patterns')) {
             try {
@@ -79,11 +82,12 @@ export class BrainWorker {
         }
         // Run initial light tick after a short delay (10 seconds)
         // This allows the server to fully initialize first
-        setTimeout(() => {
+        this.initialLightTickTimer = setTimeout(() => {
             if (this.isRunning) {
                 this.lightTick();
             }
         }, 10000);
+        this.initialLightTickTimer.unref();
     }
     /**
      * Stop the background worker
@@ -103,6 +107,10 @@ export class BrainWorker {
             clearInterval(this.mediumTimer);
             this.mediumTimer = null;
         }
+        if (this.initialLightTickTimer) {
+            clearTimeout(this.initialLightTickTimer);
+            this.initialLightTickTimer = null;
+        }
         console.log('[BrainWorker] Stopped');
     }
     /**
@@ -332,4 +340,3 @@ export function stopDefaultWorker() {
         defaultWorker.stop();
     }
 }
-//# sourceMappingURL=brain-worker.js.map

package/dist/worker/link-discovery.d.ts

@@ -44,4 +44,3 @@ export declare function getLinkCoverageStats(): {
     memoriesWithoutLinks: number;
     averageLinksPerMemory: number;
 };
-//# sourceMappingURL=link-discovery.d.ts.map

package/dist/worker/link-discovery.js

@@ -100,4 +100,3 @@ export function getLinkCoverageStats() {
             : 0,
     };
 }
-//# sourceMappingURL=link-discovery.js.map

package/dist/worker/predictive-consolidation.d.ts

@@ -43,4 +43,3 @@ export declare function getMemoryPressure(stats: MemoryStats, config: WorkerConf
     isCritical: boolean;
     recommendation: string;
 };
-//# sourceMappingURL=predictive-consolidation.d.ts.map

package/dist/worker/predictive-consolidation.js

@@ -107,4 +107,3 @@ export function getMemoryPressure(stats, config) {
         recommendation,
     };
 }
-//# sourceMappingURL=predictive-consolidation.js.map

package/dist/worker/types.d.ts

@@ -88,4 +88,3 @@ export interface PredictiveDecision {
     /** Urgency level of the consolidation need */
     urgency: 'low' | 'medium' | 'high' | 'critical';
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/worker/types.js

@@ -19,4 +19,3 @@ export const DEFAULT_WORKER_CONFIG = {
     contradictionScanLimit: 50,
     highActivityThreshold: 5,
 };
-//# sourceMappingURL=types.js.map

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

@@ -32,7 +32,8 @@ async function loadShieldConfig() {
 
 async function isOpenClawAutoMemoryEnabled() {
   const config = await loadShieldConfig();
-  return config?.openclawAutoMemory !== false;
+  // Default OFF — OpenClaw has its own memory system. User must explicitly opt in.
+  return config?.openclawAutoMemory === true;
 }
 
 /**
@@ -79,6 +80,15 @@ async function resolveServerCmd() {
 
 // ==================== CORTEX MCP HELPER ====================
 
+let _lastCallErrorType = null;
+
+function classifyCallError(err) {
+  if (err.killed || err.code === "ETIMEDOUT" || err.signal === "SIGTERM") return "timeout";
+  if (/ENOENT|not found|command not found/i.test(err.message || "")) return "not-found";
+  if (/mcporter/i.test(err.message || "")) return "mcporter";
+  return "unknown";
+}
+
 /**
  * Call a ShieldCortex MCP tool via mcporter
  * @param {string} tool - Tool name (e.g., "remember", "recall", "get_context")
@@ -121,8 +131,24 @@ async function callCortex(tool, args = {}, options = { retries: 1, timeout: 1500
             return;
           }
 
-          console.error(`[cortex-memory] ${errorType} on ${tool} after ${attempts} attempt(s):`, err.message);
-          if (err.code) console.error(`[cortex-memory] Error code: ${err.code}`);
+          // One-time categorised warning per error type (prevents spam)
+          const category = classifyCallError(err);
+          if (category !== _lastCallErrorType) {
+            _lastCallErrorType = category;
+            switch (category) {
+              case "timeout":
+                console.warn("[cortex-memory] ShieldCortex call timed out (15s). Memory may be under heavy load.");
+                break;
+              case "not-found":
+                console.warn("[cortex-memory] ShieldCortex binary not found. Run: npm install -g shieldcortex");
+                break;
+              case "mcporter":
+                console.warn("[cortex-memory] mcporter failed to reach ShieldCortex MCP server. Is it configured?");
+                break;
+              default:
+                console.warn(`[cortex-memory] ShieldCortex call failed: ${err.message}`);
+            }
+          }
           resolve(null);
           return;
         }
@@ -278,6 +304,21 @@ async function createNoveltyGate() {
   };
 }
 
+// ==================== SHARED NOVELTY GATE ====================
+
+/**
+ * Process-level shared novelty gate for ALL save paths (session-end, session-stop, keyword triggers).
+ * Avoids redundant disk round-trips and ensures cross-path deduplication.
+ */
+let _sharedNoveltyGate = null;
+
+async function getSharedNoveltyGate() {
+  if (!_sharedNoveltyGate) {
+    _sharedNoveltyGate = await createNoveltyGate();
+  }
+  return _sharedNoveltyGate;
+}
+
 // ==================== HOOK SCANNER ====================
 
 /**
@@ -357,7 +398,10 @@ const PATTERNS = {
     /\b(?:TIL|today\s+I\s+learned)\b/i,
   ],
   preference: [
-    /\b(?:always|never|prefer|don't\s+like|should\s+always)\b/i,
+    /\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,
@@ -474,7 +518,7 @@ async function onSessionEnd(event) {
     return;
   }
 
-  const noveltyGate = await createNoveltyGate();
+  const noveltyGate = await getSharedNoveltyGate();
   let saved = 0;
   let skipped = 0;
   for (const mem of memories) {
@@ -501,7 +545,7 @@ async function onSessionEnd(event) {
   await noveltyGate.flush();
 
   console.log(`[cortex-memory] Saved ${saved}/${memories.length} memories from session (${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'} from this session`);
@@ -542,7 +586,7 @@ async function onSessionStop(event) {
     return;
   }
 
-  const noveltyGate = await createNoveltyGate();
+  const noveltyGate = await getSharedNoveltyGate();
   let saved = 0;
   let skipped = 0;
   for (const mem of memories) {
@@ -679,7 +723,7 @@ async function checkAndSaveKeywordTrigger(messageText, event) {
 
   // Extract content after the trigger phrase
   let content = messageText.slice(matchIdx + matchedTrigger.phrase.length).replace(/^[:\s]+/, "").trim();
-  
+
   // If content is too short, use the whole message as context
   if (content.length < 5) {
     content = messageText;
@@ -687,6 +731,14 @@ async function checkAndSaveKeywordTrigger(messageText, event) {
 
   const title = content.slice(0, 80).replace(/["\n]/g, " ").trim();
 
+  // 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));
+  if (!novelty.allow) {
+    console.log(`[cortex-memory] Keyword trigger skipped (duplicate): "${title}"`);
+    return false;
+  }
+
   const result = await callCortex("remember", {
     title,
     content: content.slice(0, 500),
@@ -698,6 +750,8 @@ async function checkAndSaveKeywordTrigger(messageText, event) {
   });
 
   if (result) {
+    noveltyGate.remember({ content: content.slice(0, 500), title, category: matchedTrigger.category }, novelty);
+    await noveltyGate.flush();
     if (event.messages) {
       event.messages.push(`✅ Saved to Cortex memory (${matchedTrigger.category}): "${title}"`);
     }