causantic 0.2.0

package/dist/hooks/hook-utils.js

@@ -0,0 +1,187 @@
+/**
+ * Hook utilities for error recovery, logging, and metrics.
+ *
+ * Provides:
+ * - Structured JSON logging
+ * - Retry logic with exponential backoff
+ * - Hook execution metrics
+ * - Graceful degradation on failure
+ */
+// Global configuration
+let hookConfig = {
+    enableLogging: process.env.CAUSANTIC_HOOK_LOGGING === 'true',
+    logLevel: process.env.CAUSANTIC_HOOK_LOG_LEVEL ?? 'info',
+};
+/**
+ * Configure hook utilities.
+ */
+export function configureHooks(config) {
+    hookConfig = { ...hookConfig, ...config };
+}
+/**
+ * Log a structured message.
+ */
+export function logHook(entry) {
+    if (!hookConfig.enableLogging)
+        return;
+    const levels = ['debug', 'info', 'warn', 'error'];
+    const configLevel = levels.indexOf(hookConfig.logLevel ?? 'info');
+    const entryLevel = levels.indexOf(entry.level);
+    if (entryLevel < configLevel)
+        return;
+    const logEntry = {
+        timestamp: new Date().toISOString(),
+        ...entry,
+    };
+    // Write to stderr to avoid interfering with hook output
+    process.stderr.write(JSON.stringify(logEntry) + '\n');
+}
+/**
+ * Calculate exponential backoff delay.
+ */
+function calculateBackoff(attempt, initialDelayMs, maxDelayMs, backoffFactor) {
+    const delay = initialDelayMs * Math.pow(backoffFactor, attempt);
+    return Math.min(delay, maxDelayMs);
+}
+/**
+ * Sleep for a duration.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Execute a function with retry logic.
+ */
+export async function withRetry(hookName, fn, options = {}) {
+    const { maxRetries = 3, initialDelayMs = 1000, maxDelayMs = 10000, backoffFactor = 2, retryOn = () => true, } = options;
+    let lastError = null;
+    let retryCount = 0;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            if (attempt > 0) {
+                const delay = calculateBackoff(attempt - 1, initialDelayMs, maxDelayMs, backoffFactor);
+                logHook({
+                    level: 'info',
+                    hook: hookName,
+                    event: 'retry_attempt',
+                    details: { attempt, delay, maxRetries },
+                });
+                await sleep(delay);
+                retryCount++;
+            }
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            logHook({
+                level: attempt === maxRetries ? 'error' : 'warn',
+                hook: hookName,
+                event: attempt === maxRetries ? 'retry_exhausted' : 'retry_error',
+                error: lastError.message,
+                details: { attempt, maxRetries },
+            });
+            // Check if we should retry this error
+            if (!retryOn(lastError)) {
+                throw lastError;
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Create a metrics tracker for a hook execution.
+ */
+export function createMetrics(hookName) {
+    return {
+        hookName,
+        startTime: Date.now(),
+        retryCount: 0,
+    };
+}
+/**
+ * Complete metrics tracking.
+ */
+export function completeMetrics(metrics, success, error) {
+    metrics.endTime = Date.now();
+    metrics.durationMs = metrics.endTime - metrics.startTime;
+    metrics.success = success;
+    if (error) {
+        metrics.error = error.message;
+    }
+    return metrics;
+}
+/**
+ * Wrap a hook function with logging, metrics, and error handling.
+ */
+export async function executeHook(hookName, fn, options = {}) {
+    const metrics = createMetrics(hookName);
+    logHook({
+        level: 'info',
+        hook: hookName,
+        event: 'hook_started',
+    });
+    try {
+        let result;
+        if (options.retry) {
+            result = await withRetry(hookName, fn, options.retry);
+        }
+        else {
+            result = await fn();
+        }
+        completeMetrics(metrics, true);
+        logHook({
+            level: 'info',
+            hook: hookName,
+            event: 'hook_completed',
+            durationMs: metrics.durationMs,
+        });
+        return { result, metrics };
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        completeMetrics(metrics, false, err);
+        logHook({
+            level: 'error',
+            hook: hookName,
+            event: 'hook_failed',
+            durationMs: metrics.durationMs,
+            error: err.message,
+        });
+        // Use fallback if provided (graceful degradation)
+        if (options.fallback !== undefined) {
+            logHook({
+                level: 'warn',
+                hook: hookName,
+                event: 'using_fallback',
+            });
+            return { result: options.fallback, metrics };
+        }
+        throw error;
+    }
+}
+/**
+ * Check if an error is transient (worth retrying).
+ */
+export function isTransientError(error) {
+    const message = error.message.toLowerCase();
+    // Network/connectivity errors
+    if (message.includes('econnreset') ||
+        message.includes('econnrefused') ||
+        message.includes('etimedout') ||
+        message.includes('enotfound') ||
+        message.includes('network')) {
+        return true;
+    }
+    // Database busy/locked errors
+    if (message.includes('database is locked') ||
+        message.includes('busy') ||
+        message.includes('sqlite_busy')) {
+        return true;
+    }
+    // Rate limiting
+    if (message.includes('rate limit') || message.includes('too many requests')) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=hook-utils.js.map

package/dist/hooks/hook-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-utils.js","sourceRoot":"","sources":["../../src/hooks/hook-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8CH,uBAAuB;AACvB,IAAI,UAAU,GAAe;IAC3B,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,KAAK,MAAM;IAC5D,QAAQ,EAAG,OAAO,CAAC,GAAG,CAAC,wBAAmD,IAAI,MAAM;CACrF,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAA2B;IACxD,UAAU,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,MAAM,EAAE,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,KAAsC;IAC5D,IAAI,CAAC,UAAU,CAAC,aAAa;QAAE,OAAO;IAEtC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,IAAI,MAAM,CAAC,CAAC;IAClE,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAE/C,IAAI,UAAU,GAAG,WAAW;QAAE,OAAO;IAErC,MAAM,QAAQ,GAAiB;QAC7B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,GAAG,KAAK;KACT,CAAC;IAEF,wDAAwD;IACxD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CACvB,OAAe,EACf,cAAsB,EACtB,UAAkB,EAClB,aAAqB;IAErB,MAAM,KAAK,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,EAAoB,EACpB,UAAwB,EAAE;IAE1B,MAAM,EACJ,UAAU,GAAG,CAAC,EACd,cAAc,GAAG,IAAI,EACrB,UAAU,GAAG,KAAK,EAClB,aAAa,GAAG,CAAC,EACjB,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,GACrB,GAAG,OAAO,CAAC;IAEZ,IAAI,SAAS,GAAiB,IAAI,CAAC;IACnC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBAChB,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,GAAG,CAAC,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;gBAEvF,OAAO,CAAC;oBACN,KAAK,EAAE,MAAM;oBACb,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE,eAAe;oBACtB,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE;iBACxC,CAAC,CAAC;gBAEH,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;gBACnB,UAAU,EAAE,CAAC;YACf,CAAC;YAED,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAEtE,OAAO,CAAC;gBACN,KAAK,EAAE,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;gBAChD,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,aAAa;gBACjE,KAAK,EAAE,SAAS,CAAC,OAAO;gBACxB,OAAO,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE;aACjC,CAAC,CAAC;YAEH,sCAAsC;YACtC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;gBACxB,MAAM,SAAS,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,OAAO;QACL,QAAQ;QACR,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,UAAU,EAAE,CAAC;KACd,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAoB,EACpB,OAAgB,EAChB,KAAa;IAEb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,OAAO,CAAC,UAAU,GAAG,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IACzD,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC;IAC1B,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC;IAChC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,EAAoB,EACpB,UAGI,EAAE;IAEN,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAExC,OAAO,CAAC;QACN,KAAK,EAAE,MAAM;QACb,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,cAAc;KACtB,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,IAAI,MAAS,CAAC;QAEd,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QACtB,CAAC;QAED,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAE/B,OAAO,CAAC;YACN,KAAK,EAAE,MAAM;YACb,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,gBAAgB;YACvB,UAAU,EAAE,OAAO,CAAC,UAAU;SAC/B,CAAC,CAAC;QAEH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACtE,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAErC,OAAO,CAAC;YACN,KAAK,EAAE,OAAO;YACd,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,aAAa;YACpB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,KAAK,EAAE,GAAG,CAAC,OAAO;SACnB,CAAC,CAAC;QAEH,kDAAkD;QAClD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnC,OAAO,CAAC;gBACN,KAAK,EAAE,MAAM;gBACb,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,gBAAgB;aACxB,CAAC,CAAC;YACH,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;QAC/C,CAAC;QAED,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAY;IAC3C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAE5C,8BAA8B;IAC9B,IACE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;QAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAC3B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8BAA8B;IAC9B,IACE,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;QACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,EAC/B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gBAAgB;IAChB,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC5E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hook handlers exports.
+ */
+export { executeHook, withRetry, logHook, configureHooks, createMetrics, completeMetrics, isTransientError, } from './hook-utils.js';
+export type { HookLogEntry, HookMetrics, RetryOptions, HookConfig, } from './hook-utils.js';
+export { handlePreCompact, preCompactCli } from './pre-compact.js';
+export type { PreCompactResult, PreCompactOptions } from './pre-compact.js';
+export { handleSessionStart, generateMemorySection } from './session-start.js';
+export type { SessionStartOptions, SessionStartResult } from './session-start.js';
+export { updateClaudeMd, removeMemorySection, hasMemorySection } from './claudemd-generator.js';
+export type { ClaudeMdOptions, ClaudeMdResult } from './claudemd-generator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,WAAW,EACX,SAAS,EACT,OAAO,EACP,cAAc,EACd,aAAa,EACb,eAAe,EACf,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,GACX,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGlF,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChG,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,12 @@
+/**
+ * Hook handlers exports.
+ */
+// Hook utilities
+export { executeHook, withRetry, logHook, configureHooks, createMetrics, completeMetrics, isTransientError, } from './hook-utils.js';
+// Pre-compact hook
+export { handlePreCompact, preCompactCli } from './pre-compact.js';
+// Session start hook
+export { handleSessionStart, generateMemorySection } from './session-start.js';
+// CLAUDE.md generator
+export { updateClaudeMd, removeMemorySection, hasMemorySection } from './claudemd-generator.js';
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,iBAAiB;AACjB,OAAO,EACL,WAAW,EACX,SAAS,EACT,OAAO,EACP,cAAc,EACd,aAAa,EACb,eAAe,EACf,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAQzB,mBAAmB;AACnB,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGnE,qBAAqB;AACrB,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAG/E,sBAAsB;AACtB,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/hooks/pre-compact.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pre-compact hook handler.
+ * Called before a Claude Code session is compacted.
+ * Ingests the session into the memory system.
+ *
+ * Features:
+ * - Retry logic for transient errors
+ * - Structured JSON logging
+ * - Execution metrics
+ * - Graceful degradation on failure
+ */
+import { type HookMetrics } from './hook-utils.js';
+/**
+ * Result of pre-compact hook execution.
+ */
+export interface PreCompactResult {
+    /** Session ID that was ingested */
+    sessionId: string;
+    /** Number of chunks created */
+    chunkCount: number;
+    /** Number of edges created */
+    edgeCount: number;
+    /** Number of clusters the new chunks were assigned to */
+    clustersAssigned: number;
+    /** Time taken in milliseconds */
+    durationMs: number;
+    /** Whether ingestion was skipped (already existed) */
+    skipped: boolean;
+    /** Hook execution metrics */
+    metrics?: HookMetrics;
+    /** Whether this is a fallback result due to error */
+    degraded?: boolean;
+}
+/**
+ * Options for pre-compact hook.
+ */
+export interface PreCompactOptions {
+    /** Enable retry on transient errors. Default: true */
+    enableRetry?: boolean;
+    /** Maximum retries. Default: 3 */
+    maxRetries?: number;
+    /** Return fallback on total failure. Default: true */
+    gracefulDegradation?: boolean;
+}
+/**
+ * Handle pre-compact hook.
+ * Called by Claude Code before session compaction.
+ *
+ * @param sessionPath - Path to the session JSONL file
+ * @param options - Hook options
+ * @returns Result of the ingestion
+ */
+export declare function handlePreCompact(sessionPath: string, options?: PreCompactOptions): Promise<PreCompactResult>;
+/**
+ * CLI entry point for pre-compact hook.
+ */
+export declare function preCompactCli(sessionPath: string): Promise<void>;
+//# sourceMappingURL=pre-compact.d.ts.map

package/dist/hooks/pre-compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pre-compact.d.ts","sourceRoot":"","sources":["../../src/hooks/pre-compact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAKzB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAyDD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAoC3B;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBtE"}

package/dist/hooks/pre-compact.js

@@ -0,0 +1,127 @@
+/**
+ * Pre-compact hook handler.
+ * Called before a Claude Code session is compacted.
+ * Ingests the session into the memory system.
+ *
+ * Features:
+ * - Retry logic for transient errors
+ * - Structured JSON logging
+ * - Execution metrics
+ * - Graceful degradation on failure
+ */
+import { ingestSession } from '../ingest/ingest-session.js';
+import { clusterManager } from '../clusters/cluster-manager.js';
+import { vectorStore } from '../storage/vector-store.js';
+import { executeHook, logHook, isTransientError, } from './hook-utils.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('pre-compact');
+/**
+ * Internal handler without retry logic.
+ */
+async function internalHandlePreCompact(sessionPath) {
+    const startTime = Date.now();
+    // Ingest the session
+    const ingestResult = await ingestSession(sessionPath, {
+        skipIfExists: true,
+        linkCrossSessions: true,
+    });
+    if (ingestResult.skipped) {
+        return {
+            sessionId: ingestResult.sessionId,
+            chunkCount: 0,
+            edgeCount: 0,
+            clustersAssigned: 0,
+            durationMs: Date.now() - startTime,
+            skipped: true,
+        };
+    }
+    // Assign new chunks to existing clusters
+    let clustersAssigned = 0;
+    if (ingestResult.chunkCount > 0) {
+        try {
+            // Get the newly created chunk embeddings
+            const vectors = await vectorStore.getAllVectors();
+            // Filter to just the new session's chunks (rough heuristic: recent ones)
+            const recentVectors = vectors.slice(-ingestResult.chunkCount);
+            const assignResult = await clusterManager.assignNewChunks(recentVectors);
+            clustersAssigned = assignResult.assigned;
+        }
+        catch (error) {
+            // Log but don't fail - cluster assignment is secondary
+            logHook({
+                level: 'warn',
+                hook: 'pre-compact',
+                event: 'cluster_assignment_failed',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return {
+        sessionId: ingestResult.sessionId,
+        chunkCount: ingestResult.chunkCount,
+        edgeCount: ingestResult.edgeCount,
+        clustersAssigned,
+        durationMs: Date.now() - startTime,
+        skipped: false,
+    };
+}
+/**
+ * Handle pre-compact hook.
+ * Called by Claude Code before session compaction.
+ *
+ * @param sessionPath - Path to the session JSONL file
+ * @param options - Hook options
+ * @returns Result of the ingestion
+ */
+export async function handlePreCompact(sessionPath, options = {}) {
+    const { enableRetry = true, maxRetries = 3, gracefulDegradation = true, } = options;
+    const fallbackResult = {
+        sessionId: 'unknown',
+        chunkCount: 0,
+        edgeCount: 0,
+        clustersAssigned: 0,
+        durationMs: 0,
+        skipped: false,
+        degraded: true,
+    };
+    const { result, metrics } = await executeHook('pre-compact', () => internalHandlePreCompact(sessionPath), {
+        retry: enableRetry
+            ? {
+                maxRetries,
+                retryOn: isTransientError,
+            }
+            : undefined,
+        fallback: gracefulDegradation ? fallbackResult : undefined,
+    });
+    return {
+        ...result,
+        metrics,
+        durationMs: metrics.durationMs ?? result.durationMs,
+    };
+}
+/**
+ * CLI entry point for pre-compact hook.
+ */
+export async function preCompactCli(sessionPath) {
+    try {
+        const result = await handlePreCompact(sessionPath);
+        if (result.degraded) {
+            log.error('Pre-compact hook ran in degraded mode due to errors.');
+            process.exit(1);
+        }
+        if (result.skipped) {
+            log.info(`Session ${result.sessionId} already ingested, skipped.`);
+        }
+        else {
+            log.info(`Ingested session ${result.sessionId}: Chunks: ${result.chunkCount}, Edges: ${result.edgeCount}, Clusters assigned: ${result.clustersAssigned}, Duration: ${result.durationMs}ms`);
+            if (result.metrics?.retryCount && result.metrics.retryCount > 0) {
+                log.info(`Retries: ${result.metrics.retryCount}`);
+            }
+        }
+    }
+    catch (error) {
+        log.error('Pre-compact hook failed:', { error: error instanceof Error ? error.message : String(error) });
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=pre-compact.js.map

package/dist/hooks/pre-compact.js.map

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

package/dist/hooks/session-start.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Session start hook handler.
+ * Called when a new Claude Code session starts.
+ * Returns memory context summary for the project.
+ *
+ * Features:
+ * - Retry logic for transient errors
+ * - Structured JSON logging
+ * - Execution metrics
+ * - Graceful degradation on failure
+ */
+import { type HookMetrics } from './hook-utils.js';
+/**
+ * Options for session start handler.
+ */
+export interface SessionStartOptions {
+    /** Maximum tokens for memory summary. Default: from config. */
+    maxTokens?: number;
+    /** Number of recent chunks to include. Default: 3. */
+    includeRecent?: number;
+    /** Number of cross-project clusters to include. Default: 2. */
+    includeCrossProject?: number;
+    /** Enable retry on transient errors. Default: true */
+    enableRetry?: boolean;
+    /** Maximum retries. Default: 3 */
+    maxRetries?: number;
+    /** Return fallback on total failure. Default: true */
+    gracefulDegradation?: boolean;
+}
+/**
+ * Result of session start handler.
+ */
+export interface SessionStartResult {
+    /** Memory summary text */
+    summary: string;
+    /** Token count */
+    tokenCount: number;
+    /** Clusters included */
+    clustersIncluded: number;
+    /** Recent chunks included */
+    recentChunksIncluded: number;
+    /** Whether last session summary was included */
+    lastSessionIncluded: boolean;
+    /** Hook execution metrics */
+    metrics?: HookMetrics;
+    /** Whether this is a fallback result due to error */
+    degraded?: boolean;
+}
+/**
+ * Handle session start.
+ * Generates a memory summary for the project.
+ *
+ * @param projectPath - Project path (used as session slug)
+ * @param options - Session start options
+ * @returns Memory summary result
+ */
+export declare function handleSessionStart(projectPath: string, options?: SessionStartOptions): Promise<SessionStartResult>;
+/**
+ * Generate memory section for CLAUDE.md.
+ */
+export declare function generateMemorySection(projectPath: string, options?: SessionStartOptions): Promise<string>;
+//# sourceMappingURL=session-start.d.ts.map

package/dist/hooks/session-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-start.d.ts","sourceRoot":"","sources":["../../src/hooks/session-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAGzB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,mBAAmB,EAAE,OAAO,CAAC;IAC7B,6BAA6B;IAC7B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAuHD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAsC7B;AAwGD;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,CAuBjB"}