claude-mem 3.3.7 → 3.3.9

package/dist/shared/error-handler.js

@@ -0,0 +1,142 @@
+import { existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { HookError, CompressionError, FileLogger } from './types.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export class ErrorHandler {
+    logger;
+    logDir;
+    // <Block> 7.1 ====================================
+    constructor(enableDebug = false) {
+        this.logDir = join(__dirname, '..', 'logs');
+        this.ensureLogDirectory();
+        const logFile = join(this.logDir, `claude-mem-${new Date().toISOString().slice(0, 10)}.log`);
+        this.logger = new FileLogger(logFile, enableDebug);
+    }
+    // </Block> =======================================
+    // <Block> 7.2 ====================================
+    ensureLogDirectory() {
+        if (!existsSync(this.logDir)) {
+            mkdirSync(this.logDir, { recursive: true });
+        }
+    }
+    // </Block> =======================================
+    // <Block> 7.3 ====================================
+    handleHookError(error, hookType, payload) {
+        // <Block> 7.3a ====================================
+        const hookError = error instanceof HookError
+            ? error
+            : new HookError(error.message, hookType, payload, 'HOOK_EXECUTION_ERROR');
+        // </Block> =======================================
+        this.logger.error(`Hook execution failed in ${hookType}`, hookError, {
+            hookType,
+            payload: payload ? JSON.stringify(payload) : undefined,
+        });
+        console.log(JSON.stringify({
+            continue: false,
+            stopReason: `Hook error: ${hookError.message}`,
+            error: {
+                type: hookError.name,
+                message: hookError.message,
+                code: hookError.code,
+            },
+        }));
+        process.exit(1);
+    }
+    // </Block> =======================================
+    // <Block> 7.4 ====================================
+    handleCompressionError(error, transcriptPath, stage) {
+        // <Block> 7.4a ====================================
+        const compressionError = error instanceof CompressionError
+            ? error
+            : new CompressionError(error.message, transcriptPath, stage);
+        // </Block> =======================================
+        this.logger.error(`Compression failed during ${stage}`, compressionError, {
+            transcriptPath,
+            stage,
+        });
+        console.error(`Compression error: ${compressionError.message}`);
+        console.error(`Stage: ${stage}`);
+        console.error(`Transcript: ${transcriptPath}`);
+        process.exit(1);
+    }
+    // </Block> =======================================
+    // <Block> 7.5 ====================================
+    handleValidationError(message, context) {
+        this.logger.error('Validation error', undefined, { message, context });
+        console.error(`Validation error: ${message}`);
+        // <Block> 7.5a ====================================
+        if (context) {
+            console.error('Context:', JSON.stringify(context, null, 2));
+        }
+        // </Block> =======================================
+        process.exit(1);
+    }
+    // </Block> =======================================
+    // <Block> 7.6 ====================================
+    logSuccess(operation, details) {
+        this.logger.info(`Operation successful: ${operation}`, details);
+    }
+    // </Block> =======================================
+    // <Block> 7.7 ====================================
+    logWarning(message, details) {
+        this.logger.warn(message, details);
+    }
+    // </Block> =======================================
+    // <Block> 7.8 ====================================
+    logDebug(message, details) {
+        this.logger.debug(message, details);
+    }
+}
+// <Block> 7.9 ====================================
+export function parseStdinJson(input) {
+    try {
+        return JSON.parse(input);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse JSON input: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+// </Block> =======================================
+// <Block> 7.10 ===================================
+export async function safeExecute(operation, errorHandler, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const message = `Safe execution failed in ${context}: ${error instanceof Error ? error.message : String(error)}`;
+        errorHandler.handleValidationError(message, { context, error });
+        throw error;
+    }
+}
+// </Block> =======================================
+// <Block> 7.11 ===================================
+export function validateFileExists(filePath, errorHandler) {
+    if (!existsSync(filePath)) {
+        errorHandler.handleValidationError(`File not found: ${filePath}`, {
+            filePath,
+        });
+    }
+}
+// </Block> =======================================
+// <Block> 7.12 ===================================
+/**
+ * Creates a standardized hook response using HookTemplates
+ * @deprecated Use HookTemplates.createHookSuccessResponse or createHookErrorResponse instead
+ * This function is maintained for backward compatibility but should be replaced with HookTemplates.
+ */
+export function createHookResponse(success, data) {
+    // Log deprecation warning in development mode
+    if (process.env.NODE_ENV === 'development') {
+        console.warn('createHookResponse in error-handler.ts is deprecated. Use HookTemplates.createHookSuccessResponse or createHookErrorResponse instead.');
+    }
+    const response = {
+        continue: success,
+        suppressOutput: true, // Add standard suppressOutput field for Claude Code compatibility
+        ...data,
+    };
+    return JSON.stringify(response);
+}
+// </Block> =======================================
+export const globalErrorHandler = new ErrorHandler(process.env.DEBUG === 'true');

package/dist/shared/logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Simple logging utility for claude-mem
+ */
+export interface LogLevel {
+    DEBUG: number;
+    INFO: number;
+    WARN: number;
+    ERROR: number;
+}
+declare class Logger {
+    private level;
+    setLevel(level: keyof LogLevel): void;
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, error?: any, context?: any): void;
+}
+export declare const log: Logger;
+export {};

package/dist/shared/logger.js

@@ -0,0 +1,51 @@
+/**
+ * Simple logging utility for claude-mem
+ */
+const LOG_LEVELS = {
+    DEBUG: 0,
+    INFO: 1,
+    WARN: 2,
+    ERROR: 3,
+};
+class Logger {
+    // <Block> 2.1 ====================================
+    level = LOG_LEVELS.INFO;
+    setLevel(level) {
+        this.level = LOG_LEVELS[level];
+    }
+    // </Block> =======================================
+    // <Block> 2.2 ====================================
+    debug(message, ...args) {
+        if (this.level <= LOG_LEVELS.DEBUG) {
+            console.debug(`[DEBUG] ${message}`, ...args);
+        }
+    }
+    // </Block> =======================================
+    // <Block> 2.3 ====================================
+    info(message, ...args) {
+        if (this.level <= LOG_LEVELS.INFO) {
+            console.info(`[INFO] ${message}`, ...args);
+        }
+    }
+    // </Block> =======================================
+    // <Block> 2.4 ====================================
+    warn(message, ...args) {
+        if (this.level <= LOG_LEVELS.WARN) {
+            console.warn(`[WARN] ${message}`, ...args);
+        }
+    }
+    // </Block> =======================================
+    // <Block> 2.5 ====================================
+    error(message, error, context) {
+        if (this.level <= LOG_LEVELS.ERROR) {
+            console.error(`[ERROR] ${message}`);
+            if (error) {
+                console.error(error);
+            }
+            if (context) {
+                console.error('Context:', context);
+            }
+        }
+    }
+}
+export const log = new Logger();

package/dist/shared/paths.d.ts

@@ -0,0 +1,28 @@
+/**
+ * PathResolver utility for managing claude-mem file system paths
+ */
+export declare class PathResolver {
+    private baseDir;
+    constructor();
+    getConfigDir(): string;
+    getIndexDir(): string;
+    getIndexPath(): string;
+    getArchiveDir(): string;
+    getProjectArchiveDir(projectName: string): string;
+    getLogsDir(): string;
+    static ensureDirectory(dirPath: string): void;
+    static ensureDirectories(dirPaths: string[]): void;
+    static extractProjectName(transcriptPath: string): string;
+    /**
+     * DRY utility function: Canonical source for getting the current project prefix
+     * Replaces all instances of path.basename(process.cwd()) across the codebase
+     * @returns The current project directory name, sanitized for use as a prefix
+     */
+    static getCurrentProjectPrefix(): string;
+    /**
+     * DRY utility function: Gets raw project name without sanitization
+     * For use in contexts where original directory name is needed (e.g., display)
+     * @returns The current project directory name as-is
+     */
+    static getCurrentProjectName(): string;
+}

package/dist/shared/paths.js

@@ -0,0 +1,100 @@
+import { join } from 'path';
+import { homedir } from 'os';
+import { existsSync, mkdirSync } from 'fs';
+/**
+ * PathResolver utility for managing claude-mem file system paths
+ */
+export class PathResolver {
+    baseDir;
+    // <Block> 1.1 ====================================
+    constructor() {
+        this.baseDir = join(homedir(), '.claude-mem');
+    }
+    // </Block> =======================================
+    // <Block> 1.2 ====================================
+    getConfigDir() {
+        return this.baseDir;
+    }
+    // </Block> =======================================
+    // <Block> 1.3 ====================================
+    getIndexDir() {
+        return this.baseDir;
+    }
+    // </Block> =======================================
+    // <Block> 1.4 ====================================
+    getIndexPath() {
+        return join(this.baseDir, 'claude-mem-index.jsonl');
+    }
+    // </Block> =======================================
+    // <Block> 1.5 ====================================
+    getArchiveDir() {
+        return join(this.baseDir, 'archives');
+    }
+    // </Block> =======================================
+    // <Block> 1.6 ====================================
+    getProjectArchiveDir(projectName) {
+        return join(this.getArchiveDir(), projectName);
+    }
+    // </Block> =======================================
+    // <Block> 1.7 ====================================
+    getLogsDir() {
+        return join(this.baseDir, 'logs');
+    }
+    // </Block> =======================================
+    // <Block> 1.8 ====================================
+    static ensureDirectory(dirPath) {
+        if (!existsSync(dirPath)) {
+            mkdirSync(dirPath, { recursive: true });
+        }
+    }
+    // </Block> =======================================
+    // <Block> 1.9 ====================================
+    static ensureDirectories(dirPaths) {
+        dirPaths.forEach(dirPath => PathResolver.ensureDirectory(dirPath));
+    }
+    // </Block> =======================================
+    // <Block> 1.10 ===================================
+    static extractProjectName(transcriptPath) {
+        // Try to extract project name from path
+        const pathParts = transcriptPath.split('/');
+        // <Block> 1.10a =================================
+        // Look for common project indicators
+        const projectIndicators = ['src', 'lib', 'app', 'project', 'workspace'];
+        for (let i = pathParts.length - 1; i >= 0; i--) {
+            if (projectIndicators.includes(pathParts[i]) && i > 0) {
+                return pathParts[i - 1];
+            }
+        }
+        // </Block> =======================================
+        // <Block> 1.10b =================================
+        // Fallback to directory name containing the transcript
+        if (pathParts.length > 1) {
+            return pathParts[pathParts.length - 2];
+        }
+        // </Block> =======================================
+        // Ultimate fallback
+        return 'unknown-project';
+    }
+    // <Block> 1.11 ===================================
+    /**
+     * DRY utility function: Canonical source for getting the current project prefix
+     * Replaces all instances of path.basename(process.cwd()) across the codebase
+     * @returns The current project directory name, sanitized for use as a prefix
+     */
+    static getCurrentProjectPrefix() {
+        const cwd = process.cwd();
+        const pathParts = cwd.split('/');
+        const folderName = pathParts[pathParts.length - 1];
+        return folderName.replace(/-/g, '_');
+    }
+    // </Block> =======================================
+    // <Block> 1.12 ===================================
+    /**
+     * DRY utility function: Gets raw project name without sanitization
+     * For use in contexts where original directory name is needed (e.g., display)
+     * @returns The current project directory name as-is
+     */
+    static getCurrentProjectName() {
+        return require('path').basename(process.cwd());
+    }
+}

package/dist/shared/settings.d.ts

@@ -0,0 +1,41 @@
+import type { Settings } from './types.js';
+/**
+ * Settings utilities for managing ~/.claude-mem/settings.json
+ */
+export declare class SettingsManager {
+    private static settingsPath;
+    private static cachedSettings;
+    /**
+     * Safely read settings.json with error handling
+     * Returns empty object if file doesn't exist or is malformed
+     */
+    static readSettings(): Settings;
+    /**
+     * Get a specific setting value with optional fallback
+     */
+    static getSetting<K extends keyof Settings>(key: K, fallback?: Settings[K]): Settings[K] | undefined;
+    /**
+     * Get the Claude binary path from settings
+     * Falls back to 'claude' if not found or settings don't exist
+     */
+    static getClaudePath(): string;
+    /**
+     * Clear cached settings (useful for testing or after settings changes)
+     */
+    static clearCache(): void;
+}
+/**
+ * Convenience function to get Claude binary path
+ * Can be imported directly for simple use cases
+ */
+export declare function getClaudePath(): string;
+/**
+ * Convenience function to read all settings
+ * Can be imported directly for simple use cases
+ */
+export declare function readSettings(): Settings;
+/**
+ * Convenience function to get a specific setting
+ * Can be imported directly for simple use cases
+ */
+export declare function getSetting<K extends keyof Settings>(key: K, fallback?: Settings[K]): Settings[K] | undefined;

package/dist/shared/settings.js

@@ -0,0 +1,81 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { PathResolver } from './paths.js';
+/**
+ * Settings utilities for managing ~/.claude-mem/settings.json
+ */
+export class SettingsManager {
+    static settingsPath;
+    static cachedSettings = null;
+    static {
+        const pathResolver = new PathResolver();
+        this.settingsPath = join(pathResolver.getConfigDir(), 'settings.json');
+    }
+    /**
+     * Safely read settings.json with error handling
+     * Returns empty object if file doesn't exist or is malformed
+     */
+    static readSettings() {
+        // Return cached settings if available
+        if (this.cachedSettings !== null) {
+            return this.cachedSettings;
+        }
+        try {
+            if (existsSync(this.settingsPath)) {
+                const content = readFileSync(this.settingsPath, 'utf-8');
+                const settings = JSON.parse(content);
+                this.cachedSettings = settings;
+                return settings;
+            }
+        }
+        catch {
+            // File is malformed or unreadable - return empty settings
+        }
+        // File doesn't exist or failed to read
+        const emptySettings = {};
+        this.cachedSettings = emptySettings;
+        return emptySettings;
+    }
+    /**
+     * Get a specific setting value with optional fallback
+     */
+    static getSetting(key, fallback) {
+        const settings = this.readSettings();
+        return settings[key] ?? fallback;
+    }
+    /**
+     * Get the Claude binary path from settings
+     * Falls back to 'claude' if not found or settings don't exist
+     */
+    static getClaudePath() {
+        const claudePath = this.getSetting('claudePath', 'claude');
+        return claudePath;
+    }
+    /**
+     * Clear cached settings (useful for testing or after settings changes)
+     */
+    static clearCache() {
+        this.cachedSettings = null;
+    }
+}
+/**
+ * Convenience function to get Claude binary path
+ * Can be imported directly for simple use cases
+ */
+export function getClaudePath() {
+    return SettingsManager.getClaudePath();
+}
+/**
+ * Convenience function to read all settings
+ * Can be imported directly for simple use cases
+ */
+export function readSettings() {
+    return SettingsManager.readSettings();
+}
+/**
+ * Convenience function to get a specific setting
+ * Can be imported directly for simple use cases
+ */
+export function getSetting(key, fallback) {
+    return SettingsManager.getSetting(key, fallback);
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,145 @@
+export interface HookPayload {
+    session_id: string;
+    transcript_path: string;
+    hook_event_name: string;
+}
+export interface PreCompactPayload extends HookPayload {
+    hook_event_name: 'PreCompact';
+    trigger: 'manual' | 'auto';
+    custom_instructions?: string;
+}
+export interface SessionStartPayload extends HookPayload {
+    hook_event_name: 'SessionStart';
+    source: 'startup' | 'compact' | 'vscode' | 'web';
+}
+export interface UserPromptSubmitPayload extends HookPayload {
+    hook_event_name: 'UserPromptSubmit';
+    prompt: string;
+    cwd: string;
+}
+export interface PreToolUsePayload extends HookPayload {
+    hook_event_name: 'PreToolUse';
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+}
+export interface PostToolUsePayload extends HookPayload {
+    hook_event_name: 'PostToolUse';
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    tool_response: Record<string, unknown> & {
+        success?: boolean;
+    };
+}
+export interface NotificationPayload extends HookPayload {
+    hook_event_name: 'Notification';
+    message: string;
+    title?: string;
+}
+export interface StopPayload extends HookPayload {
+    hook_event_name: 'Stop';
+    stop_hook_active: boolean;
+}
+export interface BaseHookResponse {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+}
+export interface PreCompactResponse extends BaseHookResponse {
+    decision?: 'approve' | 'block';
+    reason?: string;
+}
+export interface SessionStartResponse extends BaseHookResponse {
+    hookSpecificOutput?: {
+        hookEventName: 'SessionStart';
+        additionalContext?: string;
+    };
+}
+export interface PreToolUseResponse extends BaseHookResponse {
+    permissionDecision?: 'allow' | 'deny' | 'ask';
+    permissionDecisionReason?: string;
+}
+export interface CompressionResult {
+    compressedLines: string[];
+    originalTokens: number;
+    compressedTokens: number;
+    compressionRatio: number;
+    memoryNodes: string[];
+}
+export interface MemoryNode {
+    id: string;
+    type: 'document';
+    content: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class HookError extends Error {
+    hookType: string;
+    payload?: HookPayload | undefined;
+    code?: string | undefined;
+    constructor(message: string, hookType: string, payload?: HookPayload | undefined, code?: string | undefined);
+}
+export declare class CompressionError extends Error {
+    transcriptPath: string;
+    stage: 'reading' | 'analyzing' | 'compressing' | 'writing';
+    constructor(message: string, transcriptPath: string, stage: 'reading' | 'analyzing' | 'compressing' | 'writing');
+}
+export interface Logger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, error?: Error, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+export declare class FileLogger implements Logger {
+    private logFile;
+    private enableDebug;
+    constructor(logFile: string, enableDebug?: boolean);
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, error?: Error, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    private log;
+}
+export declare function validateHookPayload(payload: unknown, expectedType: string): HookPayload;
+export declare function createSuccessResponse(additionalData?: Record<string, unknown>): BaseHookResponse;
+export declare function createErrorResponse(reason: string, additionalData?: Record<string, unknown>): BaseHookResponse;
+/**
+ * Main settings interface for claude-mem configuration
+ */
+export interface Settings {
+    autoCompress?: boolean;
+    projectName?: string;
+    installed?: boolean;
+    backend?: string;
+    embedded?: boolean;
+    saveMemoriesOnClear?: boolean;
+    claudePath?: string;
+    [key: string]: unknown;
+}
+/**
+ * Document structure for MCP operations
+ */
+export interface MCPDocument {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Search result structure from MCP operations
+ */
+export interface MCPSearchResult {
+    documents?: MCPDocument[];
+    ids?: string[];
+    metadatas?: Record<string, unknown>[];
+    distances?: number[];
+    [key: string]: unknown;
+}
+/**
+ * Interface for MCP client implementations (Chroma-based)
+ */
+export interface IMCPClient {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    addDocuments(documents: MCPDocument[]): Promise<void>;
+    queryDocuments(query: string, limit?: number): Promise<MCPSearchResult>;
+    getDocuments(ids?: string[]): Promise<MCPSearchResult>;
+}

package/dist/shared/types.js

@@ -0,0 +1,78 @@
+export class HookError extends Error {
+    hookType;
+    payload;
+    code;
+    constructor(message, hookType, payload, code) {
+        super(message);
+        this.hookType = hookType;
+        this.payload = payload;
+        this.code = code;
+        this.name = 'HookError';
+    }
+}
+export class CompressionError extends Error {
+    transcriptPath;
+    stage;
+    constructor(message, transcriptPath, stage) {
+        super(message);
+        this.transcriptPath = transcriptPath;
+        this.stage = stage;
+        this.name = 'CompressionError';
+    }
+}
+export class FileLogger {
+    logFile;
+    enableDebug;
+    constructor(logFile, enableDebug = false) {
+        this.logFile = logFile;
+        this.enableDebug = enableDebug;
+    }
+    info(message, meta) {
+        this.log('INFO', message, meta);
+    }
+    warn(message, meta) {
+        this.log('WARN', message, meta);
+    }
+    error(message, error, meta) {
+        const errorMeta = error ? { error: error.message, stack: error.stack } : {};
+        this.log('ERROR', message, { ...meta, ...errorMeta });
+    }
+    debug(message, meta) {
+        if (this.enableDebug) {
+            this.log('DEBUG', message, meta);
+        }
+    }
+    log(level, message, meta) {
+        const timestamp = new Date().toISOString();
+        const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
+        const logLine = `[${timestamp}] ${level}: ${message}${metaStr}\n`;
+        console.error(logLine);
+    }
+}
+export function validateHookPayload(payload, expectedType) {
+    if (!payload || typeof payload !== 'object') {
+        throw new HookError(`Invalid payload: expected object, got ${typeof payload}`, expectedType);
+    }
+    const hookPayload = payload;
+    if (!hookPayload.session_id || typeof hookPayload.session_id !== 'string') {
+        throw new HookError('Missing or invalid session_id', expectedType, hookPayload);
+    }
+    if (!hookPayload.transcript_path ||
+        typeof hookPayload.transcript_path !== 'string') {
+        throw new HookError('Missing or invalid transcript_path', expectedType, hookPayload);
+    }
+    return hookPayload;
+}
+export function createSuccessResponse(additionalData) {
+    return {
+        continue: true,
+        ...additionalData,
+    };
+}
+export function createErrorResponse(reason, additionalData) {
+    return {
+        continue: false,
+        stopReason: reason,
+        ...additionalData,
+    };
+}