claude-mem 3.0.2 → 3.0.4

package/dist/mcp-server-cli.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * 🔒 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+ *
+ * OFFICIAL DOCS: @modelcontextprotocol/sdk v1.0.0
+ * Last Verified: 2025-09-01
+ *
+ * Claude-mem MCP Server CLI Entry Point
+ *
+ * This module provides the standalone entry point for running the claude-mem MCP server
+ * that communicates with Claude Code via stdio transport.
+ *
+ * Usage:
+ *   node dist/mcp-server-cli.js
+ *   claude-mem-server
+ *
+ * Communication:
+ * - Stdin/Stdout: MCP protocol messages with Claude Code
+ * - Stderr: Logging and diagnostic output
+ *
+ * Architecture:
+ * This CLI connects the MCP server to Claude Code via stdio transport,
+ * enabling Claude Code to access the embedded Weaviate knowledge graph
+ * through standard MCP memory tools.
+ *
+ * Implementation follows official MCP SDK patterns:
+ * - StdioServerTransport for stdin/stdout communication (SDK README.md#_snippet_16)
+ * - Server initialization before transport connection
+ * - Graceful shutdown handlers for SIGINT/SIGTERM
+ * - Error handling for uncaught exceptions
+ *
+ * @see docs/mcp-sdk/stdio-transport.md for transport patterns
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { server, initializeServer, shutdownServer } from './mcp-server.js';
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+/**
+ * Main function to start the MCP server with stdio transport
+ *
+ * OFFICIAL PATTERN: Stdio transport connection
+ * Source: @modelcontextprotocol/sdk README.md#_snippet_16, #_snippet_25
+ *
+ * Connection sequence:
+ * 1. Initialize backend services (Weaviate adapter)
+ * 2. Create StdioServerTransport instance
+ * 3. Connect server to transport with await server.connect(transport)
+ * 4. Set up shutdown handlers for graceful termination
+ *
+ * Best Practices:
+ * - Initialize backends before transport connection
+ * - Use console.error for status messages (stderr)
+ * - Exit with code 1 on startup failures
+ */
+async function main() {
+    try {
+        // Initialize the server and embedded Weaviate adapter
+        await initializeServer();
+        // PATTERN: StdioServerTransport for CLI-based MCP servers
+        // Source: SDK README.md#_snippet_1, #_snippet_16
+        // This transport handles stdin/stdout communication automatically
+        const transport = new StdioServerTransport();
+        // PATTERN: Connect server to transport
+        // This starts the message handling loop
+        await server.connect(transport);
+        console.error('Claude-mem MCP server started on stdio');
+        console.error('Ready to receive MCP requests from Claude Code');
+        // Set up graceful shutdown handlers
+        setupShutdownHandlers();
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error('Failed to start claude-mem MCP server:', errorMessage);
+        process.exit(1);
+    }
+}
+// =============================================================================
+// SHUTDOWN HANDLING
+// =============================================================================
+/**
+ * Set up handlers for graceful shutdown on various signals
+ *
+ * PATTERN: Graceful shutdown for stdio servers
+ * Source: Common Node.js pattern for CLI tools
+ *
+ * Signal handling:
+ * - SIGINT: Ctrl+C from terminal
+ * - SIGTERM: Standard termination signal
+ * - SIGHUP: Terminal hangup
+ *
+ * Error handling:
+ * - uncaughtException: Catch sync errors
+ * - unhandledRejection: Catch async promise rejections
+ *
+ * Best Practices:
+ * - Always clean up resources before exit
+ * - Exit with code 0 for graceful shutdown
+ * - Exit with code 1 for error conditions
+ * - Log shutdown reasons to stderr
+ */
+function setupShutdownHandlers() {
+    const handleShutdown = async (signal) => {
+        console.error(`\nReceived ${signal}, shutting down gracefully...`);
+        try {
+            await shutdownServer();
+            process.exit(0);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`Error during shutdown: ${errorMessage}`);
+            process.exit(1);
+        }
+    };
+    // PATTERN: Handle standard termination signals
+    process.on('SIGINT', () => handleShutdown('SIGINT')); // Ctrl+C
+    process.on('SIGTERM', () => handleShutdown('SIGTERM')); // Kill command
+    process.on('SIGHUP', () => handleShutdown('SIGHUP')); // Terminal closed
+    // PATTERN: Handle unexpected errors gracefully
+    process.on('uncaughtException', async (error) => {
+        console.error('Uncaught exception:', error);
+        await shutdownServer();
+        process.exit(1);
+    });
+    process.on('unhandledRejection', async (reason) => {
+        console.error('Unhandled rejection:', reason);
+        await shutdownServer();
+        process.exit(1);
+    });
+}
+// =============================================================================
+// STARTUP
+// =============================================================================
+/**
+ * PATTERN: ES Module entry point detection
+ * Source: Node.js ES modules best practice
+ *
+ * In ES modules, we need to:
+ * 1. Convert import.meta.url to file path
+ * 2. Check if current file is the entry point
+ * 3. Handle both TypeScript (.ts) and compiled (.js) extensions
+ *
+ * This ensures the server only starts when run directly,
+ * not when imported as a module.
+ */
+// Run the main function if this file is executed directly
+// In ES modules, we check if process.argv[1] ends with our filename
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Check if this script is being run directly
+if (process.argv[1] === __filename || process.argv[1].endsWith('mcp-server-cli.js')) {
+    main().catch((error) => {
+        console.error('Startup error:', error);
+        process.exit(1);
+    });
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 🔒 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+ *
+ * OFFICIAL DOCS: @modelcontextprotocol/sdk v1.0.0
+ * Last Verified: 2025-09-01
+ *
+ * Claude-mem MCP Server Core Implementation
+ *
+ * This module provides the standalone MCP server that wraps the WeaviateMCPAdapter
+ * and exposes it via the Model Context Protocol for Claude Code integration.
+ *
+ * Key Features:
+ * - Implements MCP server using @modelcontextprotocol/sdk/server
+ * - Exposes standard MCP memory tools: create_entities, create_relations, search_nodes, etc.
+ * - Uses WeaviateMCPAdapter as backend storage engine (embedded Weaviate)
+ * - Handles stdio communication with Claude Code
+ * - Comprehensive error handling and logging
+ * - Zero external dependencies beyond embedded Weaviate
+ *
+ * Architecture:
+ * Claude Code ←→ MCP Server (stdio) ←→ WeaviateMCPAdapter ←→ Embedded Weaviate
+ *
+ * Implementation follows official MCP SDK patterns:
+ * - Low-level Server class for direct request handling (see SDK README.md#_snippet_25)
+ * - setRequestHandler with CallToolRequestSchema for tool routing
+ * - Proper error handling with isError flag in responses
+ * - Console.error for logging (stderr for debugging, stdout for protocol)
+ *
+ * @see docs/mcp-sdk/server-implementation.md for detailed patterns
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { WeaviateMCPAdapter } from './utils/weaviate-mcp-adapter.js';
+/**
+ * Create and configure the MCP server instance
+ *
+ * OFFICIAL PATTERN: Low-level Server implementation
+ * Source: @modelcontextprotocol/sdk README.md#_snippet_25
+ *
+ * Using the low-level Server class (not McpServer) provides:
+ * - Direct control over request handling via setRequestHandler
+ * - Custom tool routing logic with CallToolRequestSchema
+ * - Fine-grained error handling per tool
+ *
+ * Server constructor params:
+ * - First param: Server metadata (name, version)
+ * - Second param: Server options with capabilities declaration
+ *   - capabilities.tools: {} indicates this server provides tools
+ */
+declare const server: Server<{
+    method: string;
+    params?: import("zod").objectOutputType<{
+        _meta: import("zod").ZodOptional<import("zod").ZodObject<{
+            progressToken: import("zod").ZodOptional<import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>>;
+        }, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{
+            progressToken: import("zod").ZodOptional<import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>>;
+        }, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{
+            progressToken: import("zod").ZodOptional<import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>>;
+        }, import("zod").ZodTypeAny, "passthrough">>>;
+    }, import("zod").ZodTypeAny, "passthrough"> | undefined;
+}, {
+    method: string;
+    params?: import("zod").objectOutputType<{
+        _meta: import("zod").ZodOptional<import("zod").ZodObject<{}, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{}, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{}, import("zod").ZodTypeAny, "passthrough">>>;
+    }, import("zod").ZodTypeAny, "passthrough"> | undefined;
+}, import("zod").objectOutputType<{
+    _meta: import("zod").ZodOptional<import("zod").ZodObject<{}, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{}, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{}, import("zod").ZodTypeAny, "passthrough">>>;
+}, import("zod").ZodTypeAny, "passthrough">>;
+/**
+ * Create the Weaviate adapter instance
+ */
+declare const adapter: WeaviateMCPAdapter;
+/**
+ * Initialize the server and adapter connections
+ *
+ * PATTERN: Server initialization separate from transport connection
+ * Source: SDK patterns show initialization logic before transport.connect()
+ *
+ * Best Practices:
+ * - Initialize backend connections before server.connect(transport)
+ * - Use console.error for status messages (won't interfere with stdio)
+ * - Throw errors to prevent server startup if initialization fails
+ */
+declare function initializeServer(): Promise<void>;
+/**
+ * Gracefully shutdown the server and adapter connections
+ *
+ * PATTERN: Graceful shutdown handling
+ * Source: SDK examples show cleanup in shutdown handlers
+ *
+ * Best Practices:
+ * - Clean up backend connections when server shuts down
+ * - Log but don't throw errors during shutdown (best effort)
+ * - Use console.error for shutdown messages
+ */
+declare function shutdownServer(): Promise<void>;
+/**
+ * Export server and adapter for use by the CLI entry point
+ */
+export { server, adapter, initializeServer, shutdownServer };
+/**
+ * Default export provides the configured server instance
+ */
+export default server;

package/dist/mcp-server.js

@@ -0,0 +1,269 @@
+/**
+ * 🔒 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+ *
+ * OFFICIAL DOCS: @modelcontextprotocol/sdk v1.0.0
+ * Last Verified: 2025-09-01
+ *
+ * Claude-mem MCP Server Core Implementation
+ *
+ * This module provides the standalone MCP server that wraps the WeaviateMCPAdapter
+ * and exposes it via the Model Context Protocol for Claude Code integration.
+ *
+ * Key Features:
+ * - Implements MCP server using @modelcontextprotocol/sdk/server
+ * - Exposes standard MCP memory tools: create_entities, create_relations, search_nodes, etc.
+ * - Uses WeaviateMCPAdapter as backend storage engine (embedded Weaviate)
+ * - Handles stdio communication with Claude Code
+ * - Comprehensive error handling and logging
+ * - Zero external dependencies beyond embedded Weaviate
+ *
+ * Architecture:
+ * Claude Code ←→ MCP Server (stdio) ←→ WeaviateMCPAdapter ←→ Embedded Weaviate
+ *
+ * Implementation follows official MCP SDK patterns:
+ * - Low-level Server class for direct request handling (see SDK README.md#_snippet_25)
+ * - setRequestHandler with CallToolRequestSchema for tool routing
+ * - Proper error handling with isError flag in responses
+ * - Console.error for logging (stderr for debugging, stdout for protocol)
+ *
+ * @see docs/mcp-sdk/server-implementation.md for detailed patterns
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { WeaviateMCPAdapter } from './utils/weaviate-mcp-adapter.js';
+import { WEAVIATE_MESSAGES } from './constants.js';
+// =============================================================================
+// MCP SERVER CONFIGURATION
+// =============================================================================
+/**
+ * Create and configure the MCP server instance
+ *
+ * OFFICIAL PATTERN: Low-level Server implementation
+ * Source: @modelcontextprotocol/sdk README.md#_snippet_25
+ *
+ * Using the low-level Server class (not McpServer) provides:
+ * - Direct control over request handling via setRequestHandler
+ * - Custom tool routing logic with CallToolRequestSchema
+ * - Fine-grained error handling per tool
+ *
+ * Server constructor params:
+ * - First param: Server metadata (name, version)
+ * - Second param: Server options with capabilities declaration
+ *   - capabilities.tools: {} indicates this server provides tools
+ */
+const server = new Server({
+    name: 'claude-mem',
+    version: '3.0.1',
+}, {
+    capabilities: {
+        tools: {}
+    }
+});
+/**
+ * Create the Weaviate adapter instance
+ */
+const adapter = new WeaviateMCPAdapter();
+// =============================================================================
+// MCP TOOL HANDLERS
+// =============================================================================
+/**
+ * Register the main tool handler that routes requests to appropriate adapter methods
+ *
+ * OFFICIAL PATTERN: Tool request handling with CallToolRequestSchema
+ * Source: @modelcontextprotocol/sdk types.js - CallToolRequestSchema
+ *
+ * Best Practices:
+ * - Single setRequestHandler for CallToolRequestSchema handles all tools
+ * - Switch statement routes to specific tool implementations
+ * - Each tool validates its arguments before processing
+ * - Return format: { content: [{ type: 'text', text: string }] }
+ * - Error format: { content: [...], isError: true } for tool errors
+ *
+ * The request parameter contains:
+ * - params.name: The tool name being called
+ * - params.arguments: The tool arguments as a JSON object
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        // Ensure adapter connection before any operation
+        await adapter.connect();
+        // Validate that args is defined
+        if (!args) {
+            throw new Error(`No arguments provided for tool: ${name}`);
+        }
+        switch (name) {
+            case 'create_entities': {
+                // PATTERN: Tool argument validation before processing
+                // Always validate required parameters exist and have correct type
+                if (!args.entities || !Array.isArray(args.entities)) {
+                    throw new Error('create_entities requires an entities array parameter');
+                }
+                const entities = args.entities;
+                await adapter.createEntities(entities);
+                // PATTERN: Standard MCP tool response format
+                // Source: SDK examples show content array with type/text objects
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Successfully created ${entities.length} entities in embedded Weaviate`
+                        }]
+                };
+            }
+            case 'create_relations': {
+                if (!args.relations || !Array.isArray(args.relations)) {
+                    throw new Error('create_relations requires a relations array parameter');
+                }
+                const relations = args.relations;
+                await adapter.createRelations(relations);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Successfully created ${relations.length} relations in embedded Weaviate`
+                        }]
+                };
+            }
+            case 'search_nodes': {
+                if (!args.query || typeof args.query !== 'string') {
+                    throw new Error('search_nodes requires a query string parameter');
+                }
+                const searchResults = await adapter.searchNodes(args.query);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(searchResults, null, 2)
+                        }]
+                };
+            }
+            case 'open_nodes': {
+                if (!args.names || !Array.isArray(args.names)) {
+                    throw new Error('open_nodes requires a names array parameter');
+                }
+                const nodes = await adapter.openNodes(args.names);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(nodes, null, 2)
+                        }]
+                };
+            }
+            case 'delete_entities': {
+                if (!args.entityNames || !Array.isArray(args.entityNames)) {
+                    throw new Error('delete_entities requires an entityNames array parameter');
+                }
+                // Note: WeaviateMCPAdapter doesn't implement deleteEntities yet
+                // This is a placeholder for future implementation
+                throw new Error('delete_entities is not yet implemented in the embedded Weaviate adapter');
+            }
+            case 'delete_relations': {
+                if (!args.relations || !Array.isArray(args.relations)) {
+                    throw new Error('delete_relations requires a relations array parameter');
+                }
+                // Note: WeaviateMCPAdapter doesn't implement deleteRelations yet
+                // This is a placeholder for future implementation
+                throw new Error('delete_relations is not yet implemented in the embedded Weaviate adapter');
+            }
+            case 'add_observations': {
+                if (!args.observations || !Array.isArray(args.observations)) {
+                    throw new Error('add_observations requires an observations array parameter');
+                }
+                // Note: WeaviateMCPAdapter doesn't implement addObservations yet
+                // This is a placeholder for future implementation
+                throw new Error('add_observations is not yet implemented in the embedded Weaviate adapter');
+            }
+            case 'delete_observations': {
+                if (!args.deletions || !Array.isArray(args.deletions)) {
+                    throw new Error('delete_observations requires a deletions array parameter');
+                }
+                // Note: WeaviateMCPAdapter doesn't implement deleteObservations yet
+                // This is a placeholder for future implementation
+                throw new Error('delete_observations is not yet implemented in the embedded Weaviate adapter');
+            }
+            case 'read_graph': {
+                // Note: WeaviateMCPAdapter doesn't implement readGraph yet
+                // This is a placeholder for future implementation
+                throw new Error('read_graph is not yet implemented in the embedded Weaviate adapter');
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // PATTERN: Error logging to stderr
+        // Source: MCP SDK convention - stderr for logs, stdout for protocol
+        // This allows debugging without interfering with stdio transport
+        console.error(`[MCP Server Error] Tool: ${name}, Error: ${errorMessage}`);
+        // PATTERN: Error response format with isError flag
+        // Source: SDK README.md#_snippet_22 (SQLite example shows isError usage)
+        // The isError flag indicates to clients that the tool execution failed
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Error: ${errorMessage}`
+                }],
+            isError: true
+        };
+    }
+});
+// =============================================================================
+// SERVER LIFECYCLE MANAGEMENT
+// =============================================================================
+/**
+ * Initialize the server and adapter connections
+ *
+ * PATTERN: Server initialization separate from transport connection
+ * Source: SDK patterns show initialization logic before transport.connect()
+ *
+ * Best Practices:
+ * - Initialize backend connections before server.connect(transport)
+ * - Use console.error for status messages (won't interfere with stdio)
+ * - Throw errors to prevent server startup if initialization fails
+ */
+async function initializeServer() {
+    try {
+        // Connect to embedded Weaviate before accepting MCP requests
+        console.error(WEAVIATE_MESSAGES.SETUP.STARTING_EMBEDDED);
+        await adapter.connect();
+        console.error(WEAVIATE_MESSAGES.SETUP.EMBEDDED_READY);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to initialize embedded Weaviate: ${errorMessage}`);
+        throw error; // Propagate to prevent server startup
+    }
+}
+/**
+ * Gracefully shutdown the server and adapter connections
+ *
+ * PATTERN: Graceful shutdown handling
+ * Source: SDK examples show cleanup in shutdown handlers
+ *
+ * Best Practices:
+ * - Clean up backend connections when server shuts down
+ * - Log but don't throw errors during shutdown (best effort)
+ * - Use console.error for shutdown messages
+ */
+async function shutdownServer() {
+    try {
+        console.error('Shutting down claude-mem MCP server...');
+        await adapter.disconnect();
+        console.error(WEAVIATE_MESSAGES.CONNECTION.DISCONNECTED);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`Error during shutdown: ${errorMessage}`);
+        // Don't throw - best effort shutdown
+    }
+}
+// =============================================================================
+// EXPORTS
+// =============================================================================
+/**
+ * Export server and adapter for use by the CLI entry point
+ */
+export { server, adapter, initializeServer, shutdownServer };
+/**
+ * Default export provides the configured server instance
+ */
+export default server;

package/dist/types.d.ts

@@ -0,0 +1,148 @@
+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: 'entity' | 'relation';
+    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;
+    [key: string]: unknown;
+}
+/**
+ * Entity structure for MCP operations
+ */
+export interface MCPEntity {
+    name: string;
+    entityType: string;
+    observations: string[];
+}
+/**
+ * Relation structure for MCP operations
+ */
+export interface MCPRelation {
+    from: string;
+    to: string;
+    relationType: string;
+}
+/**
+ * Search result structure from MCP operations
+ */
+export interface MCPSearchResult {
+    entities?: MCPEntity[];
+    relations?: MCPRelation[];
+    [key: string]: unknown;
+}
+/**
+ * Interface for MCP client implementations (memory and Weaviate)
+ */
+export interface IMCPClient {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    createEntities(entities: MCPEntity[]): Promise<void>;
+    createRelations(relations: MCPRelation[]): Promise<void>;
+    searchNodes(query: string): Promise<MCPSearchResult>;
+    openNodes(names: string[]): Promise<MCPSearchResult>;
+}