code-graph-context 2.2.0 → 2.4.0

package/dist/mcp/tools/swarm-cleanup.tool.js

@@ -0,0 +1,157 @@
+/**
+ * Swarm Cleanup Tool
+ * Bulk delete pheromones after a swarm completes
+ */
+import { z } from 'zod';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+/**
+ * Neo4j query to delete pheromones by swarm ID
+ */
+const CLEANUP_BY_SWARM_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND p.swarmId = $swarmId
+    AND NOT p.type IN $keepTypes
+  WITH p, p.agentId as agentId, p.type as type
+  DETACH DELETE p
+  RETURN count(p) as deleted, collect(DISTINCT agentId) as agents, collect(DISTINCT type) as types
+`;
+/**
+ * Neo4j query to delete pheromones by agent ID
+ */
+const CLEANUP_BY_AGENT_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND p.agentId = $agentId
+    AND NOT p.type IN $keepTypes
+  WITH p, p.swarmId as swarmId, p.type as type
+  DETACH DELETE p
+  RETURN count(p) as deleted, collect(DISTINCT swarmId) as swarms, collect(DISTINCT type) as types
+`;
+/**
+ * Neo4j query to delete all pheromones in a project
+ */
+const CLEANUP_ALL_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND NOT p.type IN $keepTypes
+  WITH p, p.agentId as agentId, p.swarmId as swarmId, p.type as type
+  DETACH DELETE p
+  RETURN count(p) as deleted, collect(DISTINCT agentId) as agents, collect(DISTINCT swarmId) as swarms, collect(DISTINCT type) as types
+`;
+/**
+ * Count queries for dry run
+ */
+const COUNT_BY_SWARM_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId AND p.swarmId = $swarmId AND NOT p.type IN $keepTypes
+  RETURN count(p) as count, collect(DISTINCT p.agentId) as agents, collect(DISTINCT p.type) as types
+`;
+const COUNT_BY_AGENT_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId AND p.agentId = $agentId AND NOT p.type IN $keepTypes
+  RETURN count(p) as count, collect(DISTINCT p.swarmId) as swarms, collect(DISTINCT p.type) as types
+`;
+const COUNT_ALL_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId AND NOT p.type IN $keepTypes
+  RETURN count(p) as count, collect(DISTINCT p.agentId) as agents, collect(DISTINCT p.swarmId) as swarms, collect(DISTINCT p.type) as types
+`;
+export const createSwarmCleanupTool = (server) => {
+    server.registerTool(TOOL_NAMES.swarmCleanup, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmCleanup].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmCleanup].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path'),
+            swarmId: z.string().optional().describe('Delete all pheromones from this swarm'),
+            agentId: z.string().optional().describe('Delete all pheromones from this agent'),
+            all: z.boolean().optional().default(false).describe('Delete ALL pheromones in project (use with caution)'),
+            keepTypes: z
+                .array(z.string())
+                .optional()
+                .default(['warning'])
+                .describe('Pheromone types to preserve (default: ["warning"])'),
+            dryRun: z.boolean().optional().default(false).describe('Preview what would be deleted without deleting'),
+        },
+    }, async ({ projectId, swarmId, agentId, all = false, keepTypes = ['warning'], dryRun = false }) => {
+        const neo4jService = new Neo4jService();
+        // Resolve project ID
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            // Validate: must specify swarmId, agentId, or all
+            if (!swarmId && !agentId && !all) {
+                return createErrorResponse('Must specify one of: swarmId, agentId, or all=true. Use dryRun=true to preview.');
+            }
+            await debugLog('Swarm cleanup operation', {
+                projectId: resolvedProjectId,
+                swarmId,
+                agentId,
+                all,
+                keepTypes,
+                dryRun,
+            });
+            const params = { projectId: resolvedProjectId, keepTypes };
+            let deleteQuery;
+            let countQuery;
+            let mode;
+            if (swarmId) {
+                params.swarmId = swarmId;
+                deleteQuery = CLEANUP_BY_SWARM_QUERY;
+                countQuery = COUNT_BY_SWARM_QUERY;
+                mode = 'swarm';
+            }
+            else if (agentId) {
+                params.agentId = agentId;
+                deleteQuery = CLEANUP_BY_AGENT_QUERY;
+                countQuery = COUNT_BY_AGENT_QUERY;
+                mode = 'agent';
+            }
+            else {
+                deleteQuery = CLEANUP_ALL_QUERY;
+                countQuery = COUNT_ALL_QUERY;
+                mode = 'all';
+            }
+            if (dryRun) {
+                const result = await neo4jService.run(countQuery, params);
+                const count = result[0]?.count ?? 0;
+                return createSuccessResponse(JSON.stringify({
+                    success: true,
+                    dryRun: true,
+                    mode,
+                    wouldDelete: typeof count === 'object' && 'toNumber' in count ? count.toNumber() : count,
+                    agents: result[0]?.agents ?? [],
+                    swarms: result[0]?.swarms ?? [],
+                    types: result[0]?.types ?? [],
+                    keepTypes,
+                    projectId: resolvedProjectId,
+                }));
+            }
+            const result = await neo4jService.run(deleteQuery, params);
+            const deleted = result[0]?.deleted ?? 0;
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                mode,
+                deleted: typeof deleted === 'object' && 'toNumber' in deleted ? deleted.toNumber() : deleted,
+                agents: result[0]?.agents ?? [],
+                swarms: result[0]?.swarms ?? [],
+                types: result[0]?.types ?? [],
+                keepTypes,
+                projectId: resolvedProjectId,
+            }));
+        }
+        catch (error) {
+            await debugLog('Swarm cleanup error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

package/dist/mcp/tools/swarm-constants.js

@@ -0,0 +1,35 @@
+/**
+ * Shared constants for swarm coordination tools
+ */
+/**
+ * Pheromone types and their half-lives in milliseconds.
+ * Half-life determines decay rate - after one half-life, intensity drops to 50%.
+ */
+export const PHEROMONE_CONFIG = {
+    exploring: { halfLife: 2 * 60 * 1000, description: 'Browsing/reading' },
+    modifying: { halfLife: 10 * 60 * 1000, description: 'Active work' },
+    claiming: { halfLife: 60 * 60 * 1000, description: 'Ownership' },
+    completed: { halfLife: 24 * 60 * 60 * 1000, description: 'Done' },
+    warning: { halfLife: -1, description: 'Never decays' },
+    blocked: { halfLife: 5 * 60 * 1000, description: 'Stuck' },
+    proposal: { halfLife: 60 * 60 * 1000, description: 'Awaiting approval' },
+    needs_review: { halfLife: 30 * 60 * 1000, description: 'Review requested' },
+};
+export const PHEROMONE_TYPES = Object.keys(PHEROMONE_CONFIG);
+/**
+ * Get half-life for a pheromone type.
+ * Returns -1 for types that never decay (e.g., warning).
+ */
+export const getHalfLife = (type) => {
+    return PHEROMONE_CONFIG[type]?.halfLife ?? PHEROMONE_CONFIG.exploring.halfLife;
+};
+/**
+ * Workflow states are mutually exclusive per agent+node.
+ * Setting one removes others in this group.
+ * Flags (warning, proposal, needs_review) can coexist with workflow states.
+ */
+export const WORKFLOW_STATES = ['exploring', 'claiming', 'modifying', 'completed', 'blocked'];
+/**
+ * Flags can coexist with workflow states.
+ */
+export const FLAG_TYPES = ['warning', 'proposal', 'needs_review'];

package/dist/mcp/tools/swarm-pheromone.tool.js

@@ -0,0 +1,196 @@
+/**
+ * Swarm Pheromone Tool
+ * Leave a pheromone marker on a code node for stigmergic coordination
+ */
+import { z } from 'zod';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+import { PHEROMONE_TYPES, WORKFLOW_STATES, getHalfLife } from './swarm-constants.js';
+/**
+ * Neo4j query to clean up other workflow states before setting a new one.
+ * Only runs for workflow state pheromones, not flags.
+ */
+const CLEANUP_WORKFLOW_STATES_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND p.nodeId = $nodeId
+    AND p.agentId = $agentId
+    AND p.swarmId = $swarmId
+    AND p.type IN $workflowStates
+    AND p.type <> $newType
+  DETACH DELETE p
+  RETURN count(p) as cleaned
+`;
+/**
+ * Neo4j query to create or update a pheromone
+ */
+const CREATE_PHEROMONE_QUERY = `
+  // Find the target code node (exclude other pheromones)
+  MATCH (target)
+  WHERE target.id = $nodeId
+    AND target.projectId = $projectId
+    AND NOT target:Pheromone
+  WITH target
+  LIMIT 1
+
+  // Create or update pheromone (scoped to project)
+  MERGE (p:Pheromone {projectId: $projectId, nodeId: $nodeId, agentId: $agentId, swarmId: $swarmId, type: $type})
+  ON CREATE SET
+    p.id = randomUUID(),
+    p.intensity = $intensity,
+    p.timestamp = timestamp(),
+    p.data = $data,
+    p.halfLife = $halfLife
+  ON MATCH SET
+    p.intensity = $intensity,
+    p.timestamp = timestamp(),
+    p.data = $data
+
+  // Create relationship to target node if it exists
+  WITH p, target
+  WHERE target IS NOT NULL
+  MERGE (p)-[:MARKS]->(target)
+
+  RETURN p.id as id, p.nodeId as nodeId, p.projectId as projectId, p.type as type, p.intensity as intensity,
+         p.timestamp as timestamp, p.agentId as agentId, p.swarmId as swarmId,
+         CASE WHEN target IS NOT NULL THEN true ELSE false END as linkedToNode
+`;
+/**
+ * Neo4j query to delete a pheromone
+ */
+const DELETE_PHEROMONE_QUERY = `
+  MATCH (p:Pheromone {projectId: $projectId, nodeId: $nodeId, agentId: $agentId, swarmId: $swarmId, type: $type})
+  DETACH DELETE p
+  RETURN count(p) as deleted
+`;
+export const createSwarmPheromoneTool = (server) => {
+    server.registerTool(TOOL_NAMES.swarmPheromone, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmPheromone].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmPheromone].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            nodeId: z.string().describe('The code node ID to mark with a pheromone'),
+            type: z
+                .enum(PHEROMONE_TYPES)
+                .describe('Type of pheromone: exploring (browsing), modifying (active work), claiming (ownership), completed (done), warning (danger), blocked (stuck), proposal (awaiting approval), needs_review (review request)'),
+            intensity: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .default(1.0)
+                .describe('Pheromone intensity from 0.0 to 1.0 (default: 1.0)'),
+            agentId: z.string().describe('Unique identifier for the agent leaving the pheromone'),
+            swarmId: z.string().describe('Swarm ID for grouping related agents (e.g., "swarm_xyz")'),
+            data: z
+                .record(z.unknown())
+                .optional()
+                .describe('Optional metadata to attach to the pheromone (e.g., summary, reason)'),
+            remove: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, removes the pheromone instead of creating/updating it'),
+        },
+    }, async ({ projectId, nodeId, type, intensity = 1.0, agentId, swarmId, data, remove = false }) => {
+        const neo4jService = new Neo4jService();
+        // Resolve project ID
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            if (remove) {
+                const result = await neo4jService.run(DELETE_PHEROMONE_QUERY, {
+                    projectId: resolvedProjectId,
+                    nodeId,
+                    agentId,
+                    swarmId,
+                    type,
+                });
+                const deleted = result[0]?.deleted ?? 0;
+                if (deleted > 0) {
+                    return createSuccessResponse(JSON.stringify({
+                        success: true,
+                        action: 'removed',
+                        projectId: resolvedProjectId,
+                        nodeId,
+                        type,
+                        agentId,
+                        swarmId,
+                    }));
+                }
+                else {
+                    return createSuccessResponse(JSON.stringify({
+                        success: true,
+                        action: 'not_found',
+                        message: 'No matching pheromone found to remove',
+                        projectId: resolvedProjectId,
+                        nodeId,
+                        type,
+                        agentId,
+                        swarmId,
+                    }));
+                }
+            }
+            // Create or update pheromone
+            const halfLife = getHalfLife(type);
+            const dataJson = data ? JSON.stringify(data) : null;
+            // If setting a workflow state, clean up other workflow states first
+            let cleanedStates = 0;
+            if (WORKFLOW_STATES.includes(type)) {
+                const cleanupResult = await neo4jService.run(CLEANUP_WORKFLOW_STATES_QUERY, {
+                    projectId: resolvedProjectId,
+                    nodeId,
+                    agentId,
+                    swarmId,
+                    workflowStates: WORKFLOW_STATES,
+                    newType: type,
+                });
+                cleanedStates = cleanupResult[0]?.cleaned ?? 0;
+            }
+            const result = await neo4jService.run(CREATE_PHEROMONE_QUERY, {
+                projectId: resolvedProjectId,
+                nodeId,
+                type,
+                intensity,
+                agentId,
+                swarmId,
+                data: dataJson,
+                halfLife,
+            });
+            if (result.length === 0) {
+                return createErrorResponse(`Failed to create pheromone. Node ${nodeId} may not exist in the graph.`);
+            }
+            const pheromone = result[0];
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                action: cleanedStates > 0 ? 'transitioned' : 'created',
+                previousStatesRemoved: cleanedStates,
+                pheromone: {
+                    id: pheromone.id,
+                    projectId: pheromone.projectId,
+                    nodeId: pheromone.nodeId,
+                    type: pheromone.type,
+                    intensity: pheromone.intensity,
+                    agentId: pheromone.agentId,
+                    swarmId: pheromone.swarmId,
+                    timestamp: pheromone.timestamp,
+                    linkedToNode: pheromone.linkedToNode,
+                    halfLifeMs: halfLife,
+                    expiresIn: halfLife < 0 ? 'never' : `${Math.round(halfLife / 60000)} minutes`,
+                },
+            }));
+        }
+        catch (error) {
+            await debugLog('Swarm pheromone error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

package/dist/mcp/tools/swarm-sense.tool.js

@@ -0,0 +1,212 @@
+/**
+ * Swarm Sense Tool
+ * Query pheromones in the code graph for stigmergic coordination
+ */
+import { z } from 'zod';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+import { PHEROMONE_TYPES } from './swarm-constants.js';
+/**
+ * Neo4j query to sense pheromones with decay calculation
+ * Uses nodeId-based matching (self-healing) instead of [:MARKS] relationship
+ * This survives graph rebuilds since nodeIds are deterministic
+ */
+const SENSE_PHEROMONES_QUERY = `
+  // Match pheromones scoped to project, optionally filtering by type
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND ($types IS NULL OR size($types) = 0 OR p.type IN $types)
+    AND ($nodeIds IS NULL OR size($nodeIds) = 0 OR p.nodeId IN $nodeIds)
+    AND ($agentIds IS NULL OR size($agentIds) = 0 OR p.agentId IN $agentIds)
+    AND ($swarmId IS NULL OR p.swarmId = $swarmId)
+    AND ($excludeAgentId IS NULL OR p.agentId <> $excludeAgentId)
+
+  // Calculate current intensity with exponential decay
+  WITH p,
+    CASE
+      WHEN p.halfLife IS NULL OR p.halfLife <= 0 THEN p.intensity
+      ELSE p.intensity * exp(-0.693147 * (timestamp() - p.timestamp) / p.halfLife)
+    END AS currentIntensity
+
+  // Filter by minimum intensity
+  WHERE currentIntensity >= $minIntensity
+
+  // Find target by nodeId (self-healing - survives graph rebuilds)
+  OPTIONAL MATCH (target)
+  WHERE target.id = p.nodeId AND target.projectId = p.projectId
+
+  // Return pheromone data
+  RETURN
+    p.id AS id,
+    p.projectId AS projectId,
+    p.nodeId AS nodeId,
+    p.type AS type,
+    p.intensity AS originalIntensity,
+    currentIntensity,
+    p.agentId AS agentId,
+    p.swarmId AS swarmId,
+    p.timestamp AS timestamp,
+    p.data AS data,
+    p.halfLife AS halfLifeMs,
+    CASE WHEN target IS NOT NULL THEN labels(target)[0] ELSE null END AS targetType,
+    CASE WHEN target IS NOT NULL THEN target.name ELSE null END AS targetName,
+    CASE WHEN target IS NOT NULL THEN target.filePath ELSE null END AS targetFilePath
+
+  ORDER BY currentIntensity DESC, p.timestamp DESC
+  LIMIT toInteger($limit)
+`;
+/**
+ * Neo4j query to get pheromone summary statistics
+ */
+const PHEROMONE_STATS_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+  WITH p,
+    CASE
+      WHEN p.halfLife IS NULL OR p.halfLife <= 0 THEN p.intensity
+      ELSE p.intensity * exp(-0.693147 * (timestamp() - p.timestamp) / p.halfLife)
+    END AS currentIntensity
+  WHERE currentIntensity >= $minIntensity
+
+  RETURN
+    p.type AS type,
+    count(p) AS count,
+    avg(currentIntensity) AS avgIntensity,
+    collect(DISTINCT p.agentId) AS agents
+  ORDER BY count DESC
+`;
+/**
+ * Neo4j query to clean up fully decayed pheromones for a project
+ */
+const CLEANUP_DECAYED_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND p.halfLife IS NOT NULL
+    AND p.halfLife > 0
+    AND p.intensity * exp(-0.693147 * (timestamp() - p.timestamp) / p.halfLife) < 0.01
+  DETACH DELETE p
+  RETURN count(p) AS cleaned
+`;
+export const createSwarmSenseTool = (server) => {
+    server.registerTool(TOOL_NAMES.swarmSense, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmSense].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmSense].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            types: z
+                .array(z.enum(PHEROMONE_TYPES))
+                .optional()
+                .describe('Filter by pheromone types. If empty, returns all types. Options: exploring, modifying, claiming, completed, warning, blocked, proposal, needs_review'),
+            nodeIds: z.array(z.string()).optional().describe('Filter by specific node IDs. If empty, searches all nodes.'),
+            agentIds: z
+                .array(z.string())
+                .optional()
+                .describe('Filter by specific agent IDs. If empty, returns pheromones from all agents.'),
+            swarmId: z.string().optional().describe('Filter by swarm ID. If empty, returns pheromones from all swarms.'),
+            excludeAgentId: z
+                .string()
+                .optional()
+                .describe('Exclude pheromones from this agent ID (useful for seeing what OTHER agents are doing)'),
+            minIntensity: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .default(0.3)
+                .describe('Minimum effective intensity after decay (0.0-1.0, default: 0.3)'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .default(50)
+                .describe('Maximum number of pheromones to return (default: 50, max: 500)'),
+            includeStats: z.boolean().optional().default(false).describe('Include summary statistics by pheromone type'),
+            cleanup: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Run cleanup of fully decayed pheromones (intensity < 0.01)'),
+        },
+    }, async ({ projectId, types, nodeIds, agentIds, swarmId, excludeAgentId, minIntensity = 0.3, limit = 50, includeStats = false, cleanup = false, }) => {
+        const neo4jService = new Neo4jService();
+        // Resolve project ID
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            const result = {
+                pheromones: [],
+                projectId: resolvedProjectId,
+                query: {
+                    types: types ?? null,
+                    minIntensity,
+                    limit,
+                },
+            };
+            // Run cleanup if requested
+            if (cleanup) {
+                const cleanupResult = await neo4jService.run(CLEANUP_DECAYED_QUERY, { projectId: resolvedProjectId });
+                result.cleaned = cleanupResult[0]?.cleaned ?? 0;
+            }
+            // Query pheromones (ensure limit is integer for Neo4j LIMIT clause)
+            const pheromones = await neo4jService.run(SENSE_PHEROMONES_QUERY, {
+                projectId: resolvedProjectId,
+                types: types ?? null,
+                nodeIds: nodeIds ?? null,
+                agentIds: agentIds ?? null,
+                swarmId: swarmId ?? null,
+                excludeAgentId: excludeAgentId ?? null,
+                minIntensity,
+                limit: Math.floor(limit),
+            });
+            result.pheromones = pheromones.map((p) => {
+                // Convert Neo4j Integer to JS number
+                const ts = typeof p.timestamp === 'object' && p.timestamp?.toNumber ? p.timestamp.toNumber() : p.timestamp;
+                return {
+                    id: p.id,
+                    projectId: p.projectId,
+                    nodeId: p.nodeId,
+                    type: p.type,
+                    intensity: Math.round(p.currentIntensity * 1000) / 1000, // Round to 3 decimals
+                    originalIntensity: p.originalIntensity,
+                    agentId: p.agentId,
+                    swarmId: p.swarmId,
+                    timestamp: ts,
+                    age: ts ? `${Math.round((Date.now() - ts) / 1000)}s ago` : null,
+                    data: p.data ? JSON.parse(p.data) : null,
+                    target: p.targetType
+                        ? {
+                            type: p.targetType,
+                            name: p.targetName,
+                            filePath: p.targetFilePath,
+                        }
+                        : null,
+                };
+            });
+            // Include stats if requested
+            if (includeStats) {
+                const stats = await neo4jService.run(PHEROMONE_STATS_QUERY, { projectId: resolvedProjectId, minIntensity });
+                result.stats = stats.map((s) => ({
+                    type: s.type,
+                    count: typeof s.count === 'object' ? s.count.toNumber() : s.count,
+                    avgIntensity: Math.round(s.avgIntensity * 1000) / 1000,
+                    activeAgents: s.agents,
+                }));
+            }
+            return createSuccessResponse(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            await debugLog('Swarm sense error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

package/dist/storage/neo4j/neo4j.service.js

@@ -215,15 +215,19 @@ export const QUERIES = {
     // The previous query (WHERE startNode(r) IS NULL OR endNode(r) IS NULL) could never match anything
     // Get existing nodes (excluding files being reparsed) for edge target matching
     // Returns minimal info needed for edge detection: id, name, coreType, semanticType
+    // NOTE: Using property-based query instead of path traversal to avoid Cartesian explosion
+    // The old query `MATCH (sf:SourceFile)-[*]->(n)` caused OOM with large graphs
     GET_EXISTING_NODES_FOR_EDGE_DETECTION: `
-    MATCH (sf:SourceFile)-[*]->(n)
-    WHERE NOT sf.filePath IN $excludeFilePaths AND sf.projectId = $projectId
-    RETURN n.id AS id,
+    MATCH (n)
+    WHERE n.projectId = $projectId
+      AND n.filePath IS NOT NULL
+      AND NOT n.filePath IN $excludeFilePaths
+    RETURN DISTINCT n.id AS id,
            n.name AS name,
            n.coreType AS coreType,
            n.semanticType AS semanticType,
            labels(n) AS labels,
-           sf.filePath AS filePath
+           n.filePath AS filePath
   `,
     EXPLORE_ALL_CONNECTIONS: (maxDepth = MAX_TRAVERSAL_DEPTH, direction = 'BOTH', relationshipTypes) => {
         const safeMaxDepth = Math.min(Math.max(maxDepth, 1), MAX_TRAVERSAL_DEPTH);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-context",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "MCP server that builds code graphs to provide rich context to LLMs",
   "type": "module",
   "homepage": "https://github.com/drewdrewH/code-graph-context#readme",
@@ -30,7 +30,7 @@
   "license": "MIT",
   "main": "dist/mcp/mcp.server.js",
   "bin": {
-    "code-graph-context": "dist/mcp/mcp.server.js"
+    "code-graph-context": "dist/cli/cli.js"
   },
   "files": [
     "dist/**/*",