rag-memory-epf-mcp 1.7.0 → 1.9.0

package/README.md

@@ -5,7 +5,9 @@
 [![GitHub license](https://img.shields.io/github/license/heesongkoh/rag-memory-epf-mcp)](https://github.com/heesongkoh/rag-memory-epf-mcp/blob/main/LICENSE)
 [![Platforms](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)](https://github.com/heesongkoh/rag-memory-epf-mcp)
 
-An advanced MCP server for **RAG-enabled memory** through a knowledge graph with **multilingual vector search** capabilities.
+An advanced MCP server for **project-local RAG memory** through a knowledge graph with **multilingual vector search** capabilities.
+
+**Each project folder gets its own isolated memory database** — set `DB_FILE_PATH` to a project-local `.memory/rag-memory.db` so every project maintains its own entities, relations, and documents independently. Multiple projects can run simultaneously without interference since they read/write to separate SQLite databases while sharing the same server binary.
 
 **Fork of:** [rag-memory-mcp](https://github.com/ttommyth/rag-memory-mcp) — upgraded with **Qwen3-Embedding-0.6B** (1024-dim, 100+ languages) for significantly better multilingual semantic search.
 
@@ -34,7 +36,7 @@ An advanced MCP server for **RAG-enabled memory** through a knowledge graph with
 }
 ```
 
-**With custom database path:**
+**Project-local memory (recommended):**
 ```json
 {
   "mcpServers": {
@@ -42,13 +44,15 @@ An advanced MCP server for **RAG-enabled memory** through a knowledge graph with
       "command": "npx",
       "args": ["-y", "rag-memory-epf-mcp@latest"],
       "env": {
-        "DB_FILE_PATH": "/path/to/your/rag-memory.db"
+        "DB_FILE_PATH": "/path/to/your-project/.memory/rag-memory.db"
       }
     }
   }
 }
 ```
 
+Place this `.mcp.json` in each project folder with its own `DB_FILE_PATH`. Each project maintains completely isolated memory — entities, relations, and documents are never mixed between projects.
+
 ## Document Processing Pipeline
 
 `embedChunks` automatically links entities to the specific chunks where they appear:
@@ -110,19 +114,22 @@ Your entities, relationships, documents, and chunk text are preserved. Only vect
 - `createEntities`: Create entities with observations and types
 - `createRelations`: Establish relationships between entities
 - `addObservations`: Add contextual information to entities
+- `updateRelations`: Update relationship confidence and metadata
 - `deleteEntities`: Remove entities and relationships
 - `deleteRelations`: Remove specific relationships
 - `deleteObservations`: Remove specific observations
-- `embedAllEntities`: Generate embeddings for all entities
+- `embedAllEntities`: Generate embeddings for all entities (batch 32 parallel)
 
 ### Search & Retrieval
-- `hybridSearch`: Vector similarity + graph traversal
-- `searchNodes`: Semantic entity search (multilingual)
+- `hybridSearch`: Vector + FTS5 BM25 + graph traversal (3-signal hybrid)
+- `searchNodes`: Semantic entity search (multilingual, with since/until temporal filtering)
 - `openNodes`: Retrieve specific entities
 - `readGraph`: Get complete knowledge graph
 - `getDetailedContext`: Get full context for a chunk
 
-### Analytics & Migration
+### Backup & Migration
+- `exportGraph`: Export full knowledge graph as JSON (entities, relations, documents)
+- `importGraph`: Import knowledge graph from JSON (merge or replace mode)
 - `getKnowledgeGraphStats`: Knowledge base statistics
 - `getMigrationStatus`: Check database schema version
 - `runMigrations`: Apply pending migrations
@@ -130,6 +137,19 @@ Your entities, relationships, documents, and chunk text are preserved. Only vect
 
 ## Changelog
 
+### v1.7.0
+
+- **SQLite optimization** — WAL mode, 32MB cache, 256MB mmap, busy_timeout for concurrent access
+- **FTS5 full-text search** — keyword-exact matching via BM25, combined with vector search using Reciprocal Rank Fusion (RRF, k=60)
+- **updateRelations** — update relationship confidence scores and metadata without delete+recreate
+- **exportGraph / importGraph** — JSON backup and restore with merge or replace mode
+- **Batch embedding** — `embedAllEntities` processes 32 entities in parallel instead of sequential
+- **Temporal filtering** — `searchNodes` supports `since` and `until` (ISO 8601) date filters
+- **better-sqlite3 12.x** — SQLite 3.51.3 with query planner improvements
+- **sqlite-vec 0.1.7** — DELETE space reclaim, KNN distance constraints
+- **Missing indexes** — entityType, relationType, chunk lookups for faster queries
+- **SQL safety** — `safeRowid()` validation for vec0 virtual table operations
+
 ### v1.6.0
 
 - **Entity upsert** — `createEntities` now merges new observations into existing entities instead of silently ignoring duplicates. Entity type is also updated if a more specific type is provided.

package/dist/index.js

@@ -24,6 +24,7 @@ const DB_FILE_PATH = process.env.DB_FILE_PATH
         ? process.env.DB_FILE_PATH
         : path.join(path.dirname(fileURLToPath(import.meta.url)), process.env.DB_FILE_PATH)
     : defaultDbPath;
+const EMBEDDING_MODEL = process.env.EMBEDDING_MODEL || 'onnx-community/Qwen3-Embedding-0.6B-ONNX';
 // Safe rowid for vec0 virtual tables (require literal integer, not parameterized)
 function safeRowid(value) {
     const n = Number(value);
@@ -38,6 +39,8 @@ class RAGKnowledgeGraphManager {
     encoding = null;
     embeddingModel = null;
     modelInitialized = false;
+    embeddingCache = new Map();
+    EMBEDDING_CACHE_MAX = 500;
     async initialize() {
         console.error('🚀 Initializing RAG Knowledge Graph MCP Server...');
         // Initialize database
@@ -65,16 +68,16 @@ class RAGKnowledgeGraphManager {
     }
     async initializeEmbeddingModel() {
         try {
-            console.error('🤖 Loading embedding model: Qwen3-Embedding-0.6B (1024-dim, 100+ languages)...');
+            console.error(`🤖 Loading embedding model: ${EMBEDDING_MODEL} (1024-dim, 100+ languages)...`);
             // Configure environment to allow remote model downloads
             env.allowRemoteModels = true;
             env.allowLocalModels = true;
-            this.embeddingModel = await pipeline('feature-extraction', 'onnx-community/Qwen3-Embedding-0.6B-ONNX', {
+            this.embeddingModel = await pipeline('feature-extraction', EMBEDDING_MODEL, {
                 revision: 'main',
                 dtype: 'fp16',
             });
             this.modelInitialized = true;
-            console.error('✅ Qwen3-Embedding-0.6B model loaded successfully');
+            console.error(`✅ ${EMBEDDING_MODEL} model loaded successfully`);
         }
         catch (error) {
             console.error('❌ Failed to load embedding model:', error);
@@ -116,6 +119,7 @@ class RAGKnowledgeGraphManager {
             this.embeddingModel = null;
             this.modelInitialized = false;
         }
+        this.embeddingCache.clear();
         if (this.db) {
             this.db.close();
             this.db = null;
@@ -385,6 +389,115 @@ class RAGKnowledgeGraphManager {
         }));
         return { entities, relations };
     }
+    async getNeighbors(entityNames, depth = 1, relationType) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        // Cap depth at 5 to prevent runaway queries
+        const effectiveDepth = Math.min(Math.max(depth, 1), 5);
+        // Convert entity names to IDs
+        const seedIds = entityNames.map(name => `entity_${name.toLowerCase().replace(/[^a-z0-9]/g, '_')}`);
+        // Build dynamic placeholders for the seed IDs
+        const seedPlaceholders = seedIds.map(() => '?').join(',');
+        // Build the recursive CTE query
+        const relationFilter = relationType
+            ? `AND r.relationType = ?`
+            : '';
+        const cteQuery = `
+      WITH RECURSIVE traversal(entity_id, depth, path) AS (
+        -- Base case: seed entities
+        SELECT id, 0, id FROM entities WHERE id IN (${seedPlaceholders})
+        UNION ALL
+        -- Recursive: follow relationships up to max depth
+        SELECT
+          CASE WHEN r.source_entity = t.entity_id THEN r.target_entity ELSE r.source_entity END,
+          t.depth + 1,
+          t.path || ',' || CASE WHEN r.source_entity = t.entity_id THEN r.target_entity ELSE r.source_entity END
+        FROM traversal t
+        JOIN relationships r ON (r.source_entity = t.entity_id OR r.target_entity = t.entity_id)
+        WHERE t.depth < ?
+          ${relationFilter}
+          -- Cycle detection: don't revisit entities already in path
+          AND instr(t.path, CASE WHEN r.source_entity = t.entity_id THEN r.target_entity ELSE r.source_entity END) = 0
+      )
+      SELECT DISTINCT entity_id, MIN(depth) as min_depth, path
+      FROM traversal
+      GROUP BY entity_id
+    `;
+        // Build parameters
+        const params = [...seedIds, effectiveDepth];
+        if (relationType) {
+            params.push(relationType);
+        }
+        const traversalResults = this.db.prepare(cteQuery).all(...params);
+        if (traversalResults.length === 0) {
+            return { entities: [], relations: [], paths: [] };
+        }
+        // Collect all discovered entity IDs
+        const discoveredIds = traversalResults.map(r => r.entity_id);
+        const idPlaceholders = discoveredIds.map(() => '?').join(',');
+        // Fetch entity details
+        const entityRows = this.db.prepare(`
+      SELECT id, name, entityType, observations FROM entities WHERE id IN (${idPlaceholders})
+    `).all(...discoveredIds);
+        // Build id-to-depth and id-to-name maps
+        const idToDepth = new Map();
+        for (const r of traversalResults) {
+            idToDepth.set(r.entity_id, r.min_depth);
+        }
+        const idToName = new Map();
+        for (const row of entityRows) {
+            idToName.set(row.id, row.name);
+        }
+        const entities = entityRows.map(row => ({
+            name: row.name,
+            entityType: row.entityType,
+            observations: JSON.parse(row.observations),
+            depth: idToDepth.get(row.id) ?? 0,
+        }));
+        // Fetch relations between all discovered entities
+        let relQuery = `
+      SELECT
+        r.source_entity,
+        r.target_entity,
+        e1.name as from_name,
+        e2.name as to_name,
+        r.relationType
+      FROM relationships r
+      JOIN entities e1 ON r.source_entity = e1.id
+      JOIN entities e2 ON r.target_entity = e2.id
+      WHERE r.source_entity IN (${idPlaceholders})
+        AND r.target_entity IN (${idPlaceholders})
+    `;
+        const relParams = [...discoveredIds, ...discoveredIds];
+        if (relationType) {
+            relQuery += ` AND r.relationType = ?`;
+            relParams.push(relationType);
+        }
+        const relationRows = this.db.prepare(relQuery).all(...relParams);
+        const relations = relationRows.map(row => ({
+            from: row.from_name,
+            to: row.to_name,
+            relationType: row.relationType,
+            depth: Math.max(idToDepth.get(row.source_entity) ?? 0, idToDepth.get(row.target_entity) ?? 0),
+        }));
+        // Build shortest paths from seed entities to all discovered entities
+        const paths = [];
+        for (const result of traversalResults) {
+            if (result.min_depth === 0)
+                continue; // Skip seed entities themselves
+            const pathIds = result.path.split(',');
+            const pathNames = pathIds.map(id => idToName.get(id) || id).filter(Boolean);
+            if (pathNames.length >= 2) {
+                paths.push({
+                    from: pathNames[0],
+                    to: pathNames[pathNames.length - 1],
+                    path: pathNames,
+                });
+            }
+        }
+        console.error(`✅ getNeighbors: Found ${entities.length} entities, ${relations.length} relations, ${paths.length} paths (depth=${effectiveDepth})`);
+        return { entities, relations, paths };
+    }
     async searchNodes(query, limit = 10, since, until) {
         if (!this.db)
             throw new Error('Database not initialized');
@@ -920,6 +1033,11 @@ class RAGKnowledgeGraphManager {
     // Generate embeddings using sentence transformers
     // isQuery: true for search queries (adds instruction prefix), false for documents/entities
     async generateEmbedding(text, dimensions = 1024, isQuery = false) {
+        // Check cache first
+        const cacheKey = `${text.length > 100 ? text.substring(0, 100) : text}_${dimensions}_${isQuery}`;
+        const cached = this.embeddingCache.get(cacheKey);
+        if (cached)
+            return cached;
         if (this.modelInitialized && this.embeddingModel) {
             try {
                 // Qwen3: add instruction prefix for queries (task-specific instruction improves accuracy)
@@ -930,7 +1048,15 @@ class RAGKnowledgeGraphManager {
                 const result = await this.embeddingModel(inputText, { pooling: 'last_token', normalize: true });
                 // Extract the embedding array and convert to Float32Array
                 const embedding = result.data;
-                return new Float32Array(embedding.slice(0, dimensions));
+                const modelResult = new Float32Array(embedding.slice(0, dimensions));
+                // Cache the result (LRU: evict oldest if full)
+                if (this.embeddingCache.size >= this.EMBEDDING_CACHE_MAX) {
+                    const firstKey = this.embeddingCache.keys().next().value;
+                    if (firstKey)
+                        this.embeddingCache.delete(firstKey);
+                }
+                this.embeddingCache.set(cacheKey, modelResult);
+                return modelResult;
             }
             catch (error) {
                 console.error(`⚠️ Embedding model failed for text "${text.slice(0, 50)}...":`, error instanceof Error ? error.message : error);
@@ -943,7 +1069,15 @@ class RAGKnowledgeGraphManager {
         const normalizedText = text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').replace(/\s+/g, ' ').trim();
         const words = normalizedText.split(' ').filter(word => word.length > 1);
         if (words.length === 0) {
-            return new Float32Array(embedding);
+            const emptyResult = new Float32Array(embedding);
+            // Cache the result (LRU: evict oldest if full)
+            if (this.embeddingCache.size >= this.EMBEDDING_CACHE_MAX) {
+                const firstKey = this.embeddingCache.keys().next().value;
+                if (firstKey)
+                    this.embeddingCache.delete(firstKey);
+            }
+            this.embeddingCache.set(cacheKey, emptyResult);
+            return emptyResult;
         }
         // Enhanced word importance calculation
         const wordFreq = new Map();
@@ -1076,7 +1210,15 @@ class RAGKnowledgeGraphManager {
         // L2 normalization for cosine similarity
         const magnitude = Math.sqrt(embedding.reduce((sum, val) => sum + val * val, 0));
         const normalizedEmbedding = magnitude > 0 ? embedding.map(val => val / magnitude) : embedding;
-        return new Float32Array(normalizedEmbedding);
+        const fallbackResult = new Float32Array(normalizedEmbedding);
+        // Cache the result (LRU: evict oldest if full)
+        if (this.embeddingCache.size >= this.EMBEDDING_CACHE_MAX) {
+            const firstKey = this.embeddingCache.keys().next().value;
+            if (firstKey)
+                this.embeddingCache.delete(firstKey);
+        }
+        this.embeddingCache.set(cacheKey, fallbackResult);
+        return fallbackResult;
     }
     // Calculate position-based importance weight
     calculatePositionWeight(position, totalWords) {
@@ -2127,6 +2269,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.searchNodes(validatedArgs.query, validatedArgs.limit || 10, validatedArgs.since, validatedArgs.until), null, 2) }] };
             case "openNodes":
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.openNodes(validatedArgs.names), null, 2) }] };
+            case "getNeighbors":
+                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getNeighbors(validatedArgs.entityNames, validatedArgs.depth || 1, validatedArgs.relationType), null, 2) }] };
             // New RAG tools
             case "storeDocument":
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.storeDocument(validatedArgs.id, validatedArgs.content, validatedArgs.metadata || {}), null, 2) }] };
@@ -2183,12 +2327,17 @@ async function main() {
         const transport = new StdioServerTransport();
         await server.connect(transport);
         console.error("🚀 Enhanced RAG Knowledge Graph MCP Server running on stdio");
-        // Cleanup on exit
-        process.on('SIGINT', () => {
+        // Cleanup on exit — avoid process.exit() to prevent ONNX runtime mutex crash
+        const shutdown = () => {
             console.error('\n🧹 Cleaning up...');
-            ragKgManager.cleanup();
-            process.exit(0);
-        });
+            try {
+                ragKgManager.cleanup();
+            }
+            catch { }
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+        process.on('exit', shutdown);
     }
     catch (error) {
         console.error("Failed to initialize server:", error);