rag-memory-epf-mcp 3.1.5 → 3.2.1

package/README.md

@@ -12,6 +12,7 @@ A **project-local RAG memory** MCP server — knowledge graph + multilingual vec
 - **Project-local isolation** — each project gets its own `.memory/rag-memory.db`. Multiple projects run simultaneously without interference.
 - **3-signal hybrid search** — vector similarity (bge-m3, 1024-dim) + FTS5 BM25 keyword matching + knowledge graph re-ranking, combined via Reciprocal Rank Fusion
 - **100+ languages** — Korean, Chinese, Japanese, Arabic, and more. Cross-lingual search works out of the box.
+- **Graph-aware scoring** — per-entity geometric decay (0.5^i) with hard cap prevents any single document from dominating results
 - **27 MCP tools** — entity/relation CRUD, document pipeline, multi-hop graph traversal, export/import, temporal queries
 - **SQLite optimized** — WAL mode, 32MB cache, 256MB mmap, FTS5 triggers, 7 indexes
 - **MCP SDK 1.27.1** — Tool Annotations (readOnly/destructive/idempotent), latest protocol 2025-11-25
@@ -55,7 +56,7 @@ Place this `.mcp.json` in each project folder with its own `DB_FILE_PATH`. Each
 | `embedChunks` | Generate 1024-dim embeddings + auto-link entities | idempotent |
 | `embedAllEntities` | Batch embed all entities (32 parallel) | idempotent |
 | `extractTerms` | Extract potential entity terms | — |
-| `linkEntitiesToDocument` | Manually link entities to document chunks | idempotent |
+| `linkEntitiesToDocument` | Link entities to chunks where they actually appear (text-matched) | idempotent |
 | `deleteDocuments` | Remove documents and associated data | destructive |
 | `listDocuments` | View all stored documents | readOnly |
 
@@ -127,6 +128,10 @@ storeDocument(id, content, metadata)
 
 ## Changelog
 
+### v3.2.0
+- **Chunk-level entity linking in `linkEntitiesToDocument`** — entities are now linked only to chunks where they actually appear (using `buildEntityMatcher` word-boundary/CJK matching), instead of blanket-linking to all chunks. Fixes search result domination by heavily-linked documents.
+- **Graph boost decay + hard cap** — per-entity scores are sorted descending and decayed geometrically (0.5^i): 1st entity 100%, 2nd 50%, 3rd 25%, etc. Hard cap at 0.4 prevents graph signal from overwhelming vector similarity.
+
 ### v3.0.0
 - **Back to self-contained embeddings** — reverted from Ollama dependency (v2.x) to built-in `@huggingface/transformers` with bge-m3 (1024-dim). No external services required.
 - **Cross-lingual search** — auto-detects non-English queries and performs dual-language search

package/dist/index.js

@@ -1264,11 +1264,7 @@ class RAGKnowledgeGraphManager {
             if (chunks.length === 0)
                 return 0;
             // Get all entities with observations for richer matching
-            const entities = this.db.prepare(`SELECT e.id, e.name, e.entityType,
-                GROUP_CONCAT(o.content, ' ||| ') as observations
-         FROM entities e
-         LEFT JOIN observations o ON o.entityId = e.id
-         GROUP BY e.id`).all();
+            const entities = this.db.prepare(`SELECT id, name, entityType, observations FROM entities`).all();
             // Minimum name length: 2 for CJK (e.g. "할랄"), 4 for Latin (avoid "API", "Bug")
             const MIN_LEN_CJK = 2;
             const MIN_LEN_LATIN = 4;
@@ -1284,7 +1280,13 @@ class RAGKnowledgeGraphManager {
                 // Also collect observation-derived aliases (short keywords from observations)
                 const aliases = [];
                 if (entity.observations) {
-                    const obs = entity.observations.split(' ||| ');
+                    let obs;
+                    try {
+                        obs = JSON.parse(entity.observations);
+                    }
+                    catch {
+                        obs = [];
+                    }
                     for (const ob of obs) {
                         // Extract file paths or identifiers mentioned in observations (e.g. "gemini_converter.py")
                         const pathMatch = ob.match(/[\w\-]+\.\w{1,4}\b/g);
@@ -1345,11 +1347,14 @@ class RAGKnowledgeGraphManager {
         if (!document) {
             throw new Error(`Document with ID ${documentId} not found`);
         }
-        // Get chunks for this document
+        // Get chunks for this document (with text for chunk-level matching)
         const chunks = this.db.prepare(`
-      SELECT rowid FROM chunk_metadata WHERE document_id = ?
+      SELECT rowid, text FROM chunk_metadata WHERE document_id = ?
     `).all(documentId);
         let linkedCount = 0;
+        const insertStmt = this.db.prepare(`
+      INSERT OR IGNORE INTO chunk_entities (chunk_rowid, entity_id) VALUES (?, ?)
+    `);
         for (const entityName of entityNames) {
             const entityId = `entity_${entityName.toLowerCase().replace(/[^a-z0-9]/g, '_')}`;
             // Verify entity exists
@@ -1360,14 +1365,17 @@ class RAGKnowledgeGraphManager {
                 console.warn(`Entity ${entityName} not found, skipping`);
                 continue;
             }
-            // Link entity to all chunks of the document
+            // Chunk-level filtering: only link to chunks where entity actually appears
+            const nameMatcher = this.buildEntityMatcher(entityName);
+            let entityLinked = false;
             for (const chunk of chunks) {
-                this.db.prepare(`
-          INSERT OR IGNORE INTO chunk_entities (chunk_rowid, entity_id)
-          VALUES (?, ?)
-        `).run(chunk.rowid, entityId);
+                if (nameMatcher(chunk.text)) {
+                    insertStmt.run(chunk.rowid, entityId);
+                    entityLinked = true;
+                }
             }
-            linkedCount++;
+            if (entityLinked)
+                linkedCount++;
         }
         console.error(`✅ Entities linked: ${linkedCount} entities linked to document`);
         return { documentId, linkedEntities: linkedCount };
@@ -1868,42 +1876,54 @@ class RAGKnowledgeGraphManager {
                     chunkEntities = [relEntities.source_name, relEntities.target_name];
                 }
             }
-            // Enhanced graph boost calculation
+            // Enhanced graph boost calculation with decay + cap
             let graphBoost = 0;
             if (useGraph) {
                 const queryEntities = this.extractTermsFromText(query);
                 // Base boost for knowledge graph chunks
                 if (result.chunk_type === 'entity') {
-                    graphBoost += 0.15; // Entities are inherently valuable
+                    graphBoost += 0.15;
                 }
                 else if (result.chunk_type === 'relationship') {
-                    graphBoost += 0.25; // Relationships show connections
+                    graphBoost += 0.25;
                 }
-                // Additional boost for entity matches
+                // Collect per-entity scores (instead of blind accumulation)
+                const entityScores = [];
                 const queryLower = query.toLowerCase();
                 for (const entity of chunkEntities) {
+                    let score = 0;
                     const entityLower = entity.toLowerCase();
                     // Vector-matched entity (cross-lingual: "할랄 인증" → "KMF")
                     if (queryMatchedEntities.has(entity)) {
-                        graphBoost += 0.3;
+                        score = 0.3;
                     }
                     // Exact text match with extracted terms
                     else if (queryEntities.some(qe => qe.toLowerCase() === entityLower)) {
-                        graphBoost += 0.3;
+                        score = 0.3;
                     }
                     // Partial match: entity name appears in query or vice versa
                     else if (queryLower.includes(entityLower) || entityLower.includes(queryLower)) {
-                        graphBoost += 0.2;
+                        score = 0.2;
                     }
                     // Word-level partial match
                     else if (entityLower.split(/\s+/).some(word => word.length >= 3 && queryLower.includes(word))) {
-                        graphBoost += 0.15;
+                        score = 0.15;
                     }
-                    // Connected to a vector-matched entity
+                    // Connected to a vector-matched entity (additive, independent)
                     if (connectedEntities.has(entity)) {
-                        graphBoost += 0.15;
+                        score += 0.15;
                     }
+                    if (score > 0)
+                        entityScores.push(score);
+                }
+                // Geometric decay: sort descending, apply 0.5^i decay per entity
+                entityScores.sort((a, b) => b - a);
+                let entityBoost = 0;
+                for (let i = 0; i < entityScores.length; i++) {
+                    entityBoost += entityScores[i] * Math.pow(0.5, i);
                 }
+                // Hard cap to prevent graph domination
+                graphBoost += Math.min(entityBoost, 0.4);
             }
             // Generate semantic summary
             const { summary, keyHighlight, relevanceScore } = await this.generateContentSummary(result.text, primaryQueryEmbedding, chunkEntities, result.chunk_type === 'relationship' ? 1 : 2 // Shorter summary for relationships

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rag-memory-epf-mcp",
-  "version": "3.1.5",
+  "version": "3.2.1",
   "description": "MCP server for project-local RAG memory with knowledge graph and multilingual vector search",
   "license": "MIT",
   "author": "bripin123",