shieldcortex 2.20.0 → 3.0.0

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

@@ -1,6 +1,8 @@
 /**
  * CLI handler for hook subcommands.
  * Spawns the actual hook scripts with stdin/stdout passthrough.
+ *
+ * Built-in hooks: pre-compact, session-start, session-end, stop
+ * 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

@@ -1,36 +1,100 @@
 /**
  * CLI handler for hook subcommands.
  * Spawns the actual hook scripts with stdin/stdout passthrough.
+ *
+ * Built-in hooks: pre-compact, session-start, session-end, stop
+ * Custom hooks: user-defined in ~/.shieldcortex/config.json → customHooks
  */
 import { spawn } from 'child_process';
 import path from 'path';
+import fs from 'fs';
+import os from 'os';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Scripts are in ../scripts/ relative to dist/setup/
 const SCRIPTS_DIR = path.resolve(__dirname, '..', '..', 'scripts');
-const HOOKS = {
+const BUILT_IN_HOOKS = {
     'pre-compact': 'pre-compact-hook.mjs',
     'session-start': 'session-start-hook.mjs',
     'session-end': 'session-end-hook.mjs',
     'stop': 'stop-hook.mjs',
 };
-export async function handleHookCommand(hookName) {
-    const scriptFile = HOOKS[hookName];
-    if (!scriptFile) {
-        console.error(`Unknown hook: ${hookName}`);
-        console.log(`Available hooks: ${Object.keys(HOOKS).join(', ')}`);
-        console.log('Usage: shieldcortex hook <pre-compact|session-start|session-end|stop>');
-        process.exit(1);
+function loadCustomHooks() {
+    try {
+        const configPath = path.join(os.homedir(), '.shieldcortex', 'config.json');
+        if (!fs.existsSync(configPath))
+            return {};
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        if (!config.customHooks || typeof config.customHooks !== 'object')
+            return {};
+        return config.customHooks;
+    }
+    catch {
+        return {};
     }
-    const scriptPath = path.join(SCRIPTS_DIR, scriptFile);
-    const child = spawn(process.execPath, [scriptPath], {
+}
+function runScript(scriptPath, args = []) {
+    const child = spawn(process.execPath, [scriptPath, ...args], {
         stdio: ['pipe', 'inherit', 'inherit'],
     });
-    // Pipe stdin through to the child
     process.stdin.pipe(child.stdin);
     child.on('exit', (code) => {
         process.exit(code ?? 0);
     });
 }
-//# sourceMappingURL=hooks.js.map
+function runCommand(command, args = []) {
+    const child = spawn(command, args, {
+        stdio: ['pipe', 'inherit', 'inherit'],
+        shell: true,
+    });
+    process.stdin.pipe(child.stdin);
+    child.on('exit', (code) => {
+        process.exit(code ?? 0);
+    });
+}
+export async function handleHookCommand(hookName) {
+    // Try built-in hooks first
+    const scriptFile = BUILT_IN_HOOKS[hookName];
+    if (scriptFile) {
+        const scriptPath = path.join(SCRIPTS_DIR, scriptFile);
+        runScript(scriptPath);
+        return;
+    }
+    // Try custom hooks from config
+    const customHooks = loadCustomHooks();
+    const custom = customHooks[hookName];
+    if (custom) {
+        const cmd = custom.command;
+        const args = custom.args || [];
+        // If it's a .mjs/.js file, run with Node
+        if (cmd.endsWith('.mjs') || cmd.endsWith('.js')) {
+            const resolved = cmd.startsWith('/') || cmd.startsWith('~')
+                ? cmd.replace(/^~/, os.homedir())
+                : path.resolve(cmd);
+            runScript(resolved, args);
+        }
+        else {
+            // Run as shell command
+            runCommand(cmd, args);
+        }
+        return;
+    }
+    // Nothing matched
+    const customNames = Object.keys(customHooks);
+    const allHooks = [...Object.keys(BUILT_IN_HOOKS), ...customNames];
+    console.error(`Unknown hook: ${hookName}`);
+    console.log(`Available hooks: ${allHooks.join(', ')}`);
+    if (customNames.length === 0) {
+        console.log('\nTo register custom hooks, add to ~/.shieldcortex/config.json:');
+        console.log(JSON.stringify({
+            customHooks: {
+                'instructions-loaded': {
+                    command: '~/.claude/hooks/instructions-loaded.mjs',
+                    description: 'Run on InstructionsLoaded event',
+                },
+            },
+        }, null, 2));
+    }
+    process.exit(1);
+}

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