code-graph-context 2.6.2 → 2.8.0

package/README.md

@@ -345,7 +345,6 @@ Explicit task management with dependencies:
 
 | Tool | Purpose |
 |------|---------|
-| `swarm_orchestrate` | Decompose a task and spawn worker agents |
 | `swarm_post_task` | Add a task to the queue |
 | `swarm_get_tasks` | Query tasks with filters |
 | `swarm_claim_task` | Claim/start/release a task |
@@ -357,28 +356,20 @@ Explicit task management with dependencies:
 ### Example: Parallel Refactoring
 
 ```typescript
-// Orchestrator decomposes and creates tasks
-swarm_orchestrate({
+// Orchestrator decomposes the task and creates individual work items
+swarm_post_task({
   projectId: "backend",
-  task: "Rename getUserById to findUserById across the codebase",
-  maxAgents: 3
+  swarmId: "swarm_rename_user",
+  title: "Update UserService.findUserById",
+  description: "Rename getUserById to findUserById in UserService",
+  type: "refactor",
+  createdBy: "orchestrator"
 })
 
-// Returns a plan:
-{
-  swarmId: "swarm_abc123",
-  plan: {
-    totalTasks: 12,
-    parallelizable: 8,
-    sequential: 4,  // These have dependencies
-    tasks: [
-      { id: "task_1", title: "Update UserService.findUserById", status: "available" },
-      { id: "task_2", title: "Update UserController references", status: "blocked", depends: ["task_1"] },
-      ...
-    ]
-  },
-  workerInstructions: "..."  // Copy-paste to spawn workers
-}
+// Workers claim and execute tasks
+swarm_claim_task({ projectId: "backend", swarmId: "swarm_rename_user", agentId: "worker_1" })
+// ... do work ...
+swarm_complete_task({ taskId: "task_1", agentId: "worker_1", action: "complete", summary: "Renamed method" })
 ```
 
 ### Install the Swarm Skill
@@ -428,7 +419,6 @@ See [`skills/swarm/SKILL.md`](skills/swarm/SKILL.md) for the full documentation.
 | `stop_watch_project` | Stop file watching |
 | `list_watchers` | List active file watchers |
 | **Swarm** | |
-| `swarm_orchestrate` | Plan and spawn parallel agents |
 | `swarm_post_task` | Add task to the queue |
 | `swarm_get_tasks` | Query tasks |
 | `swarm_claim_task` | Claim/start/release tasks |
@@ -458,7 +448,7 @@ detect_dead_code → detect_duplicate_code → prioritize cleanup
 
 **Pattern 4: Multi-Agent Work**
 ```
-swarm_orchestrate → spawn workers → swarm_get_tasks(includeStats) → swarm_cleanup
+swarm_post_task → swarm_claim_task → swarm_complete_task → swarm_get_tasks(includeStats) → swarm_cleanup
 ```
 
 ### Multi-Project Support

package/dist/core/utils/graph-factory.js

@@ -3,7 +3,7 @@
  * Shared utilities for creating/converting graph nodes and edges
  */
 import crypto from 'crypto';
-import { CoreEdgeType, CORE_TYPESCRIPT_SCHEMA } from '../config/schema.js';
+import { CoreEdgeType, CORE_TYPESCRIPT_SCHEMA, } from '../config/schema.js';
 // ============================================
 // Node ID Generation
 // ============================================

package/dist/mcp/constants.js

@@ -38,7 +38,11 @@ export const TOOL_NAMES = {
     swarmClaimTask: 'swarm_claim_task',
     swarmCompleteTask: 'swarm_complete_task',
     swarmGetTasks: 'swarm_get_tasks',
-    swarmOrchestrate: 'swarm_orchestrate',
+    saveSessionBookmark: 'save_session_bookmark',
+    restoreSessionBookmark: 'restore_session_bookmark',
+    saveSessionNote: 'save_session_note',
+    recallSessionNotes: 'recall_session_notes',
+    cleanupSession: 'cleanup_session',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
@@ -205,9 +209,9 @@ Parameters:
     },
     [TOOL_NAMES.swarmPheromone]: {
         title: 'Swarm Pheromone',
-        description: `Mark a code node with a pheromone for coordination. Types: exploring (2min), modifying (10min), claiming (1hr), completed (24hr), warning (permanent), blocked (5min), proposal (1hr), needs_review (30min).
+        description: `Mark a code node with a pheromone for coordination. Types: exploring (2min), modifying (10min), claiming (1hr), completed (24hr), warning (permanent), blocked (5min), proposal (1hr), needs_review (30min), session_context (8hr).
 
-Workflow states (exploring/claiming/modifying/completed/blocked) are mutually exclusive per agent+node. Use remove:true to delete. Pheromones decay automatically.`,
+Workflow states (exploring/claiming/modifying/completed/blocked) are mutually exclusive per agent+node. Flag types (warning/proposal/needs_review/session_context) can coexist. Use remove:true to delete. Pheromones decay automatically.`,
     },
     [TOOL_NAMES.swarmSense]: {
         title: 'Swarm Sense',
@@ -255,11 +259,89 @@ Complete unblocks dependent tasks. Failed tasks can be retried if retryable=true
 
 Sort by: priority (default), created, updated. Add includeStats:true for aggregate counts.`,
     },
-    [TOOL_NAMES.swarmOrchestrate]: {
-        title: 'Swarm Orchestrate',
-        description: `Coordinate multiple agents for complex multi-file tasks. Analyzes codebase, decomposes into atomic tasks, spawns workers, monitors progress.
+    [TOOL_NAMES.saveSessionBookmark]: {
+        title: 'Save Session Bookmark',
+        description: `Save current session context as a bookmark for cross-session continuity.
 
-Use dryRun:true to preview plan. maxAgents controls parallelism (default: 3). Failed tasks auto-retry via pheromone decay.`,
+Records your working set (code node IDs), task context, findings, and next steps so a future session can resume exactly where you left off.
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- sessionId (required): Unique session/conversation ID for recovery
+- agentId (required): Your agent identifier
+- summary (required, min 10 chars): Brief description of current work state
+- workingSetNodeIds (required): Code node IDs you are focused on
+- taskContext (required): High-level task being worked on
+- findings: Key discoveries or decisions made so far
+- nextSteps: What to do next when resuming
+- metadata: Additional structured data
+
+Returns bookmarkId for use with restore_session_bookmark.`,
+    },
+    [TOOL_NAMES.restoreSessionBookmark]: {
+        title: 'Restore Session Bookmark',
+        description: `Restore a previously saved session bookmark to resume work.
+
+Retrieves the bookmark, fetches working set code nodes (with source), and returns any session notes. Use after conversation compaction or when resuming a task in a new session.
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- sessionId: Specific session to restore (latest bookmark if omitted)
+- agentId: Filter by agent ID (any agent if omitted)
+- includeCode (default: true): Include source code for working set nodes
+- snippetLength (default: 500): Max characters per code snippet
+
+Returns: bookmark data, working set nodes, session notes, and staleNodeIds (nodes no longer in graph after re-parse).`,
+    },
+    [TOOL_NAMES.saveSessionNote]: {
+        title: 'Save Session Note',
+        description: `Save an observation, decision, insight, or risk as a durable session note linked to code nodes.
+
+Notes survive session compaction and are recalled by restore_session_bookmark or recall_session_notes.
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- sessionId (required): Session/conversation identifier
+- agentId (required): Your agent identifier
+- topic (required, 3-100 chars): Short topic label
+- content (required, min 10 chars): Full observation text
+- category (required): architectural, bug, insight, decision, risk, or todo
+- severity (default: info): info, warning, or critical
+- aboutNodeIds: Code node IDs this note is about (creates [:ABOUT] links)
+- expiresInHours: Auto-expire after N hours (omit for permanent)
+
+Returns noteId, hasEmbedding (enables semantic recall), and expiresAt.`,
+    },
+    [TOOL_NAMES.recallSessionNotes]: {
+        title: 'Recall Session Notes',
+        description: `Search and retrieve saved session notes. Supports semantic vector search (when query provided) or filter-based search.
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- query: Natural language search — triggers semantic vector search when provided
+- category: Filter by architectural, bug, insight, decision, risk, todo
+- severity: Filter by info, warning, or critical
+- sessionId: Filter by session ID
+- agentId: Filter by agent ID
+- limit (default: 10, max: 50): Maximum notes to return
+- minSimilarity (default: 0.3): Minimum similarity for vector search
+
+Returns notes with topic, content, category, severity, relevance score (vector mode), and linked aboutNodes.`,
+    },
+    [TOOL_NAMES.cleanupSession]: {
+        title: 'Cleanup Session',
+        description: `Clean up expired session notes and old session bookmarks.
+
+Removes:
+- Expired SessionNote nodes (past expiresAt) and their edges
+- Old SessionBookmark nodes, keeping only the most recent N per session (default: 3)
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- keepBookmarks (default: 3): Number of most recent bookmarks to keep per session
+- dryRun (default: false): Preview what would be deleted without deleting
+
+Returns counts of deleted notes, bookmarks, and edges.`,
     },
 };
 // Default Values

package/dist/mcp/handlers/graph-generator.handler.js

@@ -74,6 +74,9 @@ export class GraphGeneratorHandler {
         await this.neo4jService.run(QUERIES.CREATE_PROJECT_ID_INDEX_EMBEDDED);
         await this.neo4jService.run(QUERIES.CREATE_PROJECT_ID_INDEX_SOURCEFILE);
         await this.neo4jService.run(QUERIES.CREATE_NORMALIZED_HASH_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_BOOKMARK_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTE_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTE_CATEGORY_INDEX);
         await debugLog('Project indexes created');
     }
     async importNodes(nodes, batchSize) {
@@ -180,6 +183,7 @@ export class GraphGeneratorHandler {
     async createVectorIndexes() {
         console.error('Creating vector indexes...');
         await this.neo4jService.run(QUERIES.CREATE_EMBEDDED_VECTOR_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTES_VECTOR_INDEX);
         await debugLog('Vector indexes created');
     }
     flattenProperties(properties) {

package/dist/mcp/mcp.server.js

@@ -24,8 +24,8 @@ import { registerAllTools } from './tools/index.js';
 import { debugLog } from './utils.js';
 // Track server state for debugging
 let serverStartTime;
-let toolCallCount = 0;
-let lastToolCall = null;
+const toolCallCount = 0;
+const lastToolCall = null;
 /**
  * Log memory usage and server stats
  */

package/dist/mcp/service-init.js

@@ -4,7 +4,7 @@
  */
 import fs from 'fs/promises';
 import { join } from 'path';
-import { ensureNeo4jRunning, isDockerInstalled, isDockerRunning, } from '../cli/neo4j-docker.js';
+import { ensureNeo4jRunning, isDockerInstalled, isDockerRunning } from '../cli/neo4j-docker.js';
 import { Neo4jService, QUERIES } from '../storage/neo4j/neo4j.service.js';
 import { FILE_PATHS, LOG_CONFIG } from './constants.js';
 import { initializeNaturalLanguageService } from './tools/natural-language-to-cypher.tool.js';

package/dist/mcp/services/watch-manager.js

@@ -47,7 +47,7 @@ class WatchManager {
             // This is expected if the client doesn't support logging capability
             debugLog('sendNotification: MCP message failed (expected if client lacks logging)', {
                 type: notification.type,
-                error: String(error)
+                error: String(error),
             });
         });
     }
@@ -62,7 +62,8 @@ class WatchManager {
         }
         // Enforce maximum watcher limit
         if (this.watchers.size >= WATCH.maxWatchers) {
-            throw new Error(`Maximum watcher limit (${WATCH.maxWatchers}) reached. ` + `Stop an existing watcher before starting a new one.`);
+            throw new Error(`Maximum watcher limit (${WATCH.maxWatchers}) reached. ` +
+                `Stop an existing watcher before starting a new one.`);
         }
         const fullConfig = {
             projectPath: config.projectPath,
@@ -138,7 +139,13 @@ class WatchManager {
      * Handle a file system event
      */
     handleFileEvent(state, type, filePath) {
-        debugLog('handleFileEvent START', { type, filePath, projectId: state.projectId, status: state.status, isStopping: state.isStopping });
+        debugLog('handleFileEvent START', {
+            type,
+            filePath,
+            projectId: state.projectId,
+            status: state.status,
+            isStopping: state.isStopping,
+        });
         // Ignore events if watcher is stopping or not active
         if (state.isStopping || state.status !== 'active') {
             debugLog('Ignoring event - watcher not active or stopping', {
@@ -194,12 +201,12 @@ class WatchManager {
             projectId: state.projectId,
             isProcessing: state.isProcessing,
             pendingCount: state.pendingEvents.length,
-            isStopping: state.isStopping
+            isStopping: state.isStopping,
         });
         // Don't process if already processing, no events, or watcher is stopping
         if (state.isProcessing || state.pendingEvents.length === 0 || state.isStopping) {
             await debugLog('processEvents: early return', {
-                reason: state.isProcessing ? 'already processing' : state.pendingEvents.length === 0 ? 'no events' : 'stopping'
+                reason: state.isProcessing ? 'already processing' : state.pendingEvents.length === 0 ? 'no events' : 'stopping',
             });
             return;
         }
@@ -226,12 +233,12 @@ class WatchManager {
             }
             await debugLog('processEvents: calling incrementalParseHandler', {
                 projectPath: state.projectPath,
-                projectId: state.projectId
+                projectId: state.projectId,
             });
             const result = await this.incrementalParseHandler(state.projectPath, state.projectId, state.tsconfigPath);
             await debugLog('processEvents: incrementalParseHandler returned', {
                 nodesUpdated: result.nodesUpdated,
-                edgesUpdated: result.edgesUpdated
+                edgesUpdated: result.edgesUpdated,
             });
             state.lastUpdateTime = new Date();
             const elapsedMs = Date.now() - startTime;
@@ -285,7 +292,10 @@ class WatchManager {
             debugLog('handleWatcherError: cleanup succeeded', { projectId: state.projectId });
         })
             .catch((cleanupError) => {
-            debugLog('handleWatcherError: cleanup failed', { projectId: state.projectId, cleanupError: String(cleanupError) });
+            debugLog('handleWatcherError: cleanup failed', {
+                projectId: state.projectId,
+                cleanupError: String(cleanupError),
+            });
             console.error(`[WatchManager] Failed to cleanup errored watcher ${state.projectId}:`, cleanupError);
         });
     }
@@ -306,7 +316,7 @@ class WatchManager {
             debugLog('syncMissedChanges: completed', {
                 projectId: state.projectId,
                 nodesUpdated: result.nodesUpdated,
-                edgesUpdated: result.edgesUpdated
+                edgesUpdated: result.edgesUpdated,
             });
             if (result.nodesUpdated > 0 || result.edgesUpdated > 0) {
                 console.error(`[WatchManager] Synced missed changes for ${state.projectId}: ` +
@@ -314,7 +324,11 @@ class WatchManager {
             }
         })
             .catch((error) => {
-            debugLog('syncMissedChanges: error', { projectId: state.projectId, error: String(error), isStopping: state.isStopping });
+            debugLog('syncMissedChanges: error', {
+                projectId: state.projectId,
+                error: String(error),
+                isStopping: state.isStopping,
+            });
             // Only log if watcher hasn't been stopped
             if (!state.isStopping) {
                 console.error(`[WatchManager] Failed to sync missed changes for ${state.projectId}:`, error);

package/dist/mcp/tools/index.js

@@ -12,13 +12,15 @@ import { createListWatchersTool } from './list-watchers.tool.js';
 import { createNaturalLanguageToCypherTool } from './natural-language-to-cypher.tool.js';
 import { createParseTypescriptProjectTool } from './parse-typescript-project.tool.js';
 import { createSearchCodebaseTool } from './search-codebase.tool.js';
+import { createRestoreSessionBookmarkTool, createSaveSessionBookmarkTool } from './session-bookmark.tool.js';
+import { createCleanupSessionTool } from './session-cleanup.tool.js';
+import { createRecallSessionNotesTool, createSaveSessionNoteTool } from './session-note.tool.js';
 import { createStartWatchProjectTool } from './start-watch-project.tool.js';
 import { createStopWatchProjectTool } from './stop-watch-project.tool.js';
 import { createSwarmClaimTaskTool } from './swarm-claim-task.tool.js';
 import { createSwarmCleanupTool } from './swarm-cleanup.tool.js';
 import { createSwarmCompleteTaskTool } from './swarm-complete-task.tool.js';
 import { createSwarmGetTasksTool } from './swarm-get-tasks.tool.js';
-import { createSwarmOrchestrateTool } from './swarm-orchestrate.tool.js';
 import { createSwarmPheromoneTool } from './swarm-pheromone.tool.js';
 import { createSwarmPostTaskTool } from './swarm-post-task.tool.js';
 import { createSwarmSenseTool } from './swarm-sense.tool.js';
@@ -71,6 +73,12 @@ export const registerAllTools = (server) => {
     createSwarmClaimTaskTool(server);
     createSwarmCompleteTaskTool(server);
     createSwarmGetTasksTool(server);
-    // Register swarm orchestration tool (meta-tool for coordinating multi-agent work)
-    createSwarmOrchestrateTool(server);
+    // Register session bookmark tools (cross-session context continuity)
+    createSaveSessionBookmarkTool(server);
+    createRestoreSessionBookmarkTool(server);
+    // Register session note tools (durable observations and decisions)
+    createSaveSessionNoteTool(server);
+    createRecallSessionNotesTool(server);
+    // Register session cleanup tool
+    createCleanupSessionTool(server);
 };

package/dist/mcp/tools/parse-typescript-project.tool.js

@@ -90,8 +90,8 @@ export const createParseTypescriptProjectTool = (server) => {
                 .optional()
                 .default('auto')
                 .describe('When to use streaming import: auto (>100 files), always, or never'),
-            async: z
-                .coerce.boolean()
+            async: z.coerce
+                .boolean()
                 .optional()
                 .default(true)
                 .describe('Run parsing in background and return job ID immediately. Use check_parse_status to monitor.'),
@@ -224,7 +224,8 @@ export const createParseTypescriptProjectTool = (server) => {
                 });
             const discoveredFiles = await parser.discoverSourceFiles();
             const totalFiles = discoveredFiles.length;
-            const shouldUseStreaming = useStreaming === 'always' || (useStreaming === 'auto' && totalFiles > PARSING.streamingThreshold && chunkSize > 0);
+            const shouldUseStreaming = useStreaming === 'always' ||
+                (useStreaming === 'auto' && totalFiles > PARSING.streamingThreshold && chunkSize > 0);
             console.error(`📊 Project has ${totalFiles} files. Streaming: ${shouldUseStreaming ? 'enabled' : 'disabled'}`);
             if (shouldUseStreaming && clearExisting !== false) {
                 // Use streaming import for large projects