shieldcortex 4.12.14 → 4.13.1

package/dist/cli/doctor.js

@@ -197,6 +197,93 @@ async function checkMemoryStats() {
         return { label: 'Memories', status: 'warn', message: `check failed — ${msg}` };
     }
 }
+// ── Check 3b: Write-path smoke test ───────────────────────
+/**
+ * The honest "is it working?" check.
+ *
+ * Doctor checks have historically gone green while writes were silently
+ * failing (v4.12.4 path-encoding bug, v4.12.5 NOT NULL UUID schema gap).
+ * The pattern: schema introspection passed (columns existed) but actual
+ * INSERTs threw constraint violations during real workloads.
+ *
+ * This check does a real round-trip — INSERT a tagged probe memory,
+ * SELECT it back, DELETE it. If any step fails, doctor reports the
+ * actual error string instead of "all green". The probe is tagged with
+ * a unique source identifier so it can never be confused with real data
+ * and gets deleted at the end of the check.
+ */
+/**
+ * Pure helper for the write-path round-trip. Exported so tests can
+ * exercise it against any database path (in-memory or temp file)
+ * without going through doctor's homedir-derived getDbPath().
+ */
+export function runWritePathProbe(dbPath) {
+    if (!fs.existsSync(dbPath)) {
+        return { label: 'Write path', status: 'warn', message: 'skipped (no database)' };
+    }
+    let db = null;
+    const probeUuid = `doctor-probe-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    const probeTitle = '__shieldcortex_doctor_probe__';
+    try {
+        const Database = require('better-sqlite3');
+        db = new Database(dbPath);
+        // INSERT — exercises NOT NULL columns + CHECK constraints. The schema
+        // adds these silently across versions; an INSERT against a stale schema
+        // is the exact failure mode v4.12.5 had.
+        db.prepare(`
+      INSERT INTO memories (uuid, type, category, title, content, salience, source, capture_method)
+      VALUES (?, 'short_term', 'note', ?, 'doctor probe — safe to delete', 0.01, 'cli:doctor', 'doctor-probe')
+    `).run(probeUuid, probeTitle);
+        // SELECT — exercises the FTS5 + index path
+        const row = db.prepare('SELECT id, title FROM memories WHERE uuid = ?').get(probeUuid);
+        if (!row || row.title !== probeTitle) {
+            return {
+                label: 'Write path',
+                status: 'fail',
+                message: 'wrote a probe row but could not read it back',
+                fix: 'Database may be corrupted. Run `shieldcortex consolidate` then re-run doctor.',
+            };
+        }
+        // DELETE — exercises the cascade triggers (FTS5 cleanup)
+        const deleteResult = db.prepare('DELETE FROM memories WHERE uuid = ?').run(probeUuid);
+        if (deleteResult.changes !== 1) {
+            return {
+                label: 'Write path',
+                status: 'warn',
+                message: `probe row written + read OK but delete affected ${deleteResult.changes} rows (expected 1)`,
+                fix: 'Manual cleanup may be needed. Check ~/.shieldcortex/memories.db for orphaned rows.',
+            };
+        }
+        return { label: 'Write path', status: 'pass', message: 'INSERT/SELECT/DELETE round-trip OK' };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Best-effort cleanup so we don't leave probe rows behind on a partial failure
+        if (db) {
+            try {
+                db.prepare('DELETE FROM memories WHERE uuid = ?').run(probeUuid);
+            }
+            catch { /* ignore */ }
+        }
+        return {
+            label: 'Write path',
+            status: 'fail',
+            message: `round-trip failed — ${msg}`,
+            fix: 'This is the smoking gun for a stale schema or migration drift. Try restarting the MCP server (auto-migrates), or re-install: shieldcortex install',
+        };
+    }
+    finally {
+        if (db) {
+            try {
+                db.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+async function checkWritePath() {
+    return runWritePathProbe(getDbPath());
+}
 // ── Check 4: Hook installation ────────────────────────────
 async function checkHooks() {
     const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
@@ -251,6 +338,90 @@ async function checkHooks() {
         return { label: 'Hooks', status: 'warn', message: `check failed — ${msg}` };
     }
 }
+// ── Check 4b: Auto-memory hook gates ──────────────────────
+/**
+ * Surfaces the resolved on/off state of the opt-in Stop and SessionEnd
+ * auto-memory hooks. Pre-v4.13.1 these were triple-gated (install flag,
+ * runtime config, sampling) with the runtime gate failing silently —
+ * users who wired the hook saw zero captures and zero feedback (#41).
+ *
+ * The check looks at both layers:
+ *   - settings.json: is the hook wired so Claude Code will fire it?
+ *   - autoMemory.enableStop / enableSessionEnd: will the hook actually run?
+ *
+ * Both layers must agree for the hook to do work. v4.13.1 onwards, the
+ * install flag flips both — if they disagree here, the user edited one
+ * side by hand and should re-run setup.
+ */
+export async function checkAutoMemoryHooks() {
+    const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+    let wiredStop = false;
+    let wiredSessionEnd = false;
+    try {
+        if (fs.existsSync(settingsPath)) {
+            const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            const hooks = settings?.hooks || {};
+            const isCortexWired = (entries) => Array.isArray(entries) && entries.some((entry) => Array.isArray(entry?.hooks) && entry.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('shieldcortex')));
+            wiredStop = isCortexWired(hooks.Stop);
+            wiredSessionEnd = isCortexWired(hooks.SessionEnd);
+        }
+    }
+    catch { /* fall through — both stay false, user gets a clean info row */ }
+    // Lazy-import to avoid pulling cloud/config into doctor's static graph
+    // when the user hasn't configured anything yet.
+    let gateStop = false;
+    let gateSessionEnd = false;
+    let samplingTurns = 10;
+    try {
+        const cfg = await import('../cloud/config.js');
+        const enable = cfg.getAutoMemoryEnableConfig();
+        gateStop = enable.enableStop;
+        gateSessionEnd = enable.enableSessionEnd;
+        const raw = cfg.readRawConfig();
+        const am = raw.autoMemory && typeof raw.autoMemory === 'object'
+            ? raw.autoMemory
+            : {};
+        if (typeof am.stopHookSamplingTurns === 'number' && am.stopHookSamplingTurns > 0) {
+            samplingTurns = Math.floor(am.stopHookSamplingTurns);
+        }
+    }
+    catch { /* defaults already set */ }
+    const rowFor = (label, wired, gate, flag, extra) => {
+        if (!wired && !gate) {
+            return {
+                label,
+                status: 'info',
+                message: 'opt-in (not installed)',
+            };
+        }
+        if (wired && gate) {
+            return {
+                label,
+                status: 'pass',
+                message: extra ? `enabled (${extra})` : 'enabled',
+            };
+        }
+        if (wired && !gate) {
+            return {
+                label,
+                status: 'warn',
+                message: 'wired in settings.json but runtime gate is off — hook will exit silently every turn',
+                fix: `Run \`shieldcortex setup ${flag}\` to flip the gate, or set autoMemory.enableStop/enableSessionEnd=true in ~/.shieldcortex/config.json`,
+            };
+        }
+        // gate && !wired
+        return {
+            label,
+            status: 'warn',
+            message: 'runtime gate is on but hook is not wired in settings.json — hook will never fire',
+            fix: `Run \`shieldcortex setup ${flag}\` to wire the hook`,
+        };
+    };
+    return [
+        rowFor('Auto-memory: Stop hook', wiredStop, gateStop, '--with-stop-hook', `samples turn % ${samplingTurns} == 0`),
+        rowFor('Auto-memory: SessionEnd hook', wiredSessionEnd, gateSessionEnd, '--with-session-end'),
+    ];
+}
 // ── Check 5: Process check ────────────────────────────────
 async function checkProcesses() {
     const results = [];
@@ -498,8 +669,10 @@ export async function runDoctor() {
     const checks = [
         checkDatabase,
         checkSchema,
+        checkWritePath, // Smoke test: real INSERT/SELECT/DELETE round-trip — catches silent schema drift
         checkMemoryStats,
         checkHooks,
+        checkAutoMemoryHooks,
         checkProcesses,
         checkDiskUsage,
         checkLockFile,

package/dist/cli/migrate-legacy.d.ts

@@ -0,0 +1,28 @@
+interface MigrateOptions {
+    /** Source legacy DB paths to import from. Defaults to both ~/.claude-memory/ and ~/.claude-cortex/ */
+    sources?: string[];
+    /** Target DB path. Default ~/.shieldcortex/memories.db */
+    target?: string;
+    /** If true, count + report only — no writes. */
+    dryRun?: boolean;
+}
+interface SourceReport {
+    path: string;
+    exists: boolean;
+    memoriesFound: number;
+    memoriesImported: number;
+    linksFound: number;
+    linksImported: number;
+    linksSkipped: number;
+    error?: string;
+}
+interface MigrationReport {
+    target: string;
+    dryRun: boolean;
+    sources: SourceReport[];
+    totalMemories: number;
+    totalLinks: number;
+}
+export declare function migrateLegacy(options?: MigrateOptions): MigrationReport;
+export declare function handleMemoriesCommand(args: string[]): Promise<void>;
+export {};

package/dist/cli/migrate-legacy.js

@@ -0,0 +1,291 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { randomUUID } from 'crypto';
+import Database from 'better-sqlite3';
+const DEFAULT_LEGACY_SOURCES = [
+    path.join(os.homedir(), '.claude-cortex', 'memories.db'),
+    path.join(os.homedir(), '.claude-memory', 'memories.db'),
+];
+const DEFAULT_TARGET = path.join(os.homedir(), '.shieldcortex', 'memories.db');
+function migrateOne(sourcePath, target, dryRun) {
+    const report = {
+        path: sourcePath,
+        exists: false,
+        memoriesFound: 0,
+        memoriesImported: 0,
+        linksFound: 0,
+        linksImported: 0,
+        linksSkipped: 0,
+    };
+    if (!fs.existsSync(sourcePath))
+        return report;
+    report.exists = true;
+    let source;
+    try {
+        source = new Database(sourcePath, { readonly: true, fileMustExist: true });
+        const memories = source
+            .prepare(`
+        SELECT id, type, category, title, content, project, tags, salience,
+               decayed_score, access_count, last_accessed, created_at,
+               metadata, embedding, scope, transferable
+        FROM memories
+      `)
+            .all();
+        const links = source
+            .prepare(`
+        SELECT source_id, target_id, relationship, strength, created_at
+        FROM memory_links
+      `)
+            .all();
+        report.memoriesFound = memories.length;
+        report.linksFound = links.length;
+        if (dryRun)
+            return report;
+        const insertMemory = target.prepare(`
+      INSERT INTO memories (
+        uuid, type, category, title, content, project, tags, salience,
+        decayed_score, access_count, last_accessed, created_at, updated_at,
+        metadata, embedding, scope, transferable, source, source_kind, capture_method
+      ) VALUES (
+        @uuid, @type, @category, @title, @content, @project, @tags, @salience,
+        @decayed_score, @access_count, @last_accessed, @created_at, @updated_at,
+        @metadata, @embedding, @scope, @transferable, @source, @source_kind, @capture_method
+      )
+    `);
+        const insertLink = target.prepare(`
+      INSERT OR IGNORE INTO memory_links (source_id, target_id, relationship, strength, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        const sourceLabel = path.basename(path.dirname(sourcePath));
+        const idMap = new Map();
+        const txn = target.transaction(() => {
+            for (const row of memories) {
+                const result = insertMemory.run({
+                    uuid: randomUUID(),
+                    type: row.type,
+                    category: row.category,
+                    title: row.title,
+                    content: row.content,
+                    project: row.project,
+                    tags: row.tags ?? '[]',
+                    salience: row.salience ?? 0.5,
+                    decayed_score: row.decayed_score,
+                    access_count: row.access_count ?? 0,
+                    last_accessed: row.last_accessed,
+                    created_at: row.created_at,
+                    updated_at: row.created_at,
+                    metadata: row.metadata ?? '{}',
+                    embedding: row.embedding,
+                    scope: row.scope ?? 'project',
+                    transferable: row.transferable ?? 0,
+                    source: `legacy:${sourceLabel}`,
+                    source_kind: 'legacy-import',
+                    capture_method: 'legacy-migrate',
+                });
+                idMap.set(row.id, Number(result.lastInsertRowid));
+                report.memoriesImported++;
+            }
+            for (const link of links) {
+                const newSource = idMap.get(link.source_id);
+                const newTarget = idMap.get(link.target_id);
+                if (newSource === undefined || newTarget === undefined) {
+                    report.linksSkipped++;
+                    continue;
+                }
+                const linkResult = insertLink.run(newSource, newTarget, link.relationship, link.strength ?? 0.5, link.created_at);
+                if (linkResult.changes > 0)
+                    report.linksImported++;
+                else
+                    report.linksSkipped++;
+            }
+        });
+        txn();
+    }
+    catch (err) {
+        report.error = err instanceof Error ? err.message : String(err);
+    }
+    finally {
+        source?.close();
+    }
+    return report;
+}
+export function migrateLegacy(options = {}) {
+    const sources = options.sources ?? DEFAULT_LEGACY_SOURCES;
+    const targetPath = options.target ?? DEFAULT_TARGET;
+    const dryRun = options.dryRun === true;
+    if (!fs.existsSync(targetPath)) {
+        throw new Error(`target DB does not exist: ${targetPath} (run \`shieldcortex setup\` first)`);
+    }
+    const target = new Database(targetPath);
+    // Foreign keys on so legacy links to deleted memories fail loudly.
+    target.pragma('foreign_keys = ON');
+    // The dashboard API server holds an open connection in WAL mode; give the
+    // SQLite locking layer plenty of room to coordinate so the migration
+    // doesn't bail with SQLITE_BUSY mid-transaction.
+    target.pragma('busy_timeout = 10000');
+    const report = {
+        target: targetPath,
+        dryRun,
+        sources: [],
+        totalMemories: 0,
+        totalLinks: 0,
+    };
+    try {
+        for (const sourcePath of sources) {
+            const sourceReport = migrateOne(sourcePath, target, dryRun);
+            report.sources.push(sourceReport);
+            report.totalMemories += sourceReport.memoriesImported;
+            report.totalLinks += sourceReport.linksImported;
+        }
+    }
+    finally {
+        target.close();
+    }
+    return report;
+}
+function printReport(report) {
+    const banner = report.dryRun ? '[DRY RUN] ' : '';
+    console.log(`${banner}Legacy memory migration → ${report.target}`);
+    console.log('');
+    for (const src of report.sources) {
+        if (!src.exists) {
+            console.log(`  ${src.path}: not found, skipped`);
+            continue;
+        }
+        if (src.error) {
+            console.log(`  ${src.path}: ERROR — ${src.error}`);
+            continue;
+        }
+        const verb = report.dryRun ? 'would import' : 'imported';
+        console.log(`  ${src.path}:`);
+        console.log(`    memories: ${src.memoriesFound} found, ${verb} ${src.memoriesImported}`);
+        console.log(`    links:    ${src.linksFound} found, ${verb} ${src.linksImported}, skipped ${src.linksSkipped}`);
+    }
+    console.log('');
+    console.log(report.dryRun
+        ? `Total: would import ${report.totalMemories} memories + ${report.totalLinks} links.`
+        : `Total: imported ${report.totalMemories} memories + ${report.totalLinks} links.`);
+    if (!report.dryRun) {
+        console.log('');
+        console.log('Tip: back up of the target DB was your responsibility — restore from');
+        console.log('     ~/.shieldcortex/memories.db.bak.* if needed.');
+    }
+}
+function flagValue(args, name) {
+    const idx = args.indexOf(name);
+    if (idx === -1)
+        return undefined;
+    const v = args[idx + 1];
+    if (!v || v.startsWith('--'))
+        return undefined;
+    return v;
+}
+async function runPrune(args) {
+    const { initDatabase } = await import('../database/init.js');
+    const { pruneMemories } = await import('../memory/prune.js');
+    initDatabase();
+    const dryRun = !args.includes('--execute');
+    const salienceLte = Number(flagValue(args, '--salience-lte') ?? 0.2);
+    const ageDaysGte = Number(flagValue(args, '--older-than') ?? 30);
+    const project = flagValue(args, '--project');
+    const includePinned = args.includes('--include-pinned');
+    const result = await pruneMemories({
+        salienceLte,
+        ageDaysGte,
+        project,
+        excludePinned: !includePinned,
+        dryRun,
+    });
+    const banner = dryRun ? '[DRY RUN] ' : '';
+    console.log(`${banner}Prune memories where salience <= ${salienceLte} AND age >= ${ageDaysGte}d`);
+    console.log(`  Project: ${project ?? '(all)'} · ExcludePinned: ${!includePinned}`);
+    console.log(`  Matched: ${result.matched}`);
+    if (result.sample.length > 0) {
+        console.log('  Sample:');
+        for (const s of result.sample) {
+            console.log(`    #${s.id} [${s.project ?? '-'}] sal ${s.salience.toFixed(2)} · ${s.ageDays}d · ${s.title.slice(0, 60)}`);
+        }
+    }
+    if (!dryRun) {
+        console.log(`  Deleted: ${result.deleted ?? 0}`);
+        if (result.backupPath)
+            console.log(`  Backup:  ${result.backupPath}`);
+    }
+    else if (result.matched > 0) {
+        console.log('  Re-run with --execute to delete.');
+    }
+}
+async function runDedupe(args) {
+    const { initDatabase } = await import('../database/init.js');
+    const { dedupeMemories } = await import('../memory/dedupe-runner.js');
+    initDatabase();
+    const dryRun = !args.includes('--execute');
+    const project = flagValue(args, '--project');
+    const limit = Number(flagValue(args, '--limit') ?? 200);
+    const result = await dedupeMemories({ project, dryRun, limit });
+    const banner = dryRun ? '[DRY RUN] ' : '';
+    console.log(`${banner}Dedupe long-term memories${project ? ` in project ${project}` : ' (all projects)'}`);
+    console.log(`  Pairs scanned: ${result.pairsFound}`);
+    console.log(`  Clusters: ${result.groups.length}`);
+    const totalRemovable = result.groups.reduce((sum, g) => sum + g.removeIds.length, 0);
+    console.log(`  Removable: ${totalRemovable}`);
+    if (result.groups.length > 0) {
+        console.log('  Groups:');
+        for (const g of result.groups.slice(0, 10)) {
+            console.log(`    keep #${g.keepId} [${g.removeIds.length} dup] ${g.similarity} — "${g.keepTitle.slice(0, 50)}"`);
+        }
+        if (result.groups.length > 10)
+            console.log(`    … and ${result.groups.length - 10} more`);
+    }
+    if (!dryRun) {
+        console.log(`  Merged: ${result.merged ?? 0}`);
+        if (result.backupPath)
+            console.log(`  Backup: ${result.backupPath}`);
+    }
+    else if (totalRemovable > 0) {
+        console.log('  Re-run with --execute to merge.');
+    }
+}
+function printUsage() {
+    console.log('Usage: shieldcortex memories <subcommand> [options]');
+    console.log('');
+    console.log('Subcommands:');
+    console.log('  migrate-legacy [--dry-run] [--source <path>]');
+    console.log('      Import memories from ~/.claude-memory/ and ~/.claude-cortex/');
+    console.log('      into the current ~/.shieldcortex/memories.db.');
+    console.log('');
+    console.log('  prune [--salience-lte 0.2] [--older-than 30] [--project X]');
+    console.log('        [--include-pinned] [--execute]');
+    console.log('      Delete memories below salience X older than N days.');
+    console.log('      DRY-RUN BY DEFAULT — pass --execute to actually delete.');
+    console.log('      Backup auto-saved before any delete.');
+    console.log('');
+    console.log('  dedupe [--project X] [--limit 200] [--execute]');
+    console.log('      Cluster near-duplicate long-term memories and keep the highest-');
+    console.log('      salience representative. DRY-RUN BY DEFAULT — pass --execute.');
+    console.log('      Backup auto-saved before any merge.');
+}
+export async function handleMemoriesCommand(args) {
+    const sub = args[0];
+    if (sub === 'migrate-legacy') {
+        const dryRun = args.includes('--dry-run');
+        const sourceIdx = args.indexOf('--source');
+        const sources = sourceIdx !== -1 && args[sourceIdx + 1]
+            ? [args[sourceIdx + 1]]
+            : undefined;
+        const report = migrateLegacy({ sources, dryRun });
+        printReport(report);
+        return;
+    }
+    if (sub === 'prune') {
+        await runPrune(args.slice(1));
+        return;
+    }
+    if (sub === 'dedupe') {
+        await runDedupe(args.slice(1));
+        return;
+    }
+    printUsage();
+    process.exit(1);
+}

package/dist/cloud/cli.js

@@ -157,8 +157,8 @@ export function handleCloudConfig(args) {
         console.log('  --cloud-enable         Enable cloud sync');
         console.log('  --cloud-disable        Disable cloud sync');
         console.log('  --cloud-status         Show current configuration');
-        console.log('  --openclaw-auto-memory <true|false>  Enable or disable OpenClaw auto-memory extraction');
-        console.log('  --proactive-recall <true|false>  Enable or disable proactive memory recall on prompts');
+        console.log('  --openclaw-auto-memory <true|false>  Extract memories from OpenClaw LLM output (default: off)');
+        console.log('  --proactive-recall <true|false>  Inject SC memory into prompts (default: off — adds latency)');
         console.log('  --restore-4.10-defaults  Restore pre-v4.11.0 defaults (recall on, strict interceptor, minimal preamble)');
         console.log('');
         console.log('LLM Verification:');

package/dist/cloud/config.d.ts

@@ -116,6 +116,28 @@ export declare function setProactiveRecall(enabled: boolean): void;
  * so the flip is a one-command undo.
  */
 export declare function restore410Defaults(): void;
+export interface AutoMemoryEnableConfig {
+    enableStop: boolean;
+    enableSessionEnd: boolean;
+}
+/**
+ * Returns the resolved on/off state of the opt-in auto-memory hooks.
+ *
+ * Default is false for both — preserves the OpenClaw-safe default that
+ * shipped in v4.13.0. The install flags (`--with-stop-hook` /
+ * `--with-session-end`) flip these to true so that wiring the hook in
+ * settings.json and enabling the runtime gate are a single user action.
+ */
+export declare function getAutoMemoryEnableConfig(): AutoMemoryEnableConfig;
+/**
+ * Persists the on/off state of the opt-in auto-memory hooks.
+ *
+ * Lives in `autoMemory.enableStop` / `autoMemory.enableSessionEnd` under
+ * `~/.shieldcortex/config.json` — the same namespace `auto-memory-config.mjs`
+ * reads from at hook fire time. Single source of truth: install flag +
+ * runtime gate cannot disagree.
+ */
+export declare function setAutoMemoryEnableConfig(updates: Partial<AutoMemoryEnableConfig>): void;
 export interface ToolResponseScanConfig {
     scanToolResponses: boolean;
     toolResponseMode: 'advisory' | 'enforce';

package/dist/cloud/config.js

@@ -499,6 +499,44 @@ export function restore410Defaults() {
     };
     writeRawConfig(raw);
 }
+/**
+ * Returns the resolved on/off state of the opt-in auto-memory hooks.
+ *
+ * Default is false for both — preserves the OpenClaw-safe default that
+ * shipped in v4.13.0. The install flags (`--with-stop-hook` /
+ * `--with-session-end`) flip these to true so that wiring the hook in
+ * settings.json and enabling the runtime gate are a single user action.
+ */
+export function getAutoMemoryEnableConfig() {
+    const raw = readRawConfig();
+    const am = raw.autoMemory && typeof raw.autoMemory === 'object'
+        ? raw.autoMemory
+        : {};
+    return {
+        enableStop: am.enableStop === true,
+        enableSessionEnd: am.enableSessionEnd === true,
+    };
+}
+/**
+ * Persists the on/off state of the opt-in auto-memory hooks.
+ *
+ * Lives in `autoMemory.enableStop` / `autoMemory.enableSessionEnd` under
+ * `~/.shieldcortex/config.json` — the same namespace `auto-memory-config.mjs`
+ * reads from at hook fire time. Single source of truth: install flag +
+ * runtime gate cannot disagree.
+ */
+export function setAutoMemoryEnableConfig(updates) {
+    const raw = readRawConfig();
+    const existing = raw.autoMemory && typeof raw.autoMemory === 'object'
+        ? raw.autoMemory
+        : {};
+    if (updates.enableStop !== undefined)
+        existing.enableStop = updates.enableStop;
+    if (updates.enableSessionEnd !== undefined)
+        existing.enableSessionEnd = updates.enableSessionEnd;
+    raw.autoMemory = existing;
+    writeRawConfig(raw);
+}
 const DEFAULT_TOOL_RESPONSE_SCAN_CONFIG = {
     scanToolResponses: true,
     toolResponseMode: 'advisory',

package/dist/database/init.js

@@ -31,7 +31,14 @@ function expandPath(path) {
  * Get the database path with legacy fallback
  * - New installs use ~/.shieldcortex/
  * - Existing users with ~/.claude-memory/ continue to work
+ *
+ * DEPRECATION: the .claude-memory fallback will be removed in v5.0.0 (target
+ * Q3 2026). Existing users on the legacy path get a one-time-per-process
+ * warning pointing them at `shieldcortex migrate-legacy` so they can move to
+ * ~/.shieldcortex/ before the cut. Same applies to .claude-cortex (separate
+ * legacy DB read by the CLI migrate command).
  */
+let _legacyFallbackWarned = false;
 function getDefaultDbPath() {
     const newPath = join(homedir(), '.shieldcortex', 'memories.db');
     const legacyPath = join(homedir(), '.claude-memory', 'memories.db');
@@ -39,7 +46,13 @@ function getDefaultDbPath() {
     if (existsSync(newPath) || !existsSync(legacyPath)) {
         return newPath;
     }
-    // Fall back to legacy path for existing users
+    // Fall back to legacy path for existing users — warn once.
+    if (!_legacyFallbackWarned) {
+        _legacyFallbackWarned = true;
+        console.warn('[shieldcortex] DEPRECATED: reading from ~/.claude-memory/memories.db.');
+        console.warn('[shieldcortex] This fallback will be removed in v5.0.0 (target Q3 2026).');
+        console.warn('[shieldcortex] To migrate now: shieldcortex migrate-legacy');
+    }
     return legacyPath;
 }
 function resolveRuntimeInfo() {
@@ -729,6 +742,18 @@ function runMigrations(database) {
       CREATE INDEX IF NOT EXISTS idx_frag_entities_memory ON fragmentation_entities(memory_id);
       CREATE INDEX IF NOT EXISTS idx_frag_entities_text ON fragmentation_entities(entity_value);
       CREATE INDEX IF NOT EXISTS idx_frag_entities_type ON fragmentation_entities(entity_type);
+
+      CREATE TABLE IF NOT EXISTS hook_invocations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        hook_name TEXT NOT NULL,
+        invoked_at TEXT NOT NULL DEFAULT (datetime('now')),
+        exit_code INTEGER,
+        duration_ms INTEGER,
+        memories_extracted INTEGER DEFAULT 0,
+        transcript_bytes INTEGER,
+        notes TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_hook_invocations_name_time ON hook_invocations(hook_name, invoked_at DESC);
     `);
     }
     catch {

package/dist/index.js

@@ -522,7 +522,8 @@ ${bold}DOCS${reset}
             return;
         }
         const stopHook = process.argv.includes('--with-stop-hook');
-        await setupClaudeMd({ stopHook });
+        const sessionEnd = process.argv.includes('--with-session-end');
+        await setupClaudeMd({ stopHook, sessionEnd });
         return;
     }
     // Handle "migrate" subcommand
@@ -584,6 +585,12 @@ ${bold}DOCS${reset}
         await handleReviewCopilotCommand(process.argv.slice(3), parsedArgs.dbPath);
         return;
     }
+    // Handle "memories" subcommand (memory database operations: migrate-legacy, ...)
+    if (process.argv[2] === 'memories') {
+        const { handleMemoriesCommand } = await import('./cli/migrate-legacy.js');
+        await handleMemoriesCommand(process.argv.slice(3));
+        return;
+    }
     // Handle "status" subcommand
     if (process.argv[2] === 'status') {
         const { handleStatusCommand } = await import('./setup/status.js');