rag-memory-epf-mcp 3.2.1 → 3.3.0

package/README.md

@@ -128,6 +128,9 @@ storeDocument(id, content, metadata)
 
 ## Changelog
 
+### v3.2.1
+- **Fix: `autoLinkEntities` silent failure** — was JOINing a non-existent `observations` table (observations are stored as JSON array column in `entities`). Changed to direct column select + `JSON.parse()`.
+
 ### 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.

package/dist/index.js

@@ -9,6 +9,14 @@ import fsSync from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { pipeline, env } from '@huggingface/transformers';
+// Import graphology for graph analytics
+import Graph from 'graphology';
+import louvain from 'graphology-communities-louvain';
+import degree from 'graphology-metrics/centrality/degree.js';
+import betweennessCentrality from 'graphology-metrics/centrality/betweenness.js';
+import closenessCentrality from 'graphology-metrics/centrality/closeness.js';
+import pagerank from 'graphology-metrics/centrality/pagerank.js';
+import modularity from 'graphology-metrics/graph/modularity.js';
 // Import our new structured tool system
 import { getAllMCPTools, validateToolArgs, getSystemInfo } from './src/tools/tool-registry.js';
 // Import migration system
@@ -2079,6 +2087,246 @@ class RAGKnowledgeGraphManager {
             chunks: chunkCount.count
         };
     }
+    // === GRAPH ANALYTICS TOOLS (graphology) ===
+    _buildGraphologyGraph() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const graph = new Graph({ type: 'undirected', allowSelfLoops: false });
+        // Load entities as nodes
+        const entities = this.db.prepare('SELECT id, name, entityType FROM entities').all();
+        for (const entity of entities) {
+            graph.addNode(entity.id, { name: entity.name, entityType: entity.entityType });
+        }
+        // Load relationships as edges
+        const relations = this.db.prepare('SELECT id, source_entity, target_entity, relationType FROM relationships').all();
+        for (const rel of relations) {
+            if (graph.hasNode(rel.source_entity) && graph.hasNode(rel.target_entity)) {
+                try {
+                    graph.addEdge(rel.source_entity, rel.target_entity, {
+                        relationType: rel.relationType,
+                        id: rel.id,
+                    });
+                }
+                catch (e) {
+                    // Skip duplicate edges (graphology undirected merges A→B and B→A)
+                }
+            }
+        }
+        return { graph, entities };
+    }
+    async getGraphMetrics(entityNames, metrics, limit = 10) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const { graph } = this._buildGraphologyGraph();
+        if (graph.order === 0) {
+            return { metrics: {}, message: 'Knowledge graph is empty' };
+        }
+        const allMetrics = metrics || ['degree', 'betweenness', 'closeness', 'pagerank'];
+        const result = {};
+        if (allMetrics.includes('degree')) {
+            result.degree = degree.degreeCentrality(graph);
+        }
+        if (allMetrics.includes('betweenness')) {
+            result.betweenness = betweennessCentrality(graph);
+        }
+        if (allMetrics.includes('closeness')) {
+            result.closeness = closenessCentrality(graph);
+        }
+        if (allMetrics.includes('pagerank')) {
+            result.pagerank = pagerank(graph);
+        }
+        // Build id→name map
+        const idToName = new Map();
+        graph.forEachNode((id, attrs) => {
+            idToName.set(id, attrs.name);
+        });
+        // If specific entities requested, filter to those
+        if (entityNames && entityNames.length > 0) {
+            const targetIds = new Set();
+            for (const name of entityNames) {
+                const id = `entity_${name.toLowerCase().replace(/[^a-z0-9]/g, '_')}`;
+                if (graph.hasNode(id))
+                    targetIds.add(id);
+            }
+            const filtered = {};
+            for (const [metricName, scores] of Object.entries(result)) {
+                filtered[metricName] = {};
+                for (const id of targetIds) {
+                    const name = idToName.get(id) || id;
+                    filtered[metricName][name] = scores[id] ?? null;
+                }
+            }
+            return { metrics: filtered, entityCount: graph.order, edgeCount: graph.size };
+        }
+        // Otherwise return top-N per metric
+        const topResults = {};
+        for (const [metricName, scores] of Object.entries(result)) {
+            const sorted = Object.entries(scores)
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, limit)
+                .map(([id, score]) => ({
+                name: idToName.get(id) || id,
+                score: Math.round(score * 10000) / 10000,
+            }));
+            topResults[metricName] = sorted;
+        }
+        return { metrics: topResults, entityCount: graph.order, edgeCount: graph.size };
+    }
+    async detectCommunities(resolution = 1.0) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const { graph } = this._buildGraphologyGraph();
+        if (graph.order === 0) {
+            return { communities: [], modularity: 0, message: 'Knowledge graph is empty' };
+        }
+        // Run Louvain community detection — assign to node attributes
+        louvain.assign(graph, { resolution });
+        // Assign isolated nodes (Louvain skips degree-0 nodes)
+        let maxCommunityId = -1;
+        graph.forEachNode((id, attrs) => {
+            if (typeof attrs.community === 'number' && attrs.community > maxCommunityId) {
+                maxCommunityId = attrs.community;
+            }
+        });
+        graph.forEachNode((id, attrs) => {
+            if (attrs.community === undefined) {
+                graph.setNodeAttribute(id, 'community', ++maxCommunityId);
+            }
+        });
+        // Build id→name map
+        const idToName = new Map();
+        graph.forEachNode((id, attrs) => {
+            idToName.set(id, attrs.name);
+        });
+        // Group entities by community
+        const communityMap = new Map();
+        graph.forEachNode((nodeId, attrs) => {
+            const communityId = attrs.community;
+            if (!communityMap.has(communityId)) {
+                communityMap.set(communityId, []);
+            }
+            communityMap.get(communityId).push({
+                name: idToName.get(nodeId) || nodeId,
+                entityType: attrs.entityType,
+            });
+        });
+        // Sort communities by size (largest first)
+        const sortedCommunities = [...communityMap.entries()]
+            .sort((a, b) => b[1].length - a[1].length)
+            .map(([_id, members], index) => ({
+            communityId: index,
+            size: members.length,
+            members: members.sort((a, b) => a.name.localeCompare(b.name)),
+        }));
+        // Calculate modularity (reads 'community' attribute from nodes)
+        const modularityScore = modularity(graph);
+        // Cross-community edges
+        let crossEdges = 0;
+        graph.forEachEdge((_edge, _attrs, source, target) => {
+            const srcCommunity = graph.getNodeAttribute(source, 'community');
+            const tgtCommunity = graph.getNodeAttribute(target, 'community');
+            if (srcCommunity !== tgtCommunity)
+                crossEdges++;
+        });
+        return {
+            communities: sortedCommunities,
+            totalCommunities: sortedCommunities.length,
+            modularity: Math.round(modularityScore * 10000) / 10000,
+            crossCommunityEdges: crossEdges,
+            entityCount: graph.order,
+            edgeCount: graph.size,
+        };
+    }
+    async analyzeGraphStructure() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const { graph } = this._buildGraphologyGraph();
+        if (graph.order === 0) {
+            return { message: 'Knowledge graph is empty', entityCount: 0, edgeCount: 0 };
+        }
+        // Density
+        const density = graph.size > 0
+            ? (2 * graph.size) / (graph.order * (graph.order - 1))
+            : 0;
+        // Degree distribution
+        const degrees = [];
+        const isolatedNodes = [];
+        graph.forEachNode((id, attrs) => {
+            const deg = graph.degree(id);
+            degrees.push(deg);
+            if (deg === 0)
+                isolatedNodes.push(attrs.name);
+        });
+        degrees.sort((a, b) => a - b);
+        const avgDegree = degrees.reduce((s, d) => s + d, 0) / degrees.length;
+        const medianDegree = degrees[Math.floor(degrees.length / 2)];
+        // Connected components (BFS)
+        const visited = new Set();
+        const components = [];
+        graph.forEachNode((startId) => {
+            if (visited.has(startId))
+                return;
+            const component = [];
+            const queue = [startId];
+            visited.add(startId);
+            while (queue.length > 0) {
+                const nodeId = queue.shift();
+                component.push(graph.getNodeAttribute(nodeId, 'name'));
+                graph.forEachNeighbor(nodeId, (neighbor) => {
+                    if (!visited.has(neighbor)) {
+                        visited.add(neighbor);
+                        queue.push(neighbor);
+                    }
+                });
+            }
+            components.push(component);
+        });
+        components.sort((a, b) => b.length - a.length);
+        // Relationship type distribution
+        const relTypeCount = {};
+        graph.forEachEdge((_edge, attrs) => {
+            const type = attrs.relationType || 'UNKNOWN';
+            relTypeCount[type] = (relTypeCount[type] || 0) + 1;
+        });
+        // Average clustering coefficient
+        let totalClustering = 0;
+        let clusterableNodes = 0;
+        graph.forEachNode((nodeId) => {
+            const neighbors = graph.neighbors(nodeId);
+            if (neighbors.length < 2)
+                return;
+            let triangles = 0;
+            for (let i = 0; i < neighbors.length; i++) {
+                for (let j = i + 1; j < neighbors.length; j++) {
+                    if (graph.hasEdge(neighbors[i], neighbors[j]))
+                        triangles++;
+                }
+            }
+            const possibleTriangles = (neighbors.length * (neighbors.length - 1)) / 2;
+            totalClustering += triangles / possibleTriangles;
+            clusterableNodes++;
+        });
+        const avgClustering = clusterableNodes > 0 ? totalClustering / clusterableNodes : 0;
+        return {
+            entityCount: graph.order,
+            edgeCount: graph.size,
+            density: Math.round(density * 10000) / 10000,
+            connectedComponents: {
+                count: components.length,
+                largest: components[0]?.length || 0,
+                sizes: components.map(c => c.length),
+                isolatedNodes,
+            },
+            degreeDistribution: {
+                min: degrees[0],
+                max: degrees[degrees.length - 1],
+                avg: Math.round(avgDegree * 100) / 100,
+                median: medianDegree,
+            },
+            averageClusteringCoefficient: Math.round(avgClustering * 10000) / 10000,
+            relationshipTypes: relTypeCount,
+        };
+    }
     // === MIGRATION TOOLS ===
     async getMigrationStatus() {
         if (!this.db)
@@ -2218,6 +2466,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.runMigrations(), null, 2) }] };
             case "rollbackMigration":
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.rollbackMigration(validatedArgs.targetVersion), null, 2) }] };
+            // Graph Analytics tools (graphology)
+            case "getGraphMetrics":
+                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getGraphMetrics(validatedArgs.entityNames, validatedArgs.metrics, validatedArgs.limit || 10), null, 2) }] };
+            case "detectCommunities":
+                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.detectCommunities(validatedArgs.resolution || 1.0), null, 2) }] };
+            case "analyzeGraphStructure":
+                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.analyzeGraphStructure(), null, 2) }] };
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/src/tools/graph-analytics-tools.d.ts

@@ -0,0 +1,9 @@
+import { ToolDefinition } from './types.js';
+export declare const getGraphMetricsTool: ToolDefinition;
+export declare const detectCommunitiesTool: ToolDefinition;
+export declare const analyzeGraphStructureTool: ToolDefinition;
+export declare const graphAnalyticsTools: {
+    getGraphMetrics: ToolDefinition;
+    detectCommunities: ToolDefinition;
+    analyzeGraphStructure: ToolDefinition;
+};

package/dist/src/tools/graph-analytics-tools.js

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+// === GET GRAPH METRICS TOOL ===
+const getGraphMetricsCapability = {
+    description: 'Calculate centrality metrics for entities using graphology graph analysis',
+    parameters: {
+        type: 'object',
+        properties: {
+            entityNames: {
+                type: 'array',
+                description: 'Entity names to calculate metrics for. If empty, returns top entities by each metric.',
+                items: { type: 'string' },
+            },
+            metrics: {
+                type: 'array',
+                description: 'Which metrics to compute: degree, betweenness, closeness, pagerank',
+                items: { type: 'string' },
+            },
+            limit: {
+                type: 'number',
+                description: 'Max entities to return when entityNames is empty (default 10)',
+                default: 10,
+            },
+        },
+        required: [],
+    },
+};
+const getGraphMetricsDescription = () => `<description>
+Calculate centrality metrics for entities using graphology graph analysis algorithms.
+**Identifies the most important, influential, and bridging entities in your knowledge graph.**
+Supports degree, betweenness, closeness centrality and PageRank.
+</description>
+
+<importantNotes>
+- (!important!) **Builds in-memory graph** from SQLite data — lightweight for typical knowledge graphs
+- (!important!) Returns centrality scores normalized to 0-1 range
+- (!important!) When no entityNames provided, returns top entities ranked by each metric
+- (!important!) Useful for identifying knowledge hubs, bridges, and peripheral entities
+</importantNotes>
+
+<whenToUseThisTool>
+- To find the most connected/important entities in your knowledge graph
+- To identify bridge entities that connect different knowledge domains
+- To discover peripheral entities that may need more connections
+- For knowledge graph health analysis and optimization
+- Before consolidation — to identify which entities are structurally important
+</whenToUseThisTool>
+
+<features>
+- Degree centrality: most connected entities (hub detection)
+- Betweenness centrality: entities bridging different clusters
+- Closeness centrality: entities with shortest average distance to all others
+- PageRank: recursive importance based on connections to important entities
+- Supports both targeted (specific entities) and discovery (top-N) modes
+</features>
+
+<bestPractices>
+- Use without entityNames first to discover important entities
+- Combine with detectCommunities for deeper structural analysis
+- High betweenness + low degree = critical bridge (fragile point)
+- High degree + high PageRank = knowledge hub
+- Run periodically to track how graph structure evolves
+</bestPractices>
+
+<parameters>
+- entityNames: (optional) Specific entities to analyze. If omitted, returns top entities by each metric.
+- metrics: (optional) Array of metrics to compute: "degree", "betweenness", "closeness", "pagerank". Default: all.
+- limit: (optional) Max results per metric when entityNames is empty. Default: 10.
+</parameters>
+
+<examples>
+- Top entities: {} (returns top 10 by all metrics)
+- Specific entities: {"entityNames": ["Entity A", "Entity B"]}
+- PageRank only: {"metrics": ["pagerank"], "limit": 20}
+</examples>`;
+const getGraphMetricsSchema = {
+    entityNames: z.array(z.string().describe('Entity name')).optional().describe('Entity names to analyze'),
+    metrics: z.array(z.string().describe('Metric name')).optional().describe('Metrics to compute: degree, betweenness, closeness, pagerank'),
+    limit: z.number().optional().default(10).describe('Max results per metric'),
+};
+export const getGraphMetricsTool = {
+    capability: getGraphMetricsCapability,
+    description: getGraphMetricsDescription,
+    schema: getGraphMetricsSchema,
+    annotations: { readOnlyHint: true },
+};
+// === DETECT COMMUNITIES TOOL ===
+const detectCommunitiesCapability = {
+    description: 'Detect communities/clusters in the knowledge graph using Louvain algorithm',
+    parameters: {
+        type: 'object',
+        properties: {
+            resolution: {
+                type: 'number',
+                description: 'Resolution parameter for Louvain (higher = more communities). Default: 1.0',
+                default: 1.0,
+            },
+        },
+        required: [],
+    },
+};
+const detectCommunitiesDescription = () => `<description>
+Detect communities (clusters) in the knowledge graph using the Louvain modularity algorithm.
+**Reveals natural groupings and topic clusters within your knowledge base.**
+Automatically identifies which entities belong together based on connection patterns.
+</description>
+
+<importantNotes>
+- (!important!) Uses Louvain algorithm — fast and effective for modularity optimization
+- (!important!) Returns community assignments for every entity
+- (!important!) Higher resolution parameter produces more, smaller communities
+- (!important!) Modularity score indicates clustering quality (0-1, higher = better defined clusters)
+</importantNotes>
+
+<whenToUseThisTool>
+- To discover natural topic clusters in your knowledge graph
+- To understand how your knowledge is organized structurally
+- Before reorganization — to see which entities naturally group together
+- For identifying isolated clusters that may need cross-linking
+- To validate that related entities are actually well-connected
+</whenToUseThisTool>
+
+<features>
+- Louvain community detection with configurable resolution
+- Returns named communities with member entities
+- Modularity score for clustering quality assessment
+- Community size distribution for balance analysis
+- Cross-community relationship identification
+</features>
+
+<bestPractices>
+- Start with default resolution (1.0), adjust if clusters are too large/small
+- Resolution < 1.0 = fewer, larger communities; > 1.0 = more, smaller communities
+- Single-entity communities may indicate orphaned or poorly connected entities
+- Compare community structure over time to track knowledge evolution
+- Use with getGraphMetrics to find important entities within each community
+</bestPractices>
+
+<parameters>
+- resolution: (optional) Louvain resolution. Default: 1.0. Lower = fewer clusters, Higher = more clusters.
+</parameters>
+
+<examples>
+- Default clustering: {}
+- Fine-grained: {"resolution": 2.0}
+- Coarse: {"resolution": 0.5}
+</examples>`;
+const detectCommunitiesSchema = {
+    resolution: z.number().optional().default(1.0).describe('Louvain resolution parameter'),
+};
+export const detectCommunitiesTool = {
+    capability: detectCommunitiesCapability,
+    description: detectCommunitiesDescription,
+    schema: detectCommunitiesSchema,
+    annotations: { readOnlyHint: true },
+};
+// === ANALYZE GRAPH STRUCTURE TOOL ===
+const analyzeGraphStructureCapability = {
+    description: 'Analyze overall knowledge graph structure: density, components, diameter, clustering',
+    parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+};
+const analyzeGraphStructureDescription = () => `<description>
+Analyze the overall structural properties of your knowledge graph.
+**Provides a health dashboard for graph connectivity, density, and structure.**
+Complements getKnowledgeGraphStats (which counts entities/relations) with structural analysis.
+</description>
+
+<importantNotes>
+- (!important!) Returns graph-theoretic metrics: density, components, diameter, clustering coefficient
+- (!important!) Identifies disconnected components (isolated subgraphs)
+- (!important!) Detects structural issues: low density, fragmentation, bottlenecks
+- (!important!) Computationally heavier than stats — use periodically, not every session
+</importantNotes>
+
+<whenToUseThisTool>
+- For periodic graph health assessment (weekly or after major changes)
+- To detect fragmentation — disconnected components that should be linked
+- To measure graph density — is the knowledge well-interconnected?
+- Before and after consolidation — to measure structural improvement
+- When graph feels "sparse" and you want to quantify it
+</whenToUseThisTool>
+
+<features>
+- Graph density (actual edges / possible edges)
+- Connected component analysis with sizes
+- Average clustering coefficient (local connectivity)
+- Degree distribution statistics (min, max, avg, median)
+- Isolated node detection
+- Relationship type distribution
+</features>
+
+<bestPractices>
+- Run after major entity additions to check integration
+- Compare density over time — decreasing density may indicate growing but disconnected knowledge
+- Multiple small components suggest domain silos that need cross-linking
+- Use alongside detectCommunities for complete structural understanding
+</bestPractices>
+
+<parameters>
+- None required — analyzes the entire graph structure
+</parameters>
+
+<examples>
+- Full analysis: {} (no parameters needed)
+</examples>`;
+const analyzeGraphStructureSchema = {};
+export const analyzeGraphStructureTool = {
+    capability: analyzeGraphStructureCapability,
+    description: analyzeGraphStructureDescription,
+    schema: analyzeGraphStructureSchema,
+    annotations: { readOnlyHint: true },
+};
+// === EXPORT ===
+export const graphAnalyticsTools = {
+    getGraphMetrics: getGraphMetricsTool,
+    detectCommunities: detectCommunitiesTool,
+    analyzeGraphStructure: analyzeGraphStructureTool,
+};

package/dist/src/tools/tool-registry.d.ts

@@ -1,5 +1,8 @@
 import { ToolDefinition, MCPTool } from './types.js';
 export declare const allTools: {
+    getGraphMetrics: ToolDefinition;
+    detectCommunities: ToolDefinition;
+    analyzeGraphStructure: ToolDefinition;
     readGraph: ToolDefinition;
     searchNodes: ToolDefinition;
     openNodes: ToolDefinition;
@@ -53,6 +56,7 @@ export declare function getToolsByCategory(): {
     knowledgeGraph: string[];
     rag: string[];
     graphQuery: string[];
+    graphAnalytics: string[];
     migration: string[];
     all: string[];
 };
@@ -73,12 +77,14 @@ export declare function getSystemInfo(): {
         knowledgeGraph: number;
         rag: number;
         graphQuery: number;
+        graphAnalytics: number;
         total: number;
     };
     availableTools: {
         knowledgeGraph: string[];
         rag: string[];
         graphQuery: string[];
+        graphAnalytics: string[];
         migration: string[];
         all: string[];
     };

package/dist/src/tools/tool-registry.js

@@ -2,14 +2,15 @@ import { z } from 'zod';
 import { knowledgeGraphTools } from './knowledge-graph-tools.js';
 import { ragTools } from './rag-tools.js';
 import { graphQueryTools } from './graph-query-tools.js';
+import { graphAnalyticsTools } from './graph-analytics-tools.js';
 import { migrationTools } from './migration-tools.js';
 // Central registry of all tools
 export const allTools = {
     ...knowledgeGraphTools,
     ...ragTools,
     ...graphQueryTools,
+    ...graphAnalyticsTools,
     ...migrationTools,
-    // Add other tool categories here as needed
 };
 // Global settings for tool descriptions
 export const globalSettings = {
@@ -153,6 +154,7 @@ export function getToolsByCategory() {
         knowledgeGraph: Object.keys(knowledgeGraphTools),
         rag: Object.keys(ragTools),
         graphQuery: Object.keys(graphQueryTools),
+        graphAnalytics: Object.keys(graphAnalyticsTools),
         migration: Object.keys(migrationTools),
         all: Object.keys(allTools),
     };
@@ -178,6 +180,7 @@ export function getSystemInfo() {
             knowledgeGraph: categories.knowledgeGraph.length,
             rag: categories.rag.length,
             graphQuery: categories.graphQuery.length,
+            graphAnalytics: categories.graphAnalytics.length,
             total: categories.all.length,
         },
         availableTools: categories,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rag-memory-epf-mcp",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "MCP server for project-local RAG memory with knowledge graph and multilingual vector search",
   "license": "MIT",
   "author": "bripin123",
@@ -27,6 +27,11 @@
     "@huggingface/transformers": "^3.5.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "better-sqlite3": "^12.8.0",
+    "graphology": "^0.26.0",
+    "graphology-communities-louvain": "^2.0.2",
+    "graphology-metrics": "^2.4.0",
+    "graphology-shortest-path": "^2.1.0",
+    "graphology-types": "^0.24.8",
     "sqlite-vec": "^0.1.7",
     "tiktoken": "^1.0.17",
     "zod": "^3.25.28"