ai-mind-map 1.6.2 → 1.7.0

package/dist/index.js

@@ -1,2 +1,1397 @@
-export {};
+#!/usr/bin/env node
+/**
+ * AI Mind Map — MCP Server Entry Point
+ *
+ * Creates the MCP server with stdio transport, registers all tools,
+ * initialises ALL real subsystems (knowledge graph, change tracker,
+ * persistent memory, context engine), and handles graceful shutdown.
+ *
+ * Usage:
+ *   ai-mind-map [--project-root <path>] [--db-path <path>] [--log-level debug|info|warn|error]
+ */
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import Database from 'better-sqlite3';
+import { loadConfig, parseCliArgs } from './config.js';
+// ── Knowledge Graph ───────────────────────────────────────────
+import { KnowledgeGraph } from './knowledge-graph/graph.js';
+// Note: parser.ts exports functions (parseFile, parseFiles, etc.), not a class
+import { Indexer } from './knowledge-graph/indexer.js';
+import { PageRankEngine } from './knowledge-graph/pagerank.js';
+// ── Change Tracker ────────────────────────────────────────────
+import { FileWatcher } from './change-tracker/watcher.js';
+import { DiffEngine } from './change-tracker/diff-engine.js';
+import { ChangeLog } from './change-tracker/change-log.js';
+// ── Memory ────────────────────────────────────────────────────
+import { SessionMemory } from './memory/session-memory.js';
+import { PersistentMemory } from './memory/persistent-memory.js';
+import { DecisionLog } from './memory/decision-log.js';
+import { syncSharedContext } from './memory/shared-sync.js';
+// ── Context Engine ────────────────────────────────────────────
+// compressor.ts exports functions: compress, detectContentType
+import { compress as compressContent } from './context/compressor.js';
+// progressive-disclosure.ts exports function: buildContextPackage
+import { buildContextPackage } from './context/progressive-disclosure.js';
+import { estimateTokens } from './utils/token-counter.js';
+// ── Tools ─────────────────────────────────────────────────────
+import { registerGraphTools } from './tools/graph-tools.js';
+import { registerChangeTools } from './tools/change-tools.js';
+import { registerMemoryTools } from './tools/memory-tools.js';
+import { registerContextTools } from './tools/context-tools.js';
+import { registerDebugTools } from './tools/debug-tools.js';
+import { registerFlowTools } from './tools/flow-tools.js';
+import { registerSnapshotTools } from './tools/snapshot-tools.js';
+import { registerSmartTools } from './tools/smart-tools.js';
+import { registerEvolvingTools } from './tools/evolving-tools.js';
+import { registerAdvancedTools } from './tools/advanced-tools.js';
+import { registerSemanticTools } from './tools/semantic-tools.js';
+import { SemanticSearchEngine } from './knowledge-graph/semantic-search.js';
+import { ChangelogEngine } from './knowledge-graph/changelog.js';
+import { registerSessionTools } from './tools/session-tools.js';
+import { registerDigestTools } from './tools/digest-tools.js';
+// ============================================================
+// Logger — writes to stderr so MCP stdio is uncontaminated
+// ============================================================
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+let currentLogLevel = LOG_LEVELS.info;
+function setLogLevel(level) {
+    currentLogLevel = LOG_LEVELS[level];
+}
+function log(level, message, ...extra) {
+    if (LOG_LEVELS[level] < currentLogLevel)
+        return;
+    const ts = new Date().toISOString();
+    const prefix = `[${ts}] [${level.toUpperCase()}]`;
+    if (extra.length > 0) {
+        process.stderr.write(`${prefix} ${message} ${JSON.stringify(extra)}\n`);
+    }
+    else {
+        process.stderr.write(`${prefix} ${message}\n`);
+    }
+}
+// ============================================================
+// Adapters — Bridge real implementations to tool interfaces
+// ============================================================
+/**
+ * Creates an adapter that satisfies IKnowledgeGraph from the real
+ * KnowledgeGraph and PageRankEngine classes.
+ *
+ * Key API mappings:
+ * - graph.search(query, limit) — FTS5 search, no type filter param
+ * - graph.getProjectOverview() — returns Map<string, GraphNode[]>, no args
+ * - graph.findCallers(nodeId) / graph.findCallees(nodeId) — single nodeId arg
+ * - graph.getNodesByName(name) — returns GraphNode[]
+ * - graph.getFileStructure(filePath) — returns GraphNode[]
+ */
+function createGraphAdapter(graph, pagerank) {
+    return {
+        search: (query, type, limit) => {
+            const maxResults = limit ?? 20;
+            let results = graph.search(query, maxResults);
+            // Expand with learned search aliases
+            try {
+                const aliases = graph.getLearnedSearchAliases();
+                const lowerQuery = query.toLowerCase();
+                for (const alias of aliases) {
+                    if (alias.term.toLowerCase() === lowerQuery) {
+                        for (const alt of alias.aliases) {
+                            if (results.length >= maxResults)
+                                break;
+                            const aliasResults = graph.search(alt, Math.max(3, maxResults - results.length));
+                            const existingIds = new Set(results.map(r => r.id));
+                            for (const r of aliasResults) {
+                                if (!existingIds.has(r.id) && results.length < maxResults) {
+                                    results.push(r);
+                                    existingIds.add(r.id);
+                                }
+                            }
+                        }
+                        // Touch the alias to track usage
+                        try {
+                            graph.touchLearnedRule(alias.id);
+                        }
+                        catch { }
+                        break;
+                    }
+                }
+            }
+            catch {
+                // Learned rules table might not exist
+            }
+            if (type) {
+                return results.filter((n) => n.type === type);
+            }
+            return results;
+        },
+        getStructure: (depth) => {
+            // graph.getProjectOverview() returns Map<string, GraphNode[]>
+            // We convert it to the shape expected by IKnowledgeGraph.getStructure
+            const overview = graph.getProjectOverview();
+            const files = [];
+            for (const [filePath, nodes] of overview) {
+                files.push({
+                    path: filePath,
+                    symbols: nodes.map(n => ({
+                        name: n.name,
+                        type: n.type,
+                        signature: n.signature,
+                    })),
+                });
+            }
+            // depth is accepted but getProjectOverview doesn't take a depth arg;
+            // we can slice results if needed, but return all for now.
+            return { files };
+        },
+        traceDependencies: (symbolName, direction, depth) => {
+            const nodes = graph.getNodesByName(symbolName);
+            if (nodes.length === 0) {
+                return { root: symbolName, direction, depth, nodes: [], edges: [] };
+            }
+            const rootNode = nodes[0];
+            let traced = [];
+            // findCallers(nodeId) and findCallees(nodeId) each take a single string arg
+            if (direction === 'callers' || direction === 'both') {
+                traced = traced.concat(graph.findCallers(rootNode.id));
+            }
+            if (direction === 'callees' || direction === 'both') {
+                traced = traced.concat(graph.findCallees(rootNode.id));
+            }
+            // Deduplicate
+            const seen = new Set();
+            const unique = traced.filter(n => {
+                if (seen.has(n.id))
+                    return false;
+                seen.add(n.id);
+                return true;
+            });
+            // Collect relevant edges
+            const edgeSet = [];
+            for (const n of unique) {
+                const outEdges = graph.getOutEdges(n.id);
+                const inEdges = graph.getInEdges(n.id);
+                edgeSet.push(...outEdges, ...inEdges);
+            }
+            return {
+                root: symbolName,
+                direction,
+                depth,
+                nodes: unique,
+                edges: edgeSet,
+            };
+        },
+        getSignature: (symbolName, filePath) => {
+            const nodes = graph.getNodesByName(symbolName);
+            let match;
+            if (filePath) {
+                match = nodes.find((n) => n.filePath === filePath);
+            }
+            else {
+                match = nodes[0];
+            }
+            if (!match)
+                return null;
+            // Return the shape expected by IKnowledgeGraph.getSignature
+            return {
+                node: match,
+                parameters: match.parameters,
+                returnType: match.returnType,
+                docComment: match.docComment,
+            };
+        },
+        findReferences: (symbolName) => {
+            const nodes = graph.getNodesByName(symbolName);
+            if (nodes.length === 0) {
+                return { symbol: symbolName, references: [] };
+            }
+            // Find all callers of the first matching node as "references"
+            const callers = graph.findCallers(nodes[0].id);
+            return {
+                symbol: symbolName,
+                references: callers.map((n) => ({
+                    filePath: n.filePath,
+                    line: n.startLine,
+                    context: n.signature,
+                })),
+            };
+        },
+        getFileMap: (filePath) => {
+            const nodes = graph.getFileStructure(filePath);
+            if (!nodes || nodes.length === 0)
+                return null;
+            return {
+                filePath,
+                symbols: nodes
+                    .filter(n => n.type !== 'file')
+                    .map(n => ({
+                    name: n.name,
+                    type: n.type,
+                    signature: n.signature,
+                    startLine: n.startLine,
+                    endLine: n.endLine,
+                    visibility: n.visibility,
+                    isExported: n.isExported,
+                })),
+            };
+        },
+    };
+}
+/**
+ * Creates an adapter that satisfies IChangeTracker from the real
+ * DiffEngine and ChangeLog classes.
+ *
+ * Key API mappings:
+ * - changeLog.getLatestSession() — returns ChangeSession | null
+ * - changeLog.queryChanges(options) — options has `since` (timestamp), not `afterTimestamp`
+ * - changeLog.generateSessionSummary(sessionId) — returns string
+ * - changeLog.recordChange(change) — records a FileChange
+ */
+function createChangeAdapter(diffEngine, changeLog, graph) {
+    return {
+        getChanges: (since) => {
+            try {
+                const latestSession = changeLog.getLatestSession();
+                const sinceTimestamp = since === 'last_session'
+                    ? (latestSession?.endedAt ?? Date.now() - 86400000)
+                    : since === 'today'
+                        ? new Date().setHours(0, 0, 0, 0)
+                        : since === 'this_week'
+                            ? Date.now() - 7 * 86400000
+                            : new Date(since).getTime();
+                // ChangeLog.queryChanges uses ChangeQueryOptions with `since` field (timestamp)
+                const changes = changeLog.queryChanges({
+                    since: sinceTimestamp,
+                });
+                return {
+                    since,
+                    resolvedTimestamp: sinceTimestamp,
+                    changes,
+                    totalFilesChanged: new Set(changes.map(c => c.filePath)).size,
+                    totalLinesAdded: changes.reduce((sum, c) => sum + c.linesAdded, 0),
+                    totalLinesRemoved: changes.reduce((sum, c) => sum + c.linesRemoved, 0),
+                    summary: changes.length > 0
+                        ? changes.map(c => `- ${c.filePath}: ${c.summary}`).join('\n')
+                        : 'No changes found since the specified time.',
+                };
+            }
+            catch {
+                return {
+                    since,
+                    resolvedTimestamp: Date.now(),
+                    changes: [],
+                    totalFilesChanged: 0,
+                    totalLinesAdded: 0,
+                    totalLinesRemoved: 0,
+                    summary: 'Unable to retrieve changes.',
+                };
+            }
+        },
+        getSessionDiff: () => {
+            try {
+                const latestSession = changeLog.getLatestSession();
+                if (!latestSession) {
+                    return {
+                        previousSession: null,
+                        changes: [],
+                        affectedSymbols: [],
+                        summary: 'No previous session found.',
+                    };
+                }
+                const changes = changeLog.queryChanges({
+                    since: latestSession.endedAt ?? latestSession.startedAt,
+                });
+                const symbols = changes.flatMap(c => c.symbolsAffected);
+                return {
+                    previousSession: latestSession,
+                    changes,
+                    affectedSymbols: [...new Set(symbols)],
+                    summary: changeLog.generateSessionSummary(latestSession.sessionId),
+                };
+            }
+            catch {
+                return {
+                    previousSession: null,
+                    changes: [],
+                    affectedSymbols: [],
+                    summary: 'Unable to compute session diff.',
+                };
+            }
+        },
+        analyseImpact: (params) => {
+            const target = params.filePath ?? params.symbolName ?? 'unknown';
+            // Try to find the node and compute blast radius
+            let directlyAffected = [];
+            let transitivelyAffected = [];
+            let riskLevel = 'low';
+            try {
+                if (params.symbolName) {
+                    const nodes = graph.getNodesByName(params.symbolName);
+                    if (nodes.length > 0) {
+                        const rootNode = nodes[0];
+                        const callers = graph.findCallers(rootNode.id);
+                        directlyAffected = callers.map(n => ({
+                            node: n,
+                            relationship: 'calls',
+                        }));
+                        const blastNodes = graph.blastRadius(rootNode.id, 3);
+                        transitivelyAffected = blastNodes.map((n, idx) => ({
+                            node: n,
+                            depth: Math.min(idx + 1, 3),
+                        }));
+                        const total = directlyAffected.length + transitivelyAffected.length;
+                        riskLevel = total > 20 ? 'high' : total > 5 ? 'medium' : 'low';
+                    }
+                }
+                else if (params.filePath) {
+                    const fileNodes = graph.getFileStructure(params.filePath);
+                    for (const node of fileNodes) {
+                        if (node.type === 'file')
+                            continue;
+                        const callers = graph.findCallers(node.id);
+                        for (const caller of callers) {
+                            directlyAffected.push({ node: caller, relationship: 'calls' });
+                        }
+                    }
+                    riskLevel = directlyAffected.length > 10 ? 'high'
+                        : directlyAffected.length > 3 ? 'medium' : 'low';
+                }
+            }
+            catch {
+                // Fall through with empty arrays
+            }
+            return {
+                target,
+                directlyAffected,
+                transitivelyAffected,
+                riskLevel,
+                summary: directlyAffected.length > 0
+                    ? `${target}: ${directlyAffected.length} directly affected, ${transitivelyAffected.length} transitively affected. Risk: ${riskLevel}.`
+                    : `${target}: No dependents found. Use mindmap_trace_dependencies for full dependency chain.`,
+            };
+        },
+    };
+}
+/**
+ * Creates an adapter that satisfies IMemoryStore from PersistentMemory,
+ * DecisionLog, and SessionMemory.
+ *
+ * Key API mappings:
+ * - persistentMemory.queryMemories(query) — query uses MemoryQuery shape
+ * - persistentMemory.createMemory(input) — input is CreateMemoryInput
+ * - persistentMemory.getStats() — returns MemoryStats
+ * - decisionLog.queryDecisions(query) — query uses DecisionQuery
+ * - decisionLog.createDecision(input) — returns { decision, conflicts }
+ * - decisionLog.getActiveDecisions() — returns Decision[]
+ * - sessionMemory.listRecentSessions(limit) — returns SessionListItem[]
+ */
+function createMemoryAdapter(persistentMemory, decisionLog, sessionMemory) {
+    return {
+        recall: (query, category, limit) => {
+            return persistentMemory.queryMemories({
+                text: query,
+                categories: category ? [category] : undefined,
+                limit: limit ?? 10,
+            });
+        },
+        remember: (params) => {
+            return persistentMemory.createMemory({
+                category: params.category,
+                content: params.content,
+                importance: params.importance,
+                tags: params.tags,
+                relatedFiles: params.relatedFiles,
+                sessionId: params.sessionId,
+                source: params.source,
+            });
+        },
+        getDecisions: (params) => {
+            if (params.query) {
+                // Use DecisionLog.queryDecisions with text search
+                const results = decisionLog.queryDecisions({
+                    text: params.query,
+                    status: params.status === 'all' ? undefined : (params.status ?? 'active'),
+                });
+                return results;
+            }
+            if (!params.status || params.status === 'active') {
+                return decisionLog.getActiveDecisions();
+            }
+            // 'all' — query with no filters
+            return decisionLog.queryDecisions({});
+        },
+        decide: (params) => {
+            // DecisionLog.createDecision returns { decision, conflicts }
+            const result = decisionLog.createDecision({
+                title: params.title,
+                description: params.description,
+                rationale: params.rationale,
+                alternatives: params.alternatives,
+                consequences: params.consequences,
+                relatedFiles: params.relatedFiles,
+                tags: params.tags,
+                decidedBy: params.decidedBy,
+            });
+            return result.decision;
+        },
+        getSessionSummaries: (count) => {
+            // sessionMemory.listRecentSessions returns SessionListItem[]
+            // We need to return SessionSummary[], so we adapt
+            const sessions = sessionMemory.listRecentSessions(count);
+            return sessions.map(s => {
+                // Try to get full session details if available
+                const full = sessionMemory.getSession(s.sessionId);
+                if (full) {
+                    return {
+                        sessionId: full.sessionId,
+                        startedAt: full.startedAt,
+                        endedAt: full.endedAt,
+                        tasksCompleted: full.tasksCompleted,
+                        filesModified: full.filesModified,
+                        decisionseMade: full.decisionseMade,
+                        memoriesCreated: full.memoriesCreated,
+                        tokensSaved: full.tokensSaved,
+                        summary: full.summary,
+                    };
+                }
+                // Fallback: return minimal SessionSummary from SessionListItem
+                return {
+                    sessionId: s.sessionId,
+                    startedAt: s.startedAt,
+                    endedAt: s.endedAt ?? Date.now(),
+                    tasksCompleted: [],
+                    filesModified: [],
+                    decisionseMade: [],
+                    memoriesCreated: 0,
+                    tokensSaved: 0,
+                    summary: s.summary,
+                };
+            });
+        },
+    };
+}
+/**
+ * Creates an adapter that satisfies ISessionProvider.
+ * sessionMemory.getCurrentSessionId() returns string | null.
+ * The interface expects string, so we provide a fallback.
+ */
+function createSessionAdapter(sessionMemory) {
+    return {
+        currentSessionId: () => {
+            return sessionMemory.getCurrentSessionId() ?? 'no-session';
+        },
+    };
+}
+/**
+ * Creates an adapter that satisfies IContextEngine.
+ *
+ * Key API mappings:
+ * - compress(text, level, contentType) — module-level function from compressor.ts
+ * - buildContextPackage(...) — module-level function from progressive-disclosure.ts
+ */
+function createContextAdapter(graph, persistentMemory, decisionLog, changeLog, config) {
+    return {
+        getContext: (params) => {
+            try {
+                // Build ProjectInfo for Tier 1
+                const overview = graph.getProjectOverview();
+                const stats = graph.getStats();
+                const directoryTree = Array.from(overview.keys())
+                    .slice(0, 20)
+                    .map(f => `  ${f}`)
+                    .join('\n');
+                const projectInfo = {
+                    name: path.basename(config.projectRoot),
+                    description: params.taskDescription,
+                    techStack: Object.keys(stats.languageBreakdown),
+                    directoryTree,
+                    conventions: [],
+                    currentTask: params.taskDescription,
+                };
+                // Build Tier 2 data
+                const tier2Data = {};
+                if (params.includeMemories) {
+                    tier2Data.memories = persistentMemory.queryMemories({
+                        text: params.taskDescription,
+                        limit: 5,
+                    });
+                    tier2Data.decisions = decisionLog.getActiveDecisions();
+                }
+                if (params.includeChanges) {
+                    tier2Data.recentChanges = changeLog.queryChanges({
+                        limit: 10,
+                    });
+                }
+                // Search graph for relevant nodes
+                const graphNodes = graph.search(params.taskDescription, 10);
+                if (graphNodes.length > 0) {
+                    tier2Data.graphNodes = graphNodes;
+                }
+                // Build context package
+                const pkg = buildContextPackage(projectInfo, tier2Data, {}, // Tier 3 data — empty for initial load
+                config.tokenBudgets, params.taskDescription);
+                return pkg;
+            }
+            catch {
+                return {
+                    tier1: 'Project context loading failed.',
+                    tier2: '',
+                    tier3: '',
+                    totalTokens: 10,
+                    tokensSaved: 0,
+                    breakdown: [],
+                };
+            }
+        },
+        compress: (params) => {
+            // compress(text, level, contentType?) from compressor.ts
+            // Returns CompressionResult { compressed, originalTokens, compressedTokens, ratio, contentType, level }
+            const result = compressContent(params.content, params.level, params.contentType);
+            return {
+                original: params.content,
+                compressed: result.compressed,
+                originalTokens: result.originalTokens,
+                compressedTokens: result.compressedTokens,
+                ratio: result.ratio,
+                contentType: result.contentType,
+            };
+        },
+    };
+}
+/**
+ * Creates an adapter that satisfies IIndexer.
+ *
+ * Key API mappings:
+ * - indexer.fullIndex(onProgress?) — returns Promise<IndexStats>
+ *   IndexStats has: filesScanned, filesParsed, filesSkipped, filesDeleted,
+ *                   nodesCreated, edgesCreated, parseErrors, durationMs, languages
+ * - graph.getStats() — returns { totalNodes, totalEdges, totalFiles, nodesByType, edgesByType, languageBreakdown }
+ * - persistentMemory.getStats() — returns MemoryStats
+ * - changeLog.getStats(topN?) — returns ChangeLogStats
+ */
+function createIndexerAdapter(indexer, graph, persistentMemory, decisionLog, changeLog, config, watcher) {
+    return {
+        reindex: async () => {
+            const startTime = Date.now();
+            try {
+                const result = await indexer.fullIndex();
+                return {
+                    filesScanned: result.filesScanned,
+                    filesIndexed: result.filesParsed,
+                    nodesCreated: result.nodesCreated,
+                    edgesCreated: result.edgesCreated,
+                    durationMs: result.durationMs,
+                    errors: result.parseErrors > 0
+                        ? [`${result.parseErrors} parse errors encountered`]
+                        : [],
+                };
+            }
+            catch (err) {
+                return {
+                    filesScanned: 0,
+                    filesIndexed: 0,
+                    nodesCreated: 0,
+                    edgesCreated: 0,
+                    durationMs: Date.now() - startTime,
+                    errors: [err instanceof Error ? err.message : String(err)],
+                };
+            }
+        },
+        reindexProject: async (projectPath) => {
+            const startTime = Date.now();
+            const resolvedPath = path.resolve(projectPath);
+            try {
+                // Re-target the indexer to the new project
+                indexer.setProjectRoot(resolvedPath);
+                log('info', `📁 Re-targeted to project: ${resolvedPath}`);
+                // Also watch the new project directory for changes
+                if (watcher) {
+                    watcher.addRoot(resolvedPath);
+                    log('info', `👁️ File watcher now also watching: ${resolvedPath}`);
+                }
+                // Run full index on the new project (don't clear — multi-project)
+                const result = await indexer.fullIndex();
+                return {
+                    filesScanned: result.filesScanned,
+                    filesIndexed: result.filesParsed,
+                    nodesCreated: result.nodesCreated,
+                    edgesCreated: result.edgesCreated,
+                    durationMs: result.durationMs,
+                    errors: result.parseErrors > 0
+                        ? [`${result.parseErrors} parse errors encountered`]
+                        : [],
+                    projectRoot: resolvedPath,
+                };
+            }
+            catch (err) {
+                return {
+                    filesScanned: 0,
+                    filesIndexed: 0,
+                    nodesCreated: 0,
+                    edgesCreated: 0,
+                    durationMs: Date.now() - startTime,
+                    errors: [err instanceof Error ? err.message : String(err)],
+                    projectRoot: resolvedPath,
+                };
+            }
+        },
+        getStats: () => {
+            let dbSize = 0;
+            try {
+                if (existsSync(config.dbPath)) {
+                    dbSize = statSync(config.dbPath).size;
+                }
+            }
+            catch {
+                // ignore
+            }
+            const graphStats = graph.getStats();
+            const memoryStats = persistentMemory.getStats();
+            const changeStats = changeLog.getStats();
+            // DecisionLog doesn't have a count() method; use queryDecisions
+            const allDecisions = decisionLog.queryDecisions({});
+            return {
+                projectRoot: config.projectRoot,
+                indexedFiles: graphStats.totalFiles,
+                totalNodes: graphStats.totalNodes,
+                totalEdges: graphStats.totalEdges,
+                totalMemories: memoryStats.totalMemories,
+                totalDecisions: allDecisions.length,
+                totalChangesTracked: changeStats.totalChanges,
+                lastIndexedAt: null, // Graph doesn't track this directly
+                lastChangeAt: null,
+                dbSizeBytes: dbSize,
+                languageBreakdown: graphStats.languageBreakdown,
+                tokensSavedEstimate: graphStats.totalNodes * 500,
+            };
+        },
+    };
+}
+// ============================================================
+// Ensure database directory exists
+// ============================================================
+function ensureDbDirectory(dbPath) {
+    const dir = path.dirname(dbPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        log('info', `Created database directory: ${dir}`);
+    }
+}
+// ============================================================
+// Session Token Tracker
+// ============================================================
+/**
+ * Tracks cumulative token usage across all tool calls in a session.
+ * Every tool response is enriched with `_sessionTokens` metadata
+ * so AI agents always know their token footprint.
+ */
+class SessionTokenTracker {
+    totalToolCalls = 0;
+    totalOutputTokens = 0;
+    totalInputTokens = 0;
+    totalTokensSaved = 0;
+    startTime = Date.now();
+    /** Record a tool call with its input and output token counts. */
+    record(inputTokens, outputTokens, tokensSaved) {
+        this.totalToolCalls++;
+        this.totalInputTokens += inputTokens;
+        this.totalOutputTokens += outputTokens;
+        this.totalTokensSaved += tokensSaved;
+    }
+    /** Get a summary object to include in every tool response. */
+    getSummary() {
+        return {
+            totalToolCalls: this.totalToolCalls,
+            totalInputTokens: this.totalInputTokens,
+            totalOutputTokens: this.totalOutputTokens,
+            totalTokensSaved: this.totalTokensSaved,
+            sessionDurationMs: Date.now() - this.startTime,
+        };
+    }
+}
+/**
+ * Directories that should NEVER be indexed — IDE install dirs, tool dirs, etc.
+ */
+const BLOCKED_DIRECTORY_PATTERNS = [
+    'antigravity', '.gemini', '.cursor', '.vscode-server',
+    'program files', 'programdata', 'appdata',
+    'node_modules', '.npm', '.yarn',
+    'system32', 'windows',
+];
+/** Check if a path is a known IDE/tool directory that should never be indexed */
+function isBlockedDirectory(dirPath) {
+    const lower = dirPath.toLowerCase().replace(/\\/g, '/');
+    return BLOCKED_DIRECTORY_PATTERNS.some(pattern => lower.includes(pattern));
+}
+/**
+ * Intercept an MCP tool response to inject session token metadata.
+ *
+ * Parses the JSON text content, adds `_sessionTokens` and optionally
+ * `_hint` fields, then re-serialises. This works because all our tools
+ * return `{ content: [{ type: 'text', text: JSON.stringify(result) }] }`.
+ */
+function enrichToolResponse(response, tracker, estimator, graphNodeCount, getProjectInfo) {
+    if (!response?.content?.[0]?.text)
+        return response;
+    try {
+        const result = JSON.parse(response.content[0].text);
+        // Estimate tokens for this response
+        const outputTokens = estimator.estimate(response.content[0].text);
+        const tokensSaved = result.tokensSaved ?? 0;
+        // Record in tracker
+        tracker.record(0, outputTokens, tokensSaved);
+        // Always add project metadata
+        const projectInfo = getProjectInfo();
+        result._project = projectInfo;
+        // ALWAYS tell the agent to provide project path if no real project is indexed
+        const nodeCount = graphNodeCount();
+        const rootIsBlocked = isBlockedDirectory(projectInfo.root);
+        if (nodeCount === 0 || rootIsBlocked) {
+            result._indexRequired = true;
+            result._action = 'REQUIRED: Call mindmap_reindex({ projectPath: "<USER_WORKSPACE_PATH>" }). ' +
+                'The current root "' + projectInfo.root + '" is NOT a user project. ' +
+                'Use the workspace/project directory that the user has open in their editor.';
+        }
+        // Always add session token metadata
+        result._sessionTokens = tracker.getSummary();
+        response.content[0].text = JSON.stringify(result);
+    }
+    catch {
+        // If parsing fails, return original response unchanged
+    }
+    return response;
+}
+// ============================================================
+// Main entry point
+// ============================================================
+async function main() {
+    // ── 1. Parse CLI & load config ──────────────────────────────
+    let cliArgs;
+    try {
+        cliArgs = parseCliArgs();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error parsing CLI arguments: ${msg}\n`);
+        process.exit(1);
+    }
+    setLogLevel(cliArgs.logLevel);
+    log('info', '🧠 AI Mind Map MCP Server starting…');
+    let config;
+    try {
+        config = await loadConfig(cliArgs);
+        log('info', `Project root: ${config.projectRoot}`);
+        log('info', `Database path: ${config.dbPath}`);
+        log('debug', 'Loaded config', config);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log('error', `Failed to load configuration: ${msg}`);
+        process.exit(1);
+    }
+    // ── 2. Initialise database directory ────────────────────────
+    try {
+        ensureDbDirectory(config.dbPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log('error', `Failed to create DB directory: ${msg}`);
+        process.exit(1);
+    }
+    // ── 3. Initialise SQLite database ──────────────────────────
+    // KnowledgeGraph manages its own db connection, but ChangeLog,
+    // SessionMemory, PersistentMemory, and DecisionLog each need
+    // a shared Database instance for their tables.
+    log('info', 'Initialising database…');
+    let sharedDb;
+    try {
+        sharedDb = new Database(config.dbPath);
+        sharedDb.pragma('journal_mode = WAL');
+        sharedDb.pragma('foreign_keys = ON');
+        sharedDb.pragma('busy_timeout = 5000');
+        log('info', 'Database initialized with WAL mode');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log('error', `Failed to initialize database: ${msg}`);
+        process.exit(1);
+    }
+    // ── 4. Initialise real subsystems ──────────────────────────
+    log('info', 'Initialising subsystems…');
+    // Knowledge Graph — constructor takes dbPath string
+    const graph = new KnowledgeGraph(config.dbPath);
+    // Indexer — constructor is Indexer(graph, config)
+    const indexer = new Indexer(graph, config);
+    // PageRankEngine — constructor is PageRankEngine(graph, config?)
+    const pagerank = new PageRankEngine(graph);
+    // Changelog Engine — node-level change tracking (v1.4.0)
+    const changelogEngine = new ChangelogEngine(graph.getDb());
+    indexer.setChangelog(changelogEngine);
+    log('info', '✅ Knowledge Graph initialized (with changelog engine)');
+    // Change Tracker
+    // ChangeLog constructor takes ChangeLogConfig: { dbPath, retentionDays?, defaultSearchLimit? }
+    const changeLog = new ChangeLog({ dbPath: config.dbPath });
+    const diffEngine = new DiffEngine(config.projectRoot);
+    let watcher = null;
+    // SessionMemory — must be created before watcher so it's available in the handler
+    // SessionMemory constructor takes Database.Database instance
+    const sessionMemory = new SessionMemory(sharedDb);
+    const sessionId = sessionMemory.startSession();
+    log('info', `Session started: ${sessionId}`);
+    if (config.watchEnabled && !config.memoryOnly) {
+        // FileWatcher constructor: config with { projectRoot, watchDebounceMs?, maxFileSize?, ignore? }
+        watcher = new FileWatcher({
+            projectRoot: config.projectRoot,
+            ignore: config.ignore,
+            watchDebounceMs: config.watchDebounceMs,
+            maxFileSize: config.maxFileSize,
+        });
+        // Wire watcher to indexer so fullIndex() can pause/resume it
+        indexer.setWatcher(watcher);
+        // FileWatcher emits 'changes' with WatcherEvent[]
+        watcher.on('changes', async (events) => {
+            log('debug', `File watcher detected ${events.length} changes`);
+            for (const event of events) {
+                try {
+                    if (event.changeType === 'deleted') {
+                        indexer.removeFile(event.filePath);
+                    }
+                    else {
+                        await indexer.indexFile(event.filePath);
+                    }
+                    const currentSessionId = sessionMemory.getCurrentSessionId() ?? 'no-session';
+                    changeLog.recordChange({
+                        filePath: event.filePath,
+                        changeType: event.changeType,
+                        summary: `File ${event.changeType}: ${path.basename(event.filePath)}`,
+                        symbolsAffected: [],
+                        linesAdded: 0,
+                        linesRemoved: 0,
+                        timestamp: event.timestamp,
+                        sessionId: currentSessionId,
+                    });
+                }
+                catch (err) {
+                    log('warn', `Failed to process file change: ${event.filePath}`, err);
+                }
+            }
+            // Invalidate PageRank cache when graph changes
+            pagerank.invalidateCache();
+        });
+    }
+    log('info', `✅ Change Tracker initialized (watcher: ${config.watchEnabled ? 'enabled' : 'disabled'})`);
+    // Memory
+    // PersistentMemory constructor: (db, config?) where config is Pick<MindMapConfig['memory'], 'decayRate' | 'maxMemories' | 'importanceThreshold'>
+    const persistentMemory = new PersistentMemory(sharedDb, {
+        decayRate: config.memory.decayRate,
+        maxMemories: config.memory.maxMemories,
+        importanceThreshold: config.memory.importanceThreshold,
+    });
+    // DecisionLog constructor: (db, config?) where config is Pick<MindMapConfig['memory'], 'maxDecisions'>
+    const decisionLog = new DecisionLog(sharedDb, {
+        maxDecisions: config.memory.maxDecisions,
+    });
+    log('info', `✅ Memory initialized (session: ${sessionMemory.getCurrentSessionId()})`);
+    // Apply memory decay on startup
+    try {
+        const decayed = persistentMemory.applyDecay();
+        log('info', `Applied time-based memory decay at startup (${decayed} memories decayed)`);
+    }
+    catch (err) {
+        log('warn', 'Failed to apply memory decay at startup', err);
+    }
+    // Context Engine — no class instances needed; uses module-level functions
+    log('info', '✅ Context Engine initialized');
+    // ── 5. Build adapters ──────────────────────────────────────
+    const graphAdapter = createGraphAdapter(graph, pagerank);
+    const changeAdapter = createChangeAdapter(diffEngine, changeLog, graph);
+    const memoryAdapter = createMemoryAdapter(persistentMemory, decisionLog, sessionMemory);
+    const sessionAdapter = createSessionAdapter(sessionMemory);
+    const contextAdapter = createContextAdapter(graph, persistentMemory, decisionLog, changeLog, config);
+    const indexerAdapter = createIndexerAdapter(indexer, graph, persistentMemory, decisionLog, changeLog, config, watcher);
+    // Token estimator using the exported estimateTokens function
+    const tokenEstimator = {
+        estimate: (text) => estimateTokens(text),
+    };
+    // ── 6. Create MCP server ──────────────────────────────────
+    const server = new McpServer({
+        name: 'ai-mind-map',
+        version: '1.7.0',
+    }, {
+        instructions: [
+            '# AI Mind Map — Code Memory Engine',
+            '',
+            '## ⚠ CRITICAL: FIRST STEP IN EVERY CONVERSATION',
+            'Before calling ANY other tool, you MUST ensure a project is indexed:',
+            '1. Check if `_indexRequired: true` appears in any response — if so, the index is empty or pointing at an IDE directory.',
+            '2. Call `mindmap_reindex({ projectPath: "<WORKSPACE>" })` where <WORKSPACE> is the user project directory from their open editor.',
+            '3. NEVER use paths containing: .gemini, antigravity, .cursor, .vscode, AppData, Program Files — these are IDE directories, NOT projects.',
+            '4. Example: `mindmap_reindex({ projectPath: "E:\\myproject" })`',
+            '',
+            '## After Indexing - Resume Session:',
+            'Call `mindmap_session_resume`. It returns:',
+            '- What the previous AI worked on',
+            '- What code changed since then (function-level diffs)',
+            '- Project structure + tech stack',
+            '- Hot files (most frequently changed)',
+            '',
+            '## Project Indexing:',
+            'Every response includes `_project.root` and `_project.totalNodes`.',
+            'If `_indexRequired: true` appears, you MUST call `mindmap_reindex` with the correct project path.',
+            'NEVER index directories containing: antigravity, .gemini, .cursor, .vscode, AppData, Program Files.',
+            'The graph supports multiple projects — call `mindmap_reindex` with different paths to switch.',
+            '',
+            '## Token Tracking:',
+            'Every response includes `_sessionTokens` with cumulative usage.',
+            '',
+            '##  Tool Selection Guide:',
+            '',
+            '### When you need to UNDERSTAND the project:',
+            '- `mindmap_digest` → Full project summary in <2000 tokens',
+            '- `mindmap_architecture` → Layers, patterns, component overview',
+            '- `mindmap_file_digest` → Understand a file WITHOUT reading it',
+            '',
+            '### When you need to FIND code:',
+            '- `mindmap_smart_search` → Search by name/concept (best for most lookups)',
+            '- `mindmap_semantic_search` → Search by meaning ("authentication", "error handling")',
+            '- `mindmap_search_code` → Grep-like text search in code bodies',
+            '- `mindmap_trace_dependencies` → Who calls X? What does X call?',
+            '',
+            '### When you need to READ code:',
+            '- `mindmap_get_code_snippet` → Read actual source code for a function/class',
+            '- `mindmap_get_file_map` → All symbols in a file with signatures + line ranges',
+            '',
+            '### When you need to know WHAT CHANGED:',
+            '- `mindmap_changelog` → Symbol-level diffs (added/modified/deleted functions)',
+            '- `mindmap_git_changes` → Git-aware changes with symbol mapping',
+            '- `mindmap_verify` → Check if your cached knowledge is still valid',
+            '- `mindmap_hotspots` → Most frequently changed files + symbols',
+            '',
+            '### When you need to REMEMBER:',
+            '- `mindmap_remember` → Save a fact/convention for future sessions',
+            '- `mindmap_recall` → Retrieve relevant memories for current task',
+            '- `mindmap_decide` → Record architectural decisions with rationale',
+            '',
+            '### When you finish work:',
+            '- `mindmap_session_end` → Save summary so next AI can resume instantly',
+            '',
+            '### After editing code:',
+            '- `mindmap_verify_changes` → Verify your edits at the symbol level WITHOUT re-reading files',
+            '',
+            '## âš¡ Token-Saving Rules:',
+            '1. ALWAYS call `mindmap_session_resume` first — never start blind',
+            '2. Use `mindmap_file_digest` BEFORE reading a full file — you may not need the full file',
+            '3. Use `mindmap_verify_changes` after editing to verify changes — do NOT re-read whole files',
+            '4. Use `mindmap_changelog` instead of re-reading files to see what changed',
+            '5. Call `mindmap_session_end` when done — save context for next session',
+            '',
+            '## 🔄 Project Indexing:',
+            'Every response includes `_project.root` showing which directory is currently indexed.',
+            'If `_project.totalNodes` is 0, you MUST call `mindmap_reindex` with `projectPath` set to',
+            'the user\'s project directory (e.g. their workspace root). This creates the knowledge graph.',
+            'Example: `mindmap_reindex({ projectPath: "/home/user/my-project" })`',
+            'You can also reindex to switch between projects — the graph supports multiple projects.',
+            '',
+            '## 📊 Token Tracking:',
+            'Every response includes `_sessionTokens` with cumulative usage.',
+        ].join('\n'),
+    });
+    // ── 7. Register all tools ─────────────────────────────────
+    log('info', 'Registering MCP tools…');
+    // ── 7.0 Token tracking middleware ──────────────────────────
+    // Wrap every tool handler to inject session token metadata
+    const tokenTracker = new SessionTokenTracker();
+    const originalToolFn = server.tool.bind(server);
+    // Override server.tool to wrap every handler with token tracking
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    server.tool = function (...args) {
+        // server.tool(name, description, schema, handler) or server.tool(name, description, handler)
+        const lastArgIdx = args.length - 1;
+        const originalHandler = args[lastArgIdx];
+        if (typeof originalHandler === 'function') {
+            args[lastArgIdx] = async (...handlerArgs) => {
+                // Estimate input tokens from args
+                const inputStr = JSON.stringify(handlerArgs);
+                const inputTokens = tokenEstimator.estimate(inputStr);
+                tokenTracker.totalInputTokens += inputTokens;
+                // Call original handler
+                const response = await originalHandler(...handlerArgs);
+                // Enrich response with token tracking + project metadata
+                return enrichToolResponse(response, tokenTracker, tokenEstimator, () => graph.getStats().totalNodes, () => {
+                    const s = graph.getStats();
+                    return { root: config.projectRoot, indexedFiles: s.totalFiles, totalNodes: s.totalNodes };
+                });
+            };
+        }
+        return originalToolFn.apply(server, args);
+    };
+    registerGraphTools(server, graphAdapter, tokenEstimator);
+    log('debug', 'Registered graph tools (6)');
+    registerChangeTools(server, changeAdapter, tokenEstimator);
+    log('debug', 'Registered change tools (3)');
+    registerMemoryTools(server, memoryAdapter, sessionAdapter, tokenEstimator);
+    log('debug', 'Registered memory tools (5)');
+    registerContextTools(server, contextAdapter, indexerAdapter, tokenEstimator);
+    log('debug', 'Registered context tools (4)');
+    registerDebugTools(server, graph, config, tokenEstimator);
+    log('debug', 'Registered debug tools (3)');
+    registerFlowTools(server, graph, config, tokenEstimator);
+    log('debug', 'Registered flow tools (4)');
+    registerSnapshotTools(server, graph, config, tokenEstimator);
+    log('debug', 'Registered snapshot tools (3)');
+    // Initialize semantic search engine
+    const semanticEngine = new SemanticSearchEngine(graph.getDb());
+    log('debug', 'Initialized semantic search engine');
+    registerSmartTools(server, graph, config, tokenEstimator, semanticEngine);
+    log('debug', 'Registered smart tools (3)');
+    registerEvolvingTools(server, graph, config, tokenEstimator);
+    log('debug', 'Registered evolving tools (3)');
+    registerAdvancedTools(server, graph, config, tokenEstimator, semanticEngine);
+    log('debug', 'Registered advanced tools (7)');
+    registerSemanticTools(server, graph, semanticEngine, config, tokenEstimator);
+    log('debug', 'Registered semantic search tools (3)');
+    // Session, Changelog & Digest tools (v1.4.0)
+    registerSessionTools(server, graph, changelogEngine, config, tokenEstimator);
+    log('debug', 'Registered session tools (5)');
+    registerDigestTools(server, graph, changelogEngine, config, tokenEstimator);
+    log('debug', 'Registered digest tools (3)');
+    // ── mindmap_sync_shared_context ─────────────────────────────
+    server.tool('mindmap_sync_shared_context', 'Synchronise local memories, decisions, and learned rules with the team-shared `.mindmap-shared.json` file. ' +
+        'Performs a bidirectional sync to import new conventions/decisions and export local updates.', {}, async () => {
+        try {
+            const syncStats = await syncSharedContext(config, graph, persistentMemory, decisionLog);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: 'Bidirectional synchronization completed successfully.',
+                            stats: syncStats
+                        })
+                    }
+                ]
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            message: `Synchronization failed: ${msg}`
+                        })
+                    }
+                ]
+            };
+        }
+    });
+    log('debug', 'Registered shared context sync tool');
+    log('info', '🔧 All MCP tools registered:');
+    log('info', '  Graph:    mindmap_search, mindmap_get_structure, mindmap_trace_dependencies, mindmap_get_signature, mindmap_find_references, mindmap_get_file_map');
+    log('info', '  Changes:  mindmap_what_changed, mindmap_session_diff, mindmap_impact_analysis');
+    log('info', '  Memory:   mindmap_recall, mindmap_remember, mindmap_get_decisions, mindmap_decide, mindmap_session_summary, mindmap_sync_shared_context');
+    log('info', '  Context:  mindmap_get_context, mindmap_compress, mindmap_reindex, mindmap_status');
+    log('info', '  Debug:    mindmap_debug_changes, mindmap_file_before, mindmap_file_history');
+    log('info', '  Flow:     mindmap_trace_flow, mindmap_interaction_map, mindmap_classify_file, mindmap_layer_overview');
+    log('info', '  Snapshot: mindmap_project_map, mindmap_change_delta, mindmap_session_kickoff ⭐');
+    log('info', '  Advanced: mindmap_query_graph, mindmap_dead_code, mindmap_architecture, mindmap_get_code_snippet, mindmap_search_code, mindmap_list_projects, mindmap_health');
+    log('info', '  Smart:    mindmap_explain ⭐, mindmap_git_changes ⭐, mindmap_smart_search ⭐');
+    log('info', '  Evolving: mindmap_teach ⭐, mindmap_get_learned, mindmap_forget');
+    log('info', '  Semantic: mindmap_semantic_search ⭐, mindmap_semantic_stats, mindmap_synonyms');
+    log('info', '  Session:  mindmap_session_start 🆕, mindmap_session_resume 🔥🆕, mindmap_session_end, mindmap_changelog 🆕, mindmap_hotspots, mindmap_verify_changes 🆕');
+    log('info', '  Digest:   mindmap_digest ⭐, mindmap_file_digest ⭐, mindmap_verify');
+    // ── 7.3 Register MCP Prompts ──────────────────────────────
+    // These are interactive workflow templates that AI agents can request
+    server.prompt('start_session', 'Recommended first prompt for any AI coding session. Calls mindmap_session_resume and returns a complete project briefing.', async () => {
+        // Auto-start session
+        const sessionId = changelogEngine.ensureSession('ai-agent');
+        const lastSession = changelogEngine.getLastSession();
+        const stats = graph.getStats();
+        const since = lastSession?.endedAt || lastSession?.startedAt || (Date.now() - 24 * 3600_000);
+        const changes = changelogEngine.getChangesSince(since);
+        const lines = [
+            '# Session Briefing',
+            '',
+            `**Project**: ${path.basename(config.projectRoot)}`,
+            `**Files**: ${stats.totalFiles} | **Symbols**: ${stats.totalNodes} | **Relationships**: ${stats.totalEdges}`,
+            `**Languages**: ${Object.entries(stats.languageBreakdown).map(([l, c]) => `${l}(${c})`).join(', ')}`,
+            '',
+        ];
+        if (lastSession) {
+            lines.push('## Previous Session', `- **Agent**: ${lastSession.agentName}`, `- **Task**: ${lastSession.taskDescription || 'Not specified'}`, `- **Summary**: ${lastSession.summary || 'No summary'}`, `- **Files modified**: ${lastSession.filesModified.length}`, '');
+        }
+        if (changes.totalChanges > 0) {
+            lines.push(`## Changes Since Last Session (${changes.sinceLabel})`, `${changes.filesChanged} files, ${changes.totalChanges} symbol changes:`);
+            for (const f of changes.files.slice(0, 8)) {
+                const rel = path.relative(config.projectRoot, f.filePath).replace(/\\/g, '/');
+                const parts = [];
+                if (f.added.length > 0)
+                    parts.push(`+${f.added.length}`);
+                if (f.modified.length > 0)
+                    parts.push(`~${f.modified.length}`);
+                if (f.deleted.length > 0)
+                    parts.push(`-${f.deleted.length}`);
+                lines.push(`  ${rel}: ${parts.join(', ')}`);
+            }
+            lines.push('');
+        }
+        lines.push('## What to do next', '- Use `mindmap_smart_search` to find specific code', '- Use `mindmap_explain` to understand a symbol', '- Use `mindmap_changelog` for detailed change diffs', '- Use `mindmap_session_end` when done');
+        return {
+            messages: [{
+                    role: 'user',
+                    content: { type: 'text', text: lines.join('\n') },
+                }],
+        };
+    });
+    server.prompt('tool_guide', 'Complete guide to all AI Mind Map tools — when to use each one, organized by task.', async () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        '# AI Mind Map — Complete Tool Guide',
+                        '',
+                        '## 🚀 Session Lifecycle (use these to avoid re-reading code)',
+                        '| Tool | When to Use |',
+                        '|------|------------|',
+                        '| `mindmap_session_resume` | **FIRST call every conversation** — returns project context + changes |',
+                        '| `mindmap_session_kickoff` | Full preamble: project map + change delta + memories in ONE call |',
+                        '| `mindmap_session_start` | Start tracking a new task (records agent name + task) |',
+                        '| `mindmap_session_end` | Save summary for next AI session |',
+                        '',
+                        '## 🔍 Finding Code (instead of grep/reading files)',
+                        '| Tool | When to Use |',
+                        '|------|------------|',
+                        '| `mindmap_smart_search` | Search by function/class name — returns full context |',
+                        '| `mindmap_semantic_search` | Search by concept ("error handling", "auth") |',
+                        '| `mindmap_search_code` | Grep-like text search in code bodies |',
+                        '| `mindmap_find_references` | Find all usages of a symbol |',
+                        '| `mindmap_trace_dependencies` | Who calls X? What does X call? |',
+                        '',
+                        '## 📖 Reading Code (without reading full files)',
+                        '| Tool | When to Use |',
+                        '|------|------------|',
+                        '| `mindmap_explain` | Get EVERYTHING about a symbol in one call |',
+                        '| `mindmap_get_code_snippet` | Read actual source for a function |',
+                        '| `mindmap_file_digest` | Understand a file without reading it |',
+                        '| `mindmap_get_file_map` | All symbols in a file with signatures |',
+                        '| `mindmap_get_signature` | Just the signature (cheapest read) |',
+                        '',
+                        '## 📊 Understanding the Project',
+                        '| Tool | When to Use |',
+                        '|------|------------|',
+                        '| `mindmap_digest` | Full project summary in <2000 tokens |',
+                        '| `mindmap_architecture` | Architecture layers + patterns |',
+                        '| `mindmap_project_map` | Complete project map |',
+                        '',
+                        '## 🔄 Change Tracking',
+                        '| Tool | When to Use |',
+                        '|------|------------|',
+                        '| `mindmap_changelog` | Symbol-level diffs since a time |',
+                        '| `mindmap_git_changes` | Git-aware change detection |',
+                        '| `mindmap_verify` | Check if cached code is still valid |',
+                        '| `mindmap_hotspots` | Most frequently changed files |',
+                        '',
+                        '## 🧠 Memory & Decisions',
+                        '| Tool | When to Use |',
+                        '|------|------------|',
+                        '| `mindmap_remember` | Save important facts for future |',
+                        '| `mindmap_recall` | Retrieve relevant memories |',
+                        '| `mindmap_decide` | Record architectural decisions |',
+                        '| `mindmap_teach` | Teach persistent rules |',
+                    ].join('\n'),
+                },
+            }],
+    }));
+    log('debug', 'Registered 2 MCP prompts (start_session, tool_guide)');
+    // ── 7.5 Auto-sync shared context on startup ────────────────
+    if (config.autoSyncSharedContext) {
+        log('info', '🔄 Auto-syncing shared context…');
+        try {
+            const syncStats = await syncSharedContext(config, graph, persistentMemory, decisionLog);
+            log('info', `✅ Shared context sync complete: ` +
+                `Imported: ${syncStats.memoriesImported} memories, ${syncStats.decisionsImported} decisions, ${syncStats.rulesImported} rules. ` +
+                `Exported: ${syncStats.memoriesExported} memories, ${syncStats.decisionsExported} decisions, ${syncStats.rulesExported} rules.`);
+        }
+        catch (err) {
+            log('warn', `⚠️ Auto-sync of shared context failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── 8. Smart auto-index (only if projectRoot looks like a real project) ──
+    if (config.memoryOnly) {
+        log('info', '🧠 Running in memoryOnly mode. Bypassing codebase parsing and indexing.');
+    }
+    else {
+        // Check if projectRoot is a real project (not an IDE install directory)
+        const projectMarkers = [
+            '.git', 'package.json', 'build.gradle', 'build.gradle.kts',
+            'Cargo.toml', 'go.mod', 'pom.xml', 'CMakeLists.txt',
+            'Makefile', '.project', 'setup.py', 'pyproject.toml',
+            'pubspec.yaml', 'Gemfile', '*.sln', '*.csproj',
+        ];
+        const isRealProject = projectMarkers.some(marker => existsSync(path.join(config.projectRoot, marker)));
+        if (!isRealProject || isBlockedDirectory(config.projectRoot)) {
+            log('info', `⚠️ Project root "${config.projectRoot}" does not look like a code project (no .git, package.json, etc.).`);
+            log('info', '   Skipping auto-index. The AI agent will be prompted to call mindmap_reindex with the correct project path.');
+        }
+        else {
+            const stats = graph.getStats();
+            if (stats.totalNodes === 0) {
+                log('info', `📋 Real project detected at: ${config.projectRoot}. Running initial indexing…`);
+                try {
+                    const result = await indexer.fullIndex();
+                    log('info', `✅ Initial index complete: ${result.filesParsed} files, ${result.nodesCreated} nodes, ${result.edgesCreated} edges`);
+                    if (result.parseErrors > 0) {
+                        log('warn', `⚠️ ${result.parseErrors} parse errors (non-fatal)`);
+                    }
+                }
+                catch (err) {
+                    log('warn', `⚠️ Initial indexing failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                log('info', `📋 Existing index found: ${stats.totalNodes} nodes. Running incremental update…`);
+                try {
+                    const result = await indexer.incrementalIndex();
+                    log('info', `✅ Incremental update: ${result.filesParsed} files reindexed`);
+                }
+                catch (err) {
+                    log('warn', `⚠️ Incremental update failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        // Build semantic search TF-IDF index from existing graph nodes (if any)
+        try {
+            const allNodes = graph.getAllNodes();
+            const nonFileNodes = allNodes.filter(n => n.type !== 'file');
+            if (nonFileNodes.length > 0) {
+                semanticEngine.indexNodes(nonFileNodes.map(n => ({
+                    id: n.id,
+                    name: n.name,
+                    qualifiedName: n.qualifiedName,
+                    signature: n.signature,
+                    docComment: n.docComment,
+                    filePath: n.filePath,
+                })));
+                semanticEngine.rebuildIDF();
+                log('info', `🧠 Semantic index built: ${nonFileNodes.length} symbols indexed`);
+            }
+        }
+        catch (err) {
+            log('warn', `⚠️ Semantic index build failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── 9. Start file watcher ──────────────────────────────────
+    if (watcher && !config.memoryOnly) {
+        try {
+            await watcher.start();
+            log('info', '👁️ File watcher started');
+        }
+        catch (err) {
+            log('warn', `⚠️ File watcher failed to start: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── 10. Graceful shutdown ──────────────────────────────────
+    let shuttingDown = false;
+    async function shutdown(signal) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log('info', `Received ${signal}, shutting down gracefully…`);
+        try {
+            // Stop file watcher
+            if (watcher) {
+                await watcher.stop();
+                log('debug', 'File watcher stopped');
+            }
+            // End current session
+            try {
+                sessionMemory.endSession();
+                log('debug', 'Session ended');
+            }
+            catch {
+                // Ignore session end errors
+            }
+            // Apply memory decay
+            try {
+                persistentMemory.applyDecay();
+                log('debug', 'Memory decay applied');
+            }
+            catch {
+                // Ignore decay errors
+            }
+            // Close change log database
+            try {
+                changeLog.close();
+                log('debug', 'Change log closed');
+            }
+            catch {
+                // Ignore close errors
+            }
+            // Close graph database
+            try {
+                graph.close();
+                log('debug', 'Knowledge graph closed');
+            }
+            catch {
+                // Ignore close errors
+            }
+            // Close shared database
+            try {
+                sharedDb.close();
+                log('debug', 'Shared database closed');
+            }
+            catch {
+                // Ignore close errors
+            }
+            log('info', '✅ Cleanup complete. Goodbye!');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log('error', `Error during shutdown: ${msg}`);
+        }
+        process.exit(0);
+    }
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    // Handle uncaught errors gracefully
+    process.on('uncaughtException', (err) => {
+        log('error', `Uncaught exception: ${err.message}`, err.stack);
+        void shutdown('uncaughtException');
+    });
+    process.on('unhandledRejection', (reason) => {
+        const msg = reason instanceof Error ? reason.message : String(reason);
+        log('error', `Unhandled rejection: ${msg}`);
+    });
+    // ── 11. Connect transport and start serving ────────────────
+    log('info', 'Connecting stdio transport…');
+    try {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        log('info', '🧠 AI Mind Map MCP Server is LIVE. Waiting for requests…');
+        log('info', `   Project: ${config.projectRoot}`);
+        log('info', `   Database: ${config.dbPath}`);
+        log('info', `   Session: ${sessionMemory.getCurrentSessionId()}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log('error', `Failed to start MCP server: ${msg}`);
+        process.exit(1);
+    }
+}
+// ── Kick off ────────────────────────────────────────────────
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Fatal: ${msg}\n`);
+    process.exit(1);
+});
 //# sourceMappingURL=index.js.map