claude-mem 3.0.2 → 3.0.4

package/dist/utils/memory-mcp-client.js

@@ -0,0 +1,490 @@
+/**
+ * Memory MCP Client for claude-mem
+ *
+ * This client implements the IMCPClient interface using the traditional JSONL file-based
+ * storage system. It maintains backward compatibility with the existing claude-mem
+ * architecture while providing a clean interface for MCP operations.
+ *
+ * Key Features:
+ * - 100% backward compatibility with existing JSONL index files
+ * - Implements full IMCPClient interface
+ * - Thread-safe file operations with locking
+ * - Efficient search through in-memory indexing
+ * - Atomic writes to prevent corruption
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/**
+ * Memory MCP Client - JSONL file-based implementation
+ *
+ * This client provides the IMCPClient interface while using the existing
+ * JSONL file storage system for backward compatibility.
+ */
+export class MemoryMCPClient {
+    static instance = null;
+    isConnected = false;
+    cache = null;
+    // File paths
+    configDir = join(homedir(), '.claude-mem');
+    indexDir = join(this.configDir, 'index');
+    indexPath = join(this.indexDir, 'claude_mem_index.jsonl');
+    lockPath = join(this.indexDir, 'index.lock');
+    /**
+     * Singleton pattern - ensures only one instance manages file operations
+     */
+    static getInstance() {
+        if (!MemoryMCPClient.instance) {
+            MemoryMCPClient.instance = new MemoryMCPClient();
+        }
+        return MemoryMCPClient.instance;
+    }
+    constructor() {
+        // Public constructor but singleton pattern enforced via getInstance()
+    }
+    /**
+     * Connect to the memory backend (initialize file system)
+     */
+    async connect() {
+        if (this.isConnected) {
+            return;
+        }
+        try {
+            // Ensure directories exist
+            this.ensureDirectories();
+            // Initialize or load cache
+            await this.loadCache();
+            this.isConnected = true;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to connect to memory backend: ${errorMessage}`);
+        }
+    }
+    /**
+     * Disconnect from the memory backend (cleanup)
+     */
+    async disconnect() {
+        this.isConnected = false;
+        this.cache = null;
+        // Remove lock file if it exists
+        if (existsSync(this.lockPath)) {
+            try {
+                require('fs').unlinkSync(this.lockPath);
+            }
+            catch (error) {
+                // Ignore lock cleanup errors
+            }
+        }
+    }
+    /**
+     * Create entities in the memory backend
+     */
+    async createEntities(entities) {
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        await this.withFileLock(async () => {
+            // Create a new index entry for this batch of entities
+            const entry = {
+                id: this.generateId(),
+                timestamp: new Date().toISOString(),
+                project: this.extractProjectFromEntities(entities),
+                session: this.generateSessionId(),
+                summary: this.generateSummaryFromEntities(entities),
+                nodes: entities.map(e => e.name),
+                keywords: this.extractKeywords(entities),
+                relations: [],
+                entities: entities.map(e => ({
+                    name: e.name,
+                    type: e.entityType,
+                    observations: e.observations
+                }))
+            };
+            // Append to JSONL file
+            this.appendToIndex(entry);
+            // Update cache
+            entities.forEach(entity => {
+                this.cache.entities.set(entity.name, entity);
+            });
+        });
+    }
+    /**
+     * Create relations in the memory backend
+     */
+    async createRelations(relations) {
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        await this.withFileLock(async () => {
+            // Create a new index entry for this batch of relations
+            const entry = {
+                id: this.generateId(),
+                timestamp: new Date().toISOString(),
+                project: this.extractProjectFromRelations(relations),
+                session: this.generateSessionId(),
+                summary: this.generateSummaryFromRelations(relations),
+                nodes: this.getUniqueNodesFromRelations(relations),
+                keywords: this.extractKeywordsFromRelations(relations),
+                relations: relations.map(r => ({
+                    from: r.from,
+                    to: r.to,
+                    type: r.relationType
+                })),
+                entities: []
+            };
+            // Append to JSONL file
+            this.appendToIndex(entry);
+            // Update cache
+            relations.forEach(relation => {
+                const key = `${relation.from}->${relation.to}:${relation.relationType}`;
+                this.cache.relations.set(key, relation);
+            });
+        });
+    }
+    /**
+     * Search nodes using text-based matching
+     */
+    async searchNodes(query) {
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        await this.ensureCacheLoaded();
+        const results = {
+            entities: [],
+            relations: []
+        };
+        const queryLower = query.toLowerCase();
+        const isEntityTypeQuery = /^[A-Z][a-z]+_/.test(query);
+        // Search entities
+        for (const [name, entity] of this.cache.entities) {
+            if (this.matchesEntity(entity, queryLower, isEntityTypeQuery)) {
+                results.entities.push({
+                    name: entity.name,
+                    entityType: entity.entityType,
+                    observations: entity.observations
+                });
+            }
+        }
+        // Search relations (unless it's a specific entity type search)
+        if (!isEntityTypeQuery) {
+            for (const [key, relation] of this.cache.relations) {
+                if (this.matchesRelation(relation, queryLower)) {
+                    results.relations.push({
+                        from: relation.from,
+                        to: relation.to,
+                        relationType: relation.relationType
+                    });
+                }
+            }
+        }
+        // Sort results by relevance (exact matches first)
+        results.entities = results.entities.sort((a, b) => {
+            const aExact = a.name.toLowerCase().includes(queryLower) ? 0 : 1;
+            const bExact = b.name.toLowerCase().includes(queryLower) ? 0 : 1;
+            return aExact - bExact;
+        });
+        return results;
+    }
+    /**
+     * Open specific nodes by exact name matching
+     */
+    async openNodes(names) {
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        await this.ensureCacheLoaded();
+        const results = {
+            entities: [],
+            relations: []
+        };
+        // Find exact entity matches
+        for (const name of names) {
+            const entity = this.cache.entities.get(name);
+            if (entity) {
+                results.entities.push({
+                    name: entity.name,
+                    entityType: entity.entityType,
+                    observations: entity.observations
+                });
+            }
+            // Find relations involving this entity
+            for (const [key, relation] of this.cache.relations) {
+                if (relation.from === name || relation.to === name) {
+                    results.relations.push({
+                        from: relation.from,
+                        to: relation.to,
+                        relationType: relation.relationType
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    // =============================================================================
+    // PRIVATE HELPER METHODS
+    // =============================================================================
+    /**
+     * Ensure required directories exist
+     */
+    ensureDirectories() {
+        if (!existsSync(this.configDir)) {
+            mkdirSync(this.configDir, { recursive: true });
+        }
+        if (!existsSync(this.indexDir)) {
+            mkdirSync(this.indexDir, { recursive: true });
+        }
+    }
+    /**
+     * Load cache from JSONL files
+     */
+    async loadCache() {
+        this.cache = {
+            entities: new Map(),
+            relations: new Map(),
+            lastModified: 0
+        };
+        if (!existsSync(this.indexPath)) {
+            return; // No index file yet
+        }
+        try {
+            const content = readFileSync(this.indexPath, 'utf-8');
+            const lines = content.trim().split('\n').filter(line => line.trim());
+            for (const line of lines) {
+                try {
+                    const entry = JSON.parse(line);
+                    // Load entities
+                    entry.entities?.forEach(entity => {
+                        this.cache.entities.set(entity.name, {
+                            name: entity.name,
+                            entityType: entity.type,
+                            observations: entity.observations
+                        });
+                    });
+                    // Load relations
+                    entry.relations?.forEach(relation => {
+                        const key = `${relation.from}->${relation.to}:${relation.type}`;
+                        this.cache.relations.set(key, {
+                            from: relation.from,
+                            to: relation.to,
+                            relationType: relation.type
+                        });
+                    });
+                }
+                catch (error) {
+                    // Skip malformed lines
+                    console.warn(`Skipping malformed index line: ${line}`);
+                }
+            }
+            // Update last modified time
+            const stats = require('fs').statSync(this.indexPath);
+            this.cache.lastModified = stats.mtime.getTime();
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            console.warn(`Failed to load memory cache: ${errorMessage}`);
+        }
+    }
+    /**
+     * Ensure cache is loaded and up to date
+     */
+    async ensureCacheLoaded() {
+        if (!this.cache) {
+            await this.loadCache();
+            return;
+        }
+        // Check if index file has been modified
+        if (existsSync(this.indexPath)) {
+            const stats = require('fs').statSync(this.indexPath);
+            if (stats.mtime.getTime() > this.cache.lastModified) {
+                await this.loadCache();
+            }
+        }
+    }
+    /**
+     * Execute operation with file locking
+     */
+    async withFileLock(operation) {
+        const maxRetries = 5;
+        const retryDelay = 100;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                // Check for existing lock
+                if (existsSync(this.lockPath)) {
+                    if (attempt === maxRetries) {
+                        throw new Error('File is locked by another process');
+                    }
+                    await this.sleep(retryDelay * attempt);
+                    continue;
+                }
+                // Create lock
+                writeFileSync(this.lockPath, process.pid.toString());
+                try {
+                    return await operation();
+                }
+                finally {
+                    // Remove lock
+                    if (existsSync(this.lockPath)) {
+                        require('fs').unlinkSync(this.lockPath);
+                    }
+                }
+            }
+            catch (error) {
+                if (attempt === maxRetries) {
+                    throw error;
+                }
+                await this.sleep(retryDelay * attempt);
+            }
+        }
+        throw new Error('Failed to acquire file lock');
+    }
+    /**
+     * Append entry to JSONL index file
+     */
+    appendToIndex(entry) {
+        const line = JSON.stringify(entry) + '\n';
+        if (existsSync(this.indexPath)) {
+            require('fs').appendFileSync(this.indexPath, line, 'utf-8');
+        }
+        else {
+            writeFileSync(this.indexPath, line, 'utf-8');
+        }
+    }
+    /**
+     * Check if entity matches search query
+     */
+    matchesEntity(entity, queryLower, isEntityTypeQuery) {
+        if (isEntityTypeQuery) {
+            // For entity type queries like "Component_", match the entityType
+            const type = queryLower.replace('_', '').toLowerCase();
+            return entity.entityType.toLowerCase() === type;
+        }
+        // General text search
+        const searchableText = [
+            entity.name,
+            entity.entityType,
+            ...entity.observations
+        ].join(' ').toLowerCase();
+        return searchableText.includes(queryLower);
+    }
+    /**
+     * Check if relation matches search query
+     */
+    matchesRelation(relation, queryLower) {
+        const searchableText = [
+            relation.from,
+            relation.to,
+            relation.relationType
+        ].join(' ').toLowerCase();
+        return searchableText.includes(queryLower);
+    }
+    /**
+     * Generate unique ID for index entries
+     */
+    generateId() {
+        return `mem_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Generate session ID (simplified)
+     */
+    generateSessionId() {
+        return `session_${Date.now()}`;
+    }
+    /**
+     * Extract project name from entities
+     */
+    extractProjectFromEntities(entities) {
+        if (entities.length === 0)
+            return 'unknown';
+        // Extract project from entity name format: project_entityType_name
+        const parts = entities[0].name.split('_');
+        return parts.length > 0 ? parts[0] : 'unknown';
+    }
+    /**
+     * Extract project name from relations
+     */
+    extractProjectFromRelations(relations) {
+        if (relations.length === 0)
+            return 'unknown';
+        const parts = relations[0].from.split('_');
+        return parts.length > 0 ? parts[0] : 'unknown';
+    }
+    /**
+     * Generate summary from entities
+     */
+    generateSummaryFromEntities(entities) {
+        if (entities.length === 1) {
+            return `Created ${entities[0].entityType}: ${entities[0].name.split('_').pop()}`;
+        }
+        return `Created ${entities.length} ${entities[0].entityType} entities`;
+    }
+    /**
+     * Generate summary from relations
+     */
+    generateSummaryFromRelations(relations) {
+        if (relations.length === 1) {
+            const rel = relations[0];
+            const fromName = rel.from.split('_').pop();
+            const toName = rel.to.split('_').pop();
+            return `${fromName} ${rel.relationType} ${toName}`;
+        }
+        return `Created ${relations.length} relations`;
+    }
+    /**
+     * Extract keywords from entities
+     */
+    extractKeywords(entities) {
+        const keywords = new Set();
+        entities.forEach(entity => {
+            keywords.add(entity.entityType);
+            keywords.add(entity.name.split('_').pop() || entity.name);
+            entity.observations.forEach(obs => {
+                // Extract key terms from observations
+                const words = obs.split(/\s+/)
+                    .filter(word => word.length > 3)
+                    .slice(0, 3); // Limit to first 3 significant words
+                words.forEach(word => keywords.add(word.toLowerCase()));
+            });
+        });
+        return Array.from(keywords).slice(0, 10); // Limit total keywords
+    }
+    /**
+     * Extract keywords from relations
+     */
+    extractKeywordsFromRelations(relations) {
+        const keywords = new Set();
+        relations.forEach(relation => {
+            keywords.add(relation.relationType);
+            keywords.add(relation.from.split('_').pop() || relation.from);
+            keywords.add(relation.to.split('_').pop() || relation.to);
+        });
+        return Array.from(keywords);
+    }
+    /**
+     * Get unique nodes from relations
+     */
+    getUniqueNodesFromRelations(relations) {
+        const nodes = new Set();
+        relations.forEach(relation => {
+            nodes.add(relation.from);
+            nodes.add(relation.to);
+        });
+        return Array.from(nodes);
+    }
+    /**
+     * Utility method for async delays
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Factory function to create MemoryMCPClient instance
+ */
+export function createMemoryMCPClient() {
+    return MemoryMCPClient.getInstance();
+}
+/**
+ * Default export for convenience
+ */
+export default MemoryMCPClient;

package/dist/utils/weaviate-mcp-adapter.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Embedded Weaviate Adapter for claude-mem
+ *
+ * This adapter provides a direct interface to embedded Weaviate using weaviate-ts-embedded,
+ * eliminating external dependencies and simplifying deployment.
+ *
+ * Key Features:
+ * - 100% backward compatibility with existing MCPClient interface
+ * - Embedded Weaviate instance (no external server required)
+ * - Maps entities to Weaviate objects with searchable text generation
+ * - Maps relations to separate Weaviate collection
+ * - Hybrid search (semantic + keyword) for better search quality
+ * - Automatic instance management (start/stop)
+ * - Retry logic with exponential backoff
+ */
+import { IMCPClient, MCPEntity, MCPRelation, MCPSearchResult } from '../types.js';
+/**
+ * Interface matching the existing MCPClient for 100% compatibility
+ */
+export interface IWeaviateMCPAdapter extends IMCPClient {
+}
+/**
+ * WeaviateMCPAdapter - Direct interface to embedded Weaviate
+ *
+ * This adapter maintains 100% API compatibility with the existing MCPClient
+ * while providing superior search capabilities through embedded Weaviate's hybrid search.
+ */
+export declare class WeaviateMCPAdapter implements IMCPClient {
+    private isConnected;
+    private client;
+    private maxRetries;
+    private retryDelay;
+    constructor();
+    /**
+     * Connect to embedded Weaviate
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from embedded Weaviate
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Create entities in Weaviate using the weaviate-insert-one tool
+     */
+    createEntities(entities: MCPEntity[]): Promise<void>;
+    /**
+     * Create relations in Weaviate using the weaviate-insert-one tool
+     */
+    createRelations(relations: MCPRelation[]): Promise<void>;
+    /**
+     * Search nodes using Weaviate's hybrid search capabilities
+     *
+     * This method detects entity type prefix searches (e.g., "Component_") and
+     * uses appropriate search strategies for optimal results.
+     */
+    searchNodes(query: string): Promise<MCPSearchResult>;
+    /**
+     * Open specific nodes by exact name matching
+     */
+    openNodes(names: string[]): Promise<MCPSearchResult>;
+    /**
+     * Ensure required Weaviate collections exist
+     */
+    private ensureCollections;
+    /**
+     * Generate searchable text for an entity to improve hybrid search
+     */
+    private generateEntitySearchText;
+    /**
+     * Generate searchable text for a relation to improve hybrid search
+     */
+    private generateRelationSearchText;
+    /**
+     * Enhance query based on search type for better results
+     */
+    private enhanceQuery;
+    /**
+     * Format Weaviate results to match the memory MCP structure
+     */
+    private formatSearchResults;
+    /**
+     * Call a Weaviate MCP tool with error handling and retries
+     */
+    private callTool;
+    /**
+     * Execute actual Weaviate operations using the embedded client
+     */
+    private executeWeaviateOperation;
+    /**
+     * Utility method for async delays
+     */
+    private sleep;
+}
+/**
+ * Factory function to create WeaviateMCPAdapter instance
+ * Provides clean interface for creating embedded Weaviate adapters
+ */
+export declare function createWeaviateMCPAdapter(): IMCPClient;
+/**
+ * Default export for convenience
+ */
+export default WeaviateMCPAdapter;