@vinaes/succ 1.3.19

package/dist/lib/errors.js

@@ -0,0 +1,66 @@
+/**
+ * Custom error hierarchy for succ.
+ *
+ * Provides programmatic error discrimination without parsing message strings.
+ * Each subclass carries a `code` string for structured error handling.
+ */
+/** Base error for all succ errors. Carries a `code` and optional `context`. */
+export class SuccError extends Error {
+    code;
+    context;
+    constructor(message, code = 'SUCC_ERROR', context) {
+        super(message);
+        this.name = 'SuccError';
+        this.code = code;
+        this.context = context;
+    }
+}
+/** Configuration errors: invalid config values, missing required settings. */
+export class ConfigError extends SuccError {
+    constructor(message, context) {
+        super(message, 'CONFIG_ERROR', context);
+        this.name = 'ConfigError';
+    }
+}
+/** Storage/database errors: connection failures, query errors, constraint violations. */
+export class StorageError extends SuccError {
+    constructor(message, context) {
+        super(message, 'STORAGE_ERROR', context);
+        this.name = 'StorageError';
+    }
+}
+/** Validation errors: bad input, precondition failures, argument checks. */
+export class ValidationError extends SuccError {
+    constructor(message, context) {
+        super(message, 'VALIDATION_ERROR', context);
+        this.name = 'ValidationError';
+    }
+}
+/** Network/API errors: HTTP failures, timeouts, API response errors. */
+export class NetworkError extends SuccError {
+    statusCode;
+    constructor(message, statusCode, context) {
+        super(message, 'NETWORK_ERROR', context);
+        this.name = 'NetworkError';
+        this.statusCode = statusCode;
+    }
+}
+/** Resource not found: files, PRDs, sessions, memories. */
+export class NotFoundError extends SuccError {
+    constructor(message, context) {
+        super(message, 'NOT_FOUND', context);
+        this.name = 'NotFoundError';
+    }
+}
+/** Dependency errors: missing optional deps, runtime init failures. */
+export class DependencyError extends SuccError {
+    constructor(message, context) {
+        super(message, 'DEPENDENCY_ERROR', context);
+        this.name = 'DependencyError';
+    }
+}
+/** Type guard: check if an error is a SuccError or subclass. */
+export function isSuccError(error) {
+    return error instanceof SuccError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAS;IACb,OAAO,CAA2B;IAE3C,YAAY,OAAe,EAAE,OAAe,YAAY,EAAE,OAAiC;QACzF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,OAAO,WAAY,SAAQ,SAAS;IACxC,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,yFAAyF;AACzF,MAAM,OAAO,YAAa,SAAQ,SAAS;IACzC,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC5C,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,YAAa,SAAQ,SAAS;IAChC,UAAU,CAAU;IAE7B,YAAY,OAAe,EAAE,UAAmB,EAAE,OAAiC;QACjF,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1C,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC5C,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,SAAS,CAAC;AACpC,CAAC"}

package/dist/lib/fault-logger.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Centralized fault logger for succ.
+ *
+ * Three channels:
+ * 1. Local file: .succ/brain-faults.log (JSON lines, with rotation)
+ * 2. Webhook: POST to configurable URL (fire-and-forget)
+ * 3. Sentry: lazy-loaded @sentry/node SDK (optional peer dependency)
+ */
+export type FaultLevel = 'error' | 'warn' | 'info' | 'debug';
+export interface FaultEntry {
+    timestamp: string;
+    level: FaultLevel;
+    component: string;
+    message: string;
+    stack?: string;
+    context?: Record<string, unknown>;
+    version?: string;
+}
+/**
+ * Log a fault to all configured channels.
+ * Never throws — all errors are silently swallowed.
+ */
+export declare function logFault(level: FaultLevel, component: string, message: string, opts?: {
+    error?: Error;
+    context?: Record<string, unknown>;
+}): void;
+/** Log an error (convenience wrapper). */
+export declare function logError(component: string, message: string, error?: Error, context?: Record<string, unknown>): void;
+/** Log a warning (convenience wrapper). */
+export declare function logWarn(component: string, message: string, context?: Record<string, unknown>): void;
+/** Log an info message (convenience wrapper). */
+export declare function logInfo(component: string, message: string, context?: Record<string, unknown>): void;
+/** Reset Sentry state (for testing). */
+export declare function _resetSentryState(): void;
+//# sourceMappingURL=fault-logger.d.ts.map

package/dist/lib/fault-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fault-logger.d.ts","sourceRoot":"","sources":["../../src/lib/fault-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkID;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC1D,IAAI,CAkCN;AAED,0CAA0C;AAC1C,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,KAAK,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAEN;AAED,2CAA2C;AAC3C,wBAAgB,OAAO,CACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAEN;AAED,iDAAiD;AACjD,wBAAgB,OAAO,CACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAEN;AAMD,wCAAwC;AACxC,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC"}

package/dist/lib/fault-logger.js

@@ -0,0 +1,182 @@
+/**
+ * Centralized fault logger for succ.
+ *
+ * Three channels:
+ * 1. Local file: .succ/brain-faults.log (JSON lines, with rotation)
+ * 2. Webhook: POST to configurable URL (fire-and-forget)
+ * 3. Sentry: lazy-loaded @sentry/node SDK (optional peer dependency)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSuccDir, getErrorReportingConfig } from './config.js';
+const LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+// Read version once at module load
+let _version;
+function getVersion() {
+    if (_version)
+        return _version;
+    try {
+        const pkgPath = path.resolve(new URL('.', import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1'), '../../package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        _version = pkg.version || 'unknown';
+    }
+    catch {
+        _version = 'unknown';
+    }
+    return _version;
+}
+// ---------------------------------------------------------------------------
+// Channel 1: Local file with rotation
+// ---------------------------------------------------------------------------
+function rotateIfNeeded(logPath, maxSizeMb) {
+    try {
+        const stats = fs.statSync(logPath);
+        if (stats.size > maxSizeMb * 1024 * 1024) {
+            const backupPath = logPath + '.1';
+            fs.renameSync(logPath, backupPath);
+        }
+    }
+    catch {
+        // File doesn't exist or can't stat — fine, will be created on write
+    }
+}
+function writeToFile(entry, maxSizeMb) {
+    try {
+        const succDir = getSuccDir();
+        const logPath = path.join(succDir, 'brain-faults.log');
+        // Ensure .succ/ directory exists
+        if (!fs.existsSync(succDir)) {
+            fs.mkdirSync(succDir, { recursive: true });
+        }
+        rotateIfNeeded(logPath, maxSizeMb);
+        fs.appendFileSync(logPath, JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Never break caller
+    }
+}
+// ---------------------------------------------------------------------------
+// Channel 2: Webhook (fire-and-forget)
+// ---------------------------------------------------------------------------
+function sendToWebhook(entry, url, headers) {
+    try {
+        fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: JSON.stringify(entry),
+        }).catch(() => { });
+    }
+    catch {
+        // Never break caller
+    }
+}
+// ---------------------------------------------------------------------------
+// Channel 3: Sentry (lazy-loaded optional peer dependency)
+// ---------------------------------------------------------------------------
+let sentryModule = undefined; // undefined=not tried, false=not installed
+let sentryInitialized = false;
+async function getSentry() {
+    if (sentryModule === false)
+        return null;
+    if (sentryModule)
+        return sentryModule;
+    try {
+        // @ts-expect-error - @sentry/node is an optional peer dependency, may not be installed
+        sentryModule = await import('@sentry/node');
+        return sentryModule;
+    }
+    catch {
+        sentryModule = false;
+        return null;
+    }
+}
+function sendToSentry(entry, dsn, environment, sampleRate) {
+    (async () => {
+        try {
+            const Sentry = await getSentry();
+            if (!Sentry)
+                return;
+            if (!sentryInitialized) {
+                Sentry.init({ dsn, environment, sampleRate });
+                sentryInitialized = true;
+            }
+            if (entry.level === 'error') {
+                const err = new Error(entry.message);
+                if (entry.stack)
+                    err.stack = entry.stack;
+                Sentry.captureException(err, {
+                    tags: { component: entry.component },
+                    extra: entry.context,
+                });
+            }
+            else {
+                Sentry.captureMessage(entry.message, {
+                    level: entry.level,
+                    tags: { component: entry.component },
+                    extra: entry.context,
+                });
+            }
+        }
+        catch {
+            // Never break caller
+        }
+    })();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Log a fault to all configured channels.
+ * Never throws — all errors are silently swallowed.
+ */
+export function logFault(level, component, message, opts) {
+    try {
+        const config = getErrorReportingConfig();
+        if (!config.enabled)
+            return;
+        if (LEVEL_ORDER[level] < LEVEL_ORDER[config.level])
+            return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            component,
+            message,
+            stack: opts?.error?.stack,
+            context: opts?.context,
+        };
+        // Channel 1: local file (always)
+        writeToFile(entry, config.max_file_size_mb);
+        // Channel 2: webhook (if configured)
+        if (config.webhook_url) {
+            sendToWebhook({ ...entry, version: getVersion() }, config.webhook_url, config.webhook_headers);
+        }
+        // Channel 3: sentry (if configured)
+        if (config.sentry_dsn) {
+            sendToSentry(entry, config.sentry_dsn, config.sentry_environment, config.sentry_sample_rate);
+        }
+    }
+    catch {
+        // Absolutely never break the caller
+    }
+}
+/** Log an error (convenience wrapper). */
+export function logError(component, message, error, context) {
+    logFault('error', component, message, { error, context });
+}
+/** Log a warning (convenience wrapper). */
+export function logWarn(component, message, context) {
+    logFault('warn', component, message, { context });
+}
+/** Log an info message (convenience wrapper). */
+export function logInfo(component, message, context) {
+    logFault('info', component, message, { context });
+}
+// ---------------------------------------------------------------------------
+// Testing helpers (exported for test use only)
+// ---------------------------------------------------------------------------
+/** Reset Sentry state (for testing). */
+export function _resetSentryState() {
+    sentryModule = undefined;
+    sentryInitialized = false;
+}
+//# sourceMappingURL=fault-logger.js.map

package/dist/lib/fault-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fault-logger.js","sourceRoot":"","sources":["../../src/lib/fault-logger.ts"],"names":[],"mappings":"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"}

package/dist/lib/graph/centrality.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Graph Centrality — degree centrality computation and recall boost
+ *
+ * Calculates how connected each memory is in the knowledge graph.
+ * More-connected memories get boosted in recall results.
+ */
+import type { GraphCentralityConfig } from '../config.js';
+/**
+ * Calculate degree centrality for all memories from link data.
+ * Degree = count of outgoing links + count of incoming links.
+ */
+export declare function calculateDegreeCentrality(links: Array<{
+    source_id: number;
+    target_id: number;
+}>): Map<number, number>;
+/**
+ * Normalize centrality scores to 0-1 range.
+ */
+export declare function normalizeCentrality(raw: Map<number, number>): Map<number, number>;
+/**
+ * Compute and cache centrality scores via storage dispatcher.
+ */
+export declare function updateCentralityCache(): Promise<{
+    updated: number;
+}>;
+/**
+ * Apply centrality boost to recall results.
+ * Adds boostWeight * normalized_degree to similarity score.
+ */
+export declare function applyCentralityBoost<T extends {
+    id?: number;
+    similarity: number;
+}>(results: T[], config: GraphCentralityConfig): Promise<T[]>;
+//# sourceMappingURL=centrality.d.ts.map

package/dist/lib/graph/centrality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"centrality.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/centrality.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAW1D;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,GACrD,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CASrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAejF;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAa1E;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,SAAS;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EACtF,OAAO,EAAE,CAAC,EAAE,EACZ,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC,CAed"}

package/dist/lib/graph/centrality.js

@@ -0,0 +1,76 @@
+/**
+ * Graph Centrality — degree centrality computation and recall boost
+ *
+ * Calculates how connected each memory is in the knowledge graph.
+ * More-connected memories get boosted in recall results.
+ */
+import { getAllMemoryLinksForExport, upsertCentralityScore, getCentralityScores, } from '../storage/index.js';
+// ============================================================================
+// Degree Centrality
+// ============================================================================
+/**
+ * Calculate degree centrality for all memories from link data.
+ * Degree = count of outgoing links + count of incoming links.
+ */
+export function calculateDegreeCentrality(links) {
+    const degrees = new Map();
+    for (const link of links) {
+        degrees.set(link.source_id, (degrees.get(link.source_id) ?? 0) + 1);
+        degrees.set(link.target_id, (degrees.get(link.target_id) ?? 0) + 1);
+    }
+    return degrees;
+}
+/**
+ * Normalize centrality scores to 0-1 range.
+ */
+export function normalizeCentrality(raw) {
+    if (raw.size === 0)
+        return new Map();
+    let maxDegree = 0;
+    for (const deg of raw.values()) {
+        if (deg > maxDegree)
+            maxDegree = deg;
+    }
+    if (maxDegree === 0)
+        return new Map();
+    const normalized = new Map();
+    for (const [id, deg] of raw) {
+        normalized.set(id, deg / maxDegree);
+    }
+    return normalized;
+}
+/**
+ * Compute and cache centrality scores via storage dispatcher.
+ */
+export async function updateCentralityCache() {
+    const links = await getAllMemoryLinksForExport();
+    const raw = calculateDegreeCentrality(links);
+    const normalized = normalizeCentrality(raw);
+    let count = 0;
+    for (const [memId, deg] of raw) {
+        const norm = normalized.get(memId) ?? 0;
+        await upsertCentralityScore(memId, deg, norm);
+        count++;
+    }
+    return { updated: count };
+}
+/**
+ * Apply centrality boost to recall results.
+ * Adds boostWeight * normalized_degree to similarity score.
+ */
+export async function applyCentralityBoost(results, config) {
+    if (!config.enabled || results.length === 0)
+        return results;
+    const boostWeight = config.boost_weight ?? 0.1;
+    const memoryIds = results.filter((r) => r.id != null).map((r) => r.id);
+    const centralities = await getCentralityScores(memoryIds);
+    const boosted = results.map((r) => {
+        if (r.id == null)
+            return r;
+        const c = centralities.get(r.id) ?? 0;
+        return { ...r, similarity: Math.min(1.0, r.similarity + c * boostWeight) };
+    });
+    boosted.sort((a, b) => b.similarity - a.similarity);
+    return boosted;
+}
+//# sourceMappingURL=centrality.js.map

package/dist/lib/graph/centrality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"centrality.js","sourceRoot":"","sources":["../../../src/lib/graph/centrality.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAsD;IAEtD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAwB;IAC1D,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAErC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;QAC/B,IAAI,GAAG,GAAG,SAAS;YAAE,SAAS,GAAG,GAAG,CAAC;IACvC,CAAC;IAED,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAEtC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;QAC5B,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,GAAG,SAAS,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB;IACzC,MAAM,KAAK,GAAG,MAAM,0BAA0B,EAAE,CAAC;IACjD,MAAM,GAAG,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAE5C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,qBAAqB,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAC9C,KAAK,EAAE,CAAC;IACV,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAY,EACZ,MAA6B;IAE7B,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAE5D,MAAM,WAAW,GAAG,MAAM,CAAC,YAAY,IAAI,GAAG,CAAC;IAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAG,CAAC,CAAC;IACxE,MAAM,YAAY,GAAG,MAAM,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAE1D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAChC,IAAI,CAAC,CAAC,EAAE,IAAI,IAAI;YAAE,OAAO,CAAC,CAAC;QAC3B,MAAM,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QACtC,OAAO,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/lib/graph/cleanup.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Graph cleanup pipeline — prunes weak links, enriches remaining,
+ * connects orphans, rebuilds communities and centrality.
+ *
+ * Composes existing graph functions into a single orchestrated pipeline.
+ */
+import { type CommunityResult } from './community-detection.js';
+export interface CleanupOptions {
+    /** Prune similar_to links below this weight (default 0.75) */
+    pruneThreshold?: number;
+    /** Auto-link orphans with this similarity threshold (default 0.60) */
+    orphanThreshold?: number;
+    /** Max auto-links per orphan (default 3) */
+    orphanMaxLinks?: number;
+    /** Skip LLM enrichment step */
+    skipEnrich?: boolean;
+    /** Skip orphan reconnection step */
+    skipOrphans?: boolean;
+    /** Skip communities + centrality rebuild */
+    skipFinalize?: boolean;
+    /** Preview mode — return counts without mutations */
+    dryRun?: boolean;
+    /** Progress callback for CLI/MCP reporting */
+    onProgress?: (step: string, detail: string) => void;
+}
+export interface CleanupResult {
+    pruned: number;
+    enriched: number;
+    orphansConnected: number;
+    communitiesDetected: number;
+    centralityUpdated: number;
+    /** Full community detection result (for downstream synthesis). Only set when finalize runs. */
+    communityResult?: CommunityResult;
+}
+export declare function graphCleanup(options?: CleanupOptions): Promise<CleanupResult>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/lib/graph/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAGnF,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+FAA+F;IAC/F,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAoHvF"}

package/dist/lib/graph/cleanup.js

@@ -0,0 +1,96 @@
+/**
+ * Graph cleanup pipeline — prunes weak links, enriches remaining,
+ * connects orphans, rebuilds communities and centrality.
+ *
+ * Composes existing graph functions into a single orchestrated pipeline.
+ */
+import { getAllMemoryLinksForExport, deleteMemoryLinksByIds, findIsolatedMemoryIds, createAutoLinks, } from '../storage/index.js';
+import { enrichExistingLinks } from './llm-relations.js';
+import { detectCommunities } from './community-detection.js';
+import { updateCentralityCache } from './centrality.js';
+export async function graphCleanup(options = {}) {
+    const { pruneThreshold = 0.75, orphanThreshold = 0.6, orphanMaxLinks = 3, skipEnrich = false, skipOrphans = false, skipFinalize = false, dryRun = false, onProgress, } = options;
+    const result = {
+        pruned: 0,
+        enriched: 0,
+        orphansConnected: 0,
+        communitiesDetected: 0,
+        centralityUpdated: 0,
+    };
+    // Step 1: Load all links, filter to pruneable similar_to
+    onProgress?.('load', 'Loading all memory links...');
+    const allLinks = await getAllMemoryLinksForExport();
+    const pruneCandidates = allLinks.filter((l) => l.relation === 'similar_to' && l.weight < pruneThreshold && !l.llm_enriched);
+    onProgress?.('load', `Found ${pruneCandidates.length} weak similar_to links (of ${allLinks.length} total)`);
+    // Step 2: Prune weak similar_to links
+    if (pruneCandidates.length > 0) {
+        onProgress?.('prune', `Pruning ${pruneCandidates.length} links below threshold ${pruneThreshold}...`);
+        if (!dryRun) {
+            const idsToDelete = pruneCandidates.map((l) => l.id);
+            result.pruned = await deleteMemoryLinksByIds(idsToDelete);
+        }
+        else {
+            result.pruned = pruneCandidates.length;
+        }
+        onProgress?.('prune', `Pruned ${result.pruned} links`);
+    }
+    // Step 3: Enrich remaining unenriched similar_to via LLM
+    if (!skipEnrich) {
+        onProgress?.('enrich', 'Enriching remaining similar_to links via LLM...');
+        if (!dryRun) {
+            const enrichResult = await enrichExistingLinks();
+            result.enriched = enrichResult.enriched;
+            onProgress?.('enrich', `Enriched ${enrichResult.enriched}, failed ${enrichResult.failed}, skipped ${enrichResult.skipped}`);
+        }
+        else {
+            // Count unenriched similar_to remaining after prune
+            const remaining = allLinks.filter((l) => l.relation === 'similar_to' && !l.llm_enriched && l.weight >= pruneThreshold);
+            result.enriched = remaining.length;
+            onProgress?.('enrich', `Would enrich ~${result.enriched} links`);
+        }
+    }
+    // Step 4: Connect orphans
+    if (!skipOrphans) {
+        onProgress?.('orphans', 'Finding isolated memories...');
+        const orphanIds = await findIsolatedMemoryIds();
+        onProgress?.('orphans', `Found ${orphanIds.length} isolated memories`);
+        if (orphanIds.length > 0) {
+            if (!dryRun) {
+                for (const orphanId of orphanIds) {
+                    const linked = await createAutoLinks(orphanId, orphanThreshold, orphanMaxLinks);
+                    result.orphansConnected += linked > 0 ? 1 : 0;
+                }
+            }
+            else {
+                result.orphansConnected = orphanIds.length; // best estimate
+            }
+            onProgress?.('orphans', `Connected ${result.orphansConnected} of ${orphanIds.length} orphans`);
+        }
+    }
+    // Step 5 & 6: Rebuild communities and centrality
+    if (!skipFinalize) {
+        onProgress?.('communities', 'Detecting communities...');
+        if (!dryRun) {
+            const communityResult = await detectCommunities();
+            result.communitiesDetected = communityResult.communities.length;
+            result.communityResult = communityResult;
+            onProgress?.('communities', `Detected ${result.communitiesDetected} communities (${communityResult.isolated} isolated)`);
+        }
+        else {
+            result.communitiesDetected = -1; // unknown in dry-run
+            onProgress?.('communities', 'Skipped (dry-run)');
+        }
+        onProgress?.('centrality', 'Updating centrality scores...');
+        if (!dryRun) {
+            const centralityResult = await updateCentralityCache();
+            result.centralityUpdated = centralityResult.updated;
+            onProgress?.('centrality', `Updated ${result.centralityUpdated} centrality scores`);
+        }
+        else {
+            result.centralityUpdated = -1; // unknown in dry-run
+            onProgress?.('centrality', 'Skipped (dry-run)');
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/lib/graph/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../../src/lib/graph/cleanup.ts"],"names":[],"mappings":"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"}

package/dist/lib/graph/community-detection.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Community Detection — Label Propagation Algorithm
+ *
+ * Automatically groups memories into thematic communities
+ * based on graph structure. Pure TypeScript, no external deps.
+ *
+ * Inspired by rahulnyk/knowledge_graph's Girvan-Newman approach,
+ * but using Label Propagation which is faster and simpler.
+ */
+/**
+ * Build adjacency list from memory_links table.
+ * Returns undirected graph: each edge appears in both directions.
+ */
+export declare function buildAdjacencyList(links: Array<{
+    source_id: number;
+    target_id: number;
+    weight: number;
+}>): Map<number, Array<{
+    neighbor: number;
+    weight: number;
+}>>;
+/**
+ * Label Propagation Algorithm.
+ *
+ * 1. Each node gets its own ID as label
+ * 2. Iteratively: each node adopts the most frequent weighted label of its neighbors
+ * 3. Converges when no labels change
+ *
+ * @returns Map of nodeId → communityId
+ */
+export declare function labelPropagation(adjacency: Map<number, Array<{
+    neighbor: number;
+    weight: number;
+}>>, maxIterations?: number, seed?: number): Map<number, number>;
+/**
+ * Renumber communities from 0..N for clean output.
+ */
+export declare function renumberCommunities(labels: Map<number, number>): Map<number, number>;
+export interface CommunityResult {
+    communities: Array<{
+        id: number;
+        size: number;
+        members: number[];
+    }>;
+    isolated: number;
+    iterations: number;
+}
+/**
+ * Detect communities in the memory graph.
+ * Updates memory tags with community:N assignments.
+ */
+export declare function detectCommunities(options?: {
+    maxIterations?: number;
+    minCommunitySize?: number;
+    tagPrefix?: string;
+}): Promise<CommunityResult>;
+/**
+ * Get community assignment for a specific memory from its tags.
+ */
+export declare function getMemoryCommunity(memoryId: number, tagPrefix?: string): Promise<number | null>;
+//# sourceMappingURL=community-detection.d.ts.map

package/dist/lib/graph/community-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"community-detection.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/community-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GACrE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAe1D;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,EACnE,aAAa,GAAE,MAAY,EAC3B,IAAI,GAAE,MAAW,GAChB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAgDrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAapF;AAMD,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACtF,OAAO,CAAC,eAAe,CAAC,CA6E1B;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAAoB,GAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqBxB"}