shieldcortex 3.0.3 → 3.1.0

package/dist/cloud/sync-queue.d.ts

@@ -5,6 +5,8 @@
  * Supports both audit metadata sync and quarantine content sync payloads.
  * Uses SQLite sync_queue table with exponential backoff.
  */
+import type { SyncedMemoryRecord } from './memory-sync.js';
+import type { GraphSyncEnvelope } from './graph-sync.js';
 export interface SyncEntry {
     source_type: string;
     source_identifier: string;
@@ -37,6 +39,15 @@ export interface QueueStats {
     pending: number;
     failed: number;
     synced: number;
+    byKind: Record<'audit' | 'quarantine' | 'memory' | 'graph' | 'unknown', {
+        pending: number;
+        failed: number;
+        synced: number;
+    }>;
+    oldestPendingAt: string | null;
+    nextRetryAt: string | null;
+    lastError: string | null;
+    lastErrorKind: 'audit' | 'quarantine' | 'memory' | 'graph' | 'unknown' | null;
 }
 export interface SyncQueueResult {
     processed: number;
@@ -44,6 +55,9 @@ export interface SyncQueueResult {
     failed: number;
     permanentlyFailed: number;
 }
+export interface ReconcileQueueResult {
+    removed: number;
+}
 /**
  * Enqueue a failed sync entry for later retry.
  * INSERT into sync_queue with exponential backoff schedule.
@@ -53,6 +67,11 @@ export declare function enqueueFailedSync(entry: SyncEntry): void;
  * Enqueue a failed quarantine sync entry for later retry.
  */
 export declare function enqueueFailedQuarantineSync(entry: QuarantineSyncEntry): void;
+/**
+ * Enqueue a failed memory sync entry for later retry.
+ */
+export declare function enqueueFailedMemorySync(entry: SyncedMemoryRecord): void;
+export declare function enqueueFailedGraphSync(entry: GraphSyncEnvelope): void;
 /**
  * Process pending items in the retry queue.
  * SELECT pending WHERE next_retry_at <= now, retry each (up to 10 per tick).
@@ -63,6 +82,11 @@ export declare function processRetryQueue(): Promise<SyncQueueResult>;
  * Get queue statistics by status.
  */
 export declare function getQueueStats(): QueueStats;
+export declare function reconcileSyncQueue(options?: {
+    kinds?: Array<'memory' | 'graph' | 'audit' | 'quarantine'>;
+    statuses?: Array<'pending' | 'failed'>;
+    maxCreatedAt?: string | null;
+}): ReconcileQueueResult;
 /**
  * Purge old entries from the queue.
  * DELETE WHERE created_at < 7 days ago.

package/dist/cloud/sync-queue.js

@@ -6,7 +6,7 @@
  * Uses SQLite sync_queue table with exponential backoff.
  */
 import { getDatabase } from '../database/init.js';
-import { getCloudConfig, updateLastSyncAt } from './config.js';
+import { getCloudConfig, getDeviceId, getDeviceName, updateLastSyncAt } from './config.js';
 /**
  * Enqueue a failed sync entry for later retry.
  * INSERT into sync_queue with exponential backoff schedule.
@@ -20,6 +20,23 @@ export function enqueueFailedSync(entry) {
 export function enqueueFailedQuarantineSync(entry) {
     enqueuePayload({ kind: 'quarantine', entry });
 }
+/**
+ * Enqueue a failed memory sync entry for later retry.
+ */
+export function enqueueFailedMemorySync(entry) {
+    enqueuePayload({
+        kind: 'memory',
+        entry: {
+            record: entry,
+            device_id: getDeviceId(),
+            device_name: getDeviceName(),
+            platform: `${process.platform}/${process.arch}`,
+        },
+    });
+}
+export function enqueueFailedGraphSync(entry) {
+    enqueuePayload({ kind: 'graph', entry });
+}
 function enqueuePayload(payload) {
     const db = getDatabase();
     const payloadJson = JSON.stringify(payload);
@@ -60,6 +77,35 @@ function buildRetryRequest(payloadText) {
             body: JSON.stringify(payload.entry),
         };
     }
+    if (parsed &&
+        typeof parsed === 'object' &&
+        !Array.isArray(parsed) &&
+        'kind' in parsed &&
+        parsed.kind === 'memory') {
+        const payload = parsed;
+        return {
+            path: '/v1/sync/memories',
+            body: JSON.stringify({
+                device: {
+                    device_id: payload.entry.device_id,
+                    device_name: payload.entry.device_name,
+                    platform: payload.entry.platform,
+                },
+                memories: [payload.entry.record],
+            }),
+        };
+    }
+    if (parsed &&
+        typeof parsed === 'object' &&
+        !Array.isArray(parsed) &&
+        'kind' in parsed &&
+        parsed.kind === 'graph') {
+        const payload = parsed;
+        return {
+            path: '/v1/sync/graph',
+            body: JSON.stringify(payload.entry),
+        };
+    }
     throw new Error('Unsupported sync queue payload');
 }
 /**
@@ -167,21 +213,94 @@ export async function processRetryQueue() {
 export function getQueueStats() {
     const db = getDatabase();
     const rows = db.prepare(`
-    SELECT status, COUNT(*) as count
+    SELECT id, payload, status, next_retry_at, last_error, created_at
     FROM sync_queue
-    GROUP BY status
   `).all();
-    const stats = { pending: 0, failed: 0, synced: 0 };
+    const stats = {
+        pending: 0,
+        failed: 0,
+        synced: 0,
+        byKind: {
+            audit: { pending: 0, failed: 0, synced: 0 },
+            quarantine: { pending: 0, failed: 0, synced: 0 },
+            memory: { pending: 0, failed: 0, synced: 0 },
+            graph: { pending: 0, failed: 0, synced: 0 },
+            unknown: { pending: 0, failed: 0, synced: 0 },
+        },
+        oldestPendingAt: null,
+        nextRetryAt: null,
+        lastError: null,
+        lastErrorKind: null,
+    };
+    let newestErrorRowId = -1;
     for (const row of rows) {
+        const kind = getPayloadKind(row.payload);
         if (row.status === 'pending')
-            stats.pending = row.count;
+            stats.pending++;
         else if (row.status === 'failed')
-            stats.failed = row.count;
+            stats.failed++;
         else if (row.status === 'synced')
-            stats.synced = row.count;
+            stats.synced++;
+        if (row.status === 'pending' || row.status === 'failed' || row.status === 'synced') {
+            stats.byKind[kind][row.status]++;
+        }
+        if (row.status === 'pending' && row.created_at) {
+            if (!stats.oldestPendingAt || row.created_at < stats.oldestPendingAt) {
+                stats.oldestPendingAt = row.created_at;
+            }
+        }
+        if (row.status === 'pending' && row.next_retry_at) {
+            if (!stats.nextRetryAt || row.next_retry_at < stats.nextRetryAt) {
+                stats.nextRetryAt = row.next_retry_at;
+            }
+        }
+        if (row.last_error && row.id > newestErrorRowId) {
+            newestErrorRowId = row.id;
+            stats.lastError = row.last_error;
+            stats.lastErrorKind = kind;
+        }
     }
     return stats;
 }
+export function reconcileSyncQueue(options = {}) {
+    const db = getDatabase();
+    const kinds = options.kinds ?? ['memory', 'graph'];
+    const statuses = options.statuses ?? ['pending', 'failed'];
+    if (kinds.length === 0 || statuses.length === 0) {
+        return { removed: 0 };
+    }
+    const kindPlaceholders = kinds.map(() => '?').join(', ');
+    const statusPlaceholders = statuses.map(() => '?').join(', ');
+    const params = [...statuses, ...kinds];
+    let sqlText = `
+    DELETE FROM sync_queue
+    WHERE status IN (${statusPlaceholders})
+      AND json_extract(payload, '$.kind') IN (${kindPlaceholders})
+  `;
+    if (options.maxCreatedAt) {
+        sqlText += ' AND created_at <= ?';
+        params.push(options.maxCreatedAt);
+    }
+    const result = db.prepare(sqlText).run(...params);
+    return { removed: Number(result.changes ?? 0) };
+}
+function getPayloadKind(payloadText) {
+    try {
+        const parsed = JSON.parse(payloadText);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && 'kind' in parsed) {
+            const kind = parsed.kind;
+            if (kind === 'audit' || kind === 'quarantine' || kind === 'memory' || kind === 'graph')
+                return kind;
+        }
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return 'audit';
+        }
+    }
+    catch {
+        // ignore malformed payloads
+    }
+    return 'unknown';
+}
 /**
  * Purge old entries from the queue.
  * DELETE WHERE created_at < 7 days ago.

package/dist/database/init.js

@@ -7,6 +7,7 @@ import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
+import { randomUUID } from 'crypto';
 const _currentFile = fileURLToPath(import.meta.url);
 const _currentDir = dirname(_currentFile);
 let db = null;
@@ -260,6 +261,25 @@ function runMigrations(database) {
     if (!columnNames.has('source')) {
         database.exec("ALTER TABLE memories ADD COLUMN source TEXT DEFAULT 'user:direct'");
     }
+    if (!columnNames.has('uuid')) {
+        database.exec("ALTER TABLE memories ADD COLUMN uuid TEXT");
+    }
+    if (!columnNames.has('updated_at')) {
+        database.exec('ALTER TABLE memories ADD COLUMN updated_at TIMESTAMP');
+    }
+    try {
+        const rowsWithoutUuid = database.prepare('SELECT id FROM memories WHERE uuid IS NULL OR uuid = ?').all('');
+        const setUuid = database.prepare('UPDATE memories SET uuid = ? WHERE id = ?');
+        for (const row of rowsWithoutUuid) {
+            setUuid.run(randomUUID(), row.id);
+        }
+        database.exec('UPDATE memories SET updated_at = COALESCE(updated_at, created_at, CURRENT_TIMESTAMP) WHERE updated_at IS NULL');
+        database.exec('CREATE UNIQUE INDEX IF NOT EXISTS idx_memories_uuid ON memories(uuid)');
+        database.exec('CREATE INDEX IF NOT EXISTS idx_memories_updated ON memories(updated_at DESC)');
+    }
+    catch {
+        // Safe to ignore on partially migrated databases
+    }
     // Migration: Defence tables (defence_audit, quarantine, fragmentation_entities)
     try {
         database.exec(`
@@ -673,6 +693,7 @@ function getInlineSchema() {
     return `
     CREATE TABLE IF NOT EXISTS memories (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
+      uuid TEXT NOT NULL UNIQUE,
       type TEXT NOT NULL CHECK(type IN ('short_term', 'long_term', 'episodic')),
       category TEXT NOT NULL DEFAULT 'note',
       title TEXT NOT NULL,
@@ -684,6 +705,7 @@ function getInlineSchema() {
       access_count INTEGER DEFAULT 0,
       last_accessed TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
       created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+      updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
       metadata TEXT DEFAULT '{}',
       embedding BLOB,
       scope TEXT DEFAULT 'project',
@@ -721,11 +743,13 @@ function getInlineSchema() {
     END;
 
     CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_memories_uuid ON memories(uuid);
     CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project);
     CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);
     CREATE INDEX IF NOT EXISTS idx_memories_salience ON memories(salience DESC);
     CREATE INDEX IF NOT EXISTS idx_memories_decayed_score ON memories(decayed_score DESC);
     CREATE INDEX IF NOT EXISTS idx_memories_last_accessed ON memories(last_accessed DESC);
+    CREATE INDEX IF NOT EXISTS idx_memories_updated ON memories(updated_at DESC);
 
     CREATE TABLE IF NOT EXISTS sessions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,

package/dist/graph/backfill.js

@@ -1,8 +1,8 @@
 import { getDatabase } from '../database/init.js';
 import { extractFromMemory } from './extract.js';
-import { processExtractionResult } from './resolve.js';
+import { replaceMemoryGraph } from './resolve.js';
 /** Bump this when extract.ts logic changes to force re-extraction */
-const EXTRACTION_VERSION = 2;
+const EXTRACTION_VERSION = 3;
 export function backfillGraph(options) {
     const db = getDatabase();
     const force = options?.force ?? false;
@@ -32,9 +32,7 @@ export function backfillGraph(options) {
     for (const mem of memories) {
         try {
             const extraction = extractFromMemory(mem.title, mem.content, mem.category);
-            if (extraction.entities.length > 0) {
-                processExtractionResult(extraction, mem.id);
-            }
+            replaceMemoryGraph(mem.id, extraction);
             // Mark this memory as extracted at the current version
             if (updateVersion) {
                 updateVersion.run(EXTRACTION_VERSION, mem.id);

package/dist/graph/resolve.d.ts

@@ -2,4 +2,14 @@ import type { EntityType, ExtractionResult } from './extract.js';
 export declare function levenshtein(a: string, b: string): number;
 export declare function resolveEntity(name: string, type: EntityType): number;
 export declare function mergeEntities(keepId: number, removeId: number): void;
+export declare function removeMemoryGraph(memoryId: number): {
+    removedEntityLinks: number;
+    removedTriples: number;
+    orphanEntitiesPruned: number;
+};
+export declare function replaceMemoryGraph(memoryId: number, result: ExtractionResult): {
+    removedEntityLinks: number;
+    removedTriples: number;
+    orphanEntitiesPruned: number;
+};
 export declare function processExtractionResult(result: ExtractionResult, memoryId: number): void;

package/dist/graph/resolve.js

@@ -93,7 +93,7 @@ export function mergeEntities(keepId, removeId) {
         db.prepare('DELETE FROM entities WHERE id = ?').run(removeId);
     })();
 }
-export function processExtractionResult(result, memoryId) {
+function applyExtractionResult(result, memoryId) {
     const db = getDatabase();
     const nameToId = new Map();
     // 1. Resolve all entities
@@ -123,3 +123,65 @@ export function processExtractionResult(result, memoryId) {
         updateCount.run(id);
     }
 }
+function pruneOrphanEntities(candidateIds) {
+    if (candidateIds.length === 0)
+        return 0;
+    const db = getDatabase();
+    const placeholders = candidateIds.map(() => '?').join(', ');
+    const orphanRows = db.prepare(`
+    SELECT e.id
+    FROM entities e
+    WHERE e.id IN (${placeholders})
+      AND NOT EXISTS (SELECT 1 FROM memory_entities me WHERE me.entity_id = e.id)
+      AND NOT EXISTS (SELECT 1 FROM triples t WHERE t.subject_id = e.id OR t.object_id = e.id)
+  `).all(...candidateIds);
+    if (orphanRows.length === 0)
+        return 0;
+    const orphanIds = orphanRows.map((row) => row.id);
+    const orphanPlaceholders = orphanIds.map(() => '?').join(', ');
+    db.prepare(`DELETE FROM entities WHERE id IN (${orphanPlaceholders})`).run(...orphanIds);
+    return orphanIds.length;
+}
+function clearMemoryGraphSlice(memoryId) {
+    const db = getDatabase();
+    const linkedEntityRows = db.prepare(`
+    SELECT DISTINCT entity_id
+    FROM memory_entities
+    WHERE memory_id = ?
+  `).all(memoryId);
+    const linkedEntityIds = linkedEntityRows.map((row) => row.entity_id);
+    const removedTriples = Number(db.prepare('DELETE FROM triples WHERE source_memory_id = ?').run(memoryId).changes ?? 0);
+    const removedEntityLinks = Number(db.prepare('DELETE FROM memory_entities WHERE memory_id = ?').run(memoryId).changes ?? 0);
+    if (linkedEntityIds.length > 0) {
+        const placeholders = linkedEntityIds.map(() => '?').join(', ');
+        db.prepare(`
+      UPDATE entities
+      SET memory_count = CASE WHEN memory_count > 0 THEN memory_count - 1 ELSE 0 END
+      WHERE id IN (${placeholders})
+    `).run(...linkedEntityIds);
+    }
+    const orphanEntitiesPruned = pruneOrphanEntities(linkedEntityIds);
+    return {
+        removedEntityLinks,
+        removedTriples,
+        orphanEntitiesPruned,
+    };
+}
+export function removeMemoryGraph(memoryId) {
+    const db = getDatabase();
+    return db.transaction(() => clearMemoryGraphSlice(memoryId))();
+}
+export function replaceMemoryGraph(memoryId, result) {
+    const db = getDatabase();
+    return db.transaction(() => {
+        const cleared = clearMemoryGraphSlice(memoryId);
+        if (result.entities.length > 0) {
+            applyExtractionResult(result, memoryId);
+        }
+        return cleared;
+    })();
+}
+export function processExtractionResult(result, memoryId) {
+    const db = getDatabase();
+    db.transaction(() => applyExtractionResult(result, memoryId))();
+}

package/dist/index.d.ts

@@ -25,6 +25,7 @@
  *   shieldcortex hook session-start      # Run session-start hook (for settings.json)
  *   shieldcortex hook session-end        # Run session-end hook (for settings.json)
  *   shieldcortex service install         # Auto-start dashboard on login
+ *   shieldcortex service repair          # Rebuild auto-start service with current install path
  *   shieldcortex service uninstall       # Remove auto-start
  *   shieldcortex service status          # Check service status
  *   shieldcortex openclaw install        # Install OpenClaw hook
@@ -32,6 +33,7 @@
  *   shieldcortex openclaw status         # Check OpenClaw hook status
  *   shieldcortex config --openclaw-auto-memory true   # Enable OpenClaw auto-memory extraction
  *   shieldcortex config --openclaw-auto-memory false  # Disable OpenClaw auto-memory extraction
+ *   shieldcortex cloud sync --full      # Backfill local memories + graph to ShieldCortex Cloud
  *   shieldcortex copilot install         # Configure MCP server for VS Code + Cursor
  *   shieldcortex copilot uninstall       # Remove MCP server configuration
  *   shieldcortex copilot status          # Check MCP server configuration

package/dist/index.js

@@ -25,6 +25,7 @@
  *   shieldcortex hook session-start      # Run session-start hook (for settings.json)
  *   shieldcortex hook session-end        # Run session-end hook (for settings.json)
  *   shieldcortex service install         # Auto-start dashboard on login
+ *   shieldcortex service repair          # Rebuild auto-start service with current install path
  *   shieldcortex service uninstall       # Remove auto-start
  *   shieldcortex service status          # Check service status
  *   shieldcortex openclaw install        # Install OpenClaw hook
@@ -32,6 +33,7 @@
  *   shieldcortex openclaw status         # Check OpenClaw hook status
  *   shieldcortex config --openclaw-auto-memory true   # Enable OpenClaw auto-memory extraction
  *   shieldcortex config --openclaw-auto-memory false  # Disable OpenClaw auto-memory extraction
+ *   shieldcortex cloud sync --full      # Backfill local memories + graph to ShieldCortex Cloud
  *   shieldcortex copilot install         # Configure MCP server for VS Code + Cursor
  *   shieldcortex copilot uninstall       # Remove MCP server configuration
  *   shieldcortex copilot status          # Check MCP server configuration
@@ -47,6 +49,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
+import http from 'http';
 import path from 'path';
 import fs from 'fs';
 import { createServer } from './server.js';
@@ -295,6 +298,25 @@ function startDashboard() {
     });
     return dashboard;
 }
+function checkLocalHttp(url, expectedStatus = [200], timeoutMs = 1200) {
+    return new Promise((resolve) => {
+        const req = http.get(url, { timeout: timeoutMs }, (res) => {
+            res.resume();
+            resolve(Boolean(res.statusCode && expectedStatus.includes(res.statusCode)));
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.on('error', () => resolve(false));
+    });
+}
+async function isLocalApiRunning() {
+    return checkLocalHttp('http://127.0.0.1:3001/api/health');
+}
+async function isLocalDashboardRunning() {
+    return checkLocalHttp('http://127.0.0.1:3030', [200, 307, 308]);
+}
 /**
  * Main entry point
  */
@@ -321,6 +343,7 @@ ${bold}COMMANDS${reset}
   ${cyan}doctor${reset}                Diagnose installation issues
   ${cyan}quickstart${reset} [target]    Detect the fastest setup path
   ${cyan}config${reset} [options]      Configure cloud sync and settings
+  ${cyan}cloud${reset} sync --full     Backfill local memories + graph to ShieldCortex Cloud
   ${cyan}license${reset} <action>      Manage licence key (activate, status, deactivate)
   ${cyan}iron-dome${reset} <action>    Manage behaviour protection layer
   ${cyan}audit${reset} [options]       Run a full security audit
@@ -343,6 +366,7 @@ ${bold}EXAMPLES${reset}
   shieldcortex dashboard
   shieldcortex license activate sc_pro_...
   shieldcortex config --cloud-enable --cloud-api-key <key>
+  shieldcortex cloud sync --full
 
 ${bold}DOCS${reset}
   https://shieldcortex.ai/docs
@@ -423,6 +447,12 @@ ${bold}DOCS${reset}
         handleCloudConfig(process.argv.slice(3));
         return;
     }
+    // Handle "cloud" subcommand
+    if (process.argv[2] === 'cloud') {
+        const { handleCloudCommand } = await import('./cloud/cli.js');
+        await handleCloudCommand(process.argv.slice(3));
+        return;
+    }
     // Handle "status" subcommand
     if (process.argv[2] === 'status') {
         const { handleStatusCommand } = await import('./setup/status.js');
@@ -602,7 +632,7 @@ ${bold}DOCS${reset}
     const knownCommands = new Set([
         'doctor', 'quickstart', 'setup', 'install', 'migrate', 'uninstall', 'hook',
         'openclaw', 'clawdbot', 'copilot', 'service', 'config', 'status',
-        'graph', 'license', 'licence', 'audit', 'iron-dome', 'scan',
+        'graph', 'license', 'licence', 'audit', 'iron-dome', 'scan', 'cloud',
         'scan-skill', 'scan-skills', 'dashboard', 'api',
     ]);
     const arg = process.argv[2];
@@ -615,14 +645,36 @@ ${bold}DOCS${reset}
     let dashboardProcess = null;
     if (mode === 'api') {
         // API mode only - for dashboard visualization
+        if (await isLocalApiRunning()) {
+            console.log('ShieldCortex API is already running at http://localhost:3001');
+            return;
+        }
         console.log('Starting ShieldCortex in API mode...');
         startVisualizationServer(dbPath);
     }
     else if (mode === 'dashboard') {
         // Dashboard mode - API + Next.js dashboard
         console.log('Starting ShieldCortex with Dashboard...');
-        startVisualizationServer(dbPath);
-        dashboardProcess = startDashboard();
+        const apiRunning = await isLocalApiRunning();
+        const dashboardRunning = await isLocalDashboardRunning();
+        if (apiRunning && dashboardRunning) {
+            console.log('ShieldCortex dashboard is already running.');
+            console.log('Dashboard: http://localhost:3030');
+            console.log('API:       http://localhost:3001');
+            return;
+        }
+        if (!apiRunning) {
+            startVisualizationServer(dbPath);
+        }
+        else {
+            console.log('Reusing existing local ShieldCortex API on http://localhost:3001');
+        }
+        if (!dashboardRunning) {
+            dashboardProcess = startDashboard();
+        }
+        else {
+            console.log('Dashboard UI is already running on http://localhost:3030');
+        }
         // Kill dashboard child process on any exit (prevents orphans)
         const killDashboard = () => {
             if (dashboardProcess && !dashboardProcess.killed) {
@@ -648,7 +700,12 @@ ${bold}DOCS${reset}
     else if (mode === 'both') {
         // Both modes - API in background, MCP in foreground
         console.log('Starting ShieldCortex in both modes...');
-        startVisualizationServer(dbPath);
+        if (!(await isLocalApiRunning())) {
+            startVisualizationServer(dbPath);
+        }
+        else {
+            console.log('Reusing existing local ShieldCortex API on http://localhost:3001');
+        }
         await startMcpServer(dbPath);
     }
     else {

package/dist/memory/search.d.ts

@@ -0,0 +1,37 @@
+import type Database from 'better-sqlite3';
+import { Memory, MemoryCategory, MemoryConfig, SearchResult } from './types.js';
+export interface SearchExecutionOptions {
+    enableSideEffects: boolean;
+    includeExplanation: boolean;
+}
+export interface SearchScoringContext {
+    db: Database.Database;
+    config: MemoryConfig;
+    detectedCategory: MemoryCategory | null;
+    queryTags: string[];
+    vectorResults: Map<number, number>;
+    query: string;
+}
+export interface SearchScoreValues {
+    ftsScore: number;
+    vectorSimilarity: number;
+    vectorBoost: number;
+    decayedScore: number;
+    priorityBoost: number;
+    recencyBoost: number;
+    categoryBoost: number;
+    linkBoost: number;
+    tagBoost: number;
+    activationBoost: number;
+    finalScore: number;
+}
+export type MemoryRowConverter = (row: Record<string, unknown>) => Memory;
+export declare function detectQueryCategory(query: string): MemoryCategory | null;
+export declare function calculateLinkBoost(memoryId: number, db: Database.Database): number;
+export declare function calculateTagScore(queryTags: string[], memoryTags: string[]): number;
+export declare function extractQueryTags(query: string): string[];
+export declare function vectorSearch(db: Database.Database, rowToMemory: MemoryRowConverter, queryEmbedding: Float32Array, limit: number, project?: string, includeGlobal?: boolean): Array<{
+    memory: Memory;
+    similarity: number;
+}>;
+export declare function buildSearchExplanation(memory: Memory, context: SearchScoringContext, values: SearchScoreValues): SearchResult['explanation'];