codebase-context 1.2.1 → 1.5.0

package/dist/index.js

@@ -1,20 +1,24 @@
 #!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * MCP Server for Codebase Context
  * Provides codebase indexing and semantic search capabilities
  */
-import { promises as fs } from "fs";
-import path from "path";
-import { glob } from "glob";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { CodebaseIndexer } from "./core/indexer.js";
-import { CodebaseSearcher } from "./core/search.js";
-import { analyzerRegistry } from "./core/analyzer-registry.js";
-import { AngularAnalyzer } from "./analyzers/angular/index.js";
-import { GenericAnalyzer } from "./analyzers/generic/index.js";
-import { InternalFileGraph } from "./utils/usage-tracker.js";
+import { promises as fs } from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CodebaseIndexer } from './core/indexer.js';
+import { CodebaseSearcher } from './core/search.js';
+import { analyzerRegistry } from './core/analyzer-registry.js';
+import { AngularAnalyzer } from './analyzers/angular/index.js';
+import { GenericAnalyzer } from './analyzers/generic/index.js';
+import { InternalFileGraph } from './utils/usage-tracker.js';
+import { IndexCorruptedError } from './errors/index.js';
+import { CODEBASE_CONTEXT_DIRNAME, MEMORY_FILENAME, INTELLIGENCE_FILENAME, KEYWORD_INDEX_FILENAME, VECTOR_DB_DIRNAME } from './constants/codebase-context.js';
+import { appendMemoryFile, readMemoriesFile, filterMemories, applyUnfilteredLimit } from './memory/store.js';
 analyzerRegistry.register(new AngularAnalyzer());
 analyzerRegistry.register(new GenericAnalyzer());
 // Resolve root path with validation
@@ -32,168 +36,304 @@ function resolveRootPath() {
     return rootPath;
 }
 const ROOT_PATH = resolveRootPath();
+// File paths (new structure)
+const PATHS = {
+    baseDir: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME),
+    memory: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME, MEMORY_FILENAME),
+    intelligence: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME, INTELLIGENCE_FILENAME),
+    keywordIndex: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME, KEYWORD_INDEX_FILENAME),
+    vectorDb: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME, VECTOR_DB_DIRNAME)
+};
+// Legacy paths for migration
+const LEGACY_PATHS = {
+    // Pre-v1.5
+    intelligence: path.join(ROOT_PATH, '.codebase-intelligence.json'),
+    keywordIndex: path.join(ROOT_PATH, '.codebase-index.json'),
+    vectorDb: path.join(ROOT_PATH, '.codebase-index')
+};
+/**
+ * Check if file/directory exists
+ */
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Migrate legacy file structure to .codebase-context/ folder.
+ * Idempotent, fail-safe. Rollback compatibility is not required.
+ */
+async function migrateToNewStructure() {
+    let migrated = false;
+    try {
+        await fs.mkdir(PATHS.baseDir, { recursive: true });
+        // intelligence.json
+        if (!(await fileExists(PATHS.intelligence))) {
+            if (await fileExists(LEGACY_PATHS.intelligence)) {
+                await fs.copyFile(LEGACY_PATHS.intelligence, PATHS.intelligence);
+                migrated = true;
+                if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                    console.error('[DEBUG] Migrated intelligence.json');
+                }
+            }
+        }
+        // index.json (keyword index)
+        if (!(await fileExists(PATHS.keywordIndex))) {
+            if (await fileExists(LEGACY_PATHS.keywordIndex)) {
+                await fs.copyFile(LEGACY_PATHS.keywordIndex, PATHS.keywordIndex);
+                migrated = true;
+                if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                    console.error('[DEBUG] Migrated index.json');
+                }
+            }
+        }
+        // Vector DB directory
+        if (!(await fileExists(PATHS.vectorDb))) {
+            if (await fileExists(LEGACY_PATHS.vectorDb)) {
+                await fs.rename(LEGACY_PATHS.vectorDb, PATHS.vectorDb);
+                migrated = true;
+                if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                    console.error('[DEBUG] Migrated vector database');
+                }
+            }
+        }
+        return migrated;
+    }
+    catch (error) {
+        if (process.env.CODEBASE_CONTEXT_DEBUG) {
+            console.error('[DEBUG] Migration error:', error);
+        }
+        return false;
+    }
+}
 const indexState = {
-    status: "idle",
+    status: 'idle'
 };
 const server = new Server({
-    name: "codebase-context-mcp",
-    version: "1.0.0",
+    name: 'codebase-context',
+    version: '1.4.0'
 }, {
     capabilities: {
         tools: {},
-        resources: {},
-        logging: {}, // Enable structured logging for clients that support it
-    },
+        resources: {}
+    }
 });
 const TOOLS = [
     {
-        name: "search_codebase",
-        description: "Search the indexed codebase using natural language queries. Returns code summaries with file locations. " +
-            "Supports framework-specific queries and architectural layer filtering. " +
-            "Use the returned filePath with other tools to read complete file contents.",
+        name: 'search_codebase',
+        description: 'Search the indexed codebase using natural language queries. Returns code summaries with file locations. ' +
+            'Supports framework-specific queries and architectural layer filtering. ' +
+            'Use the returned filePath with other tools to read complete file contents.',
         inputSchema: {
-            type: "object",
+            type: 'object',
             properties: {
                 query: {
-                    type: "string",
-                    description: "Natural language search query",
+                    type: 'string',
+                    description: 'Natural language search query'
                 },
                 limit: {
-                    type: "number",
-                    description: "Maximum number of results to return (default: 5)",
-                    default: 5,
+                    type: 'number',
+                    description: 'Maximum number of results to return (default: 5)',
+                    default: 5
                 },
                 filters: {
-                    type: "object",
-                    description: "Optional filters",
+                    type: 'object',
+                    description: 'Optional filters',
                     properties: {
                         framework: {
-                            type: "string",
-                            description: "Filter by framework (angular, react, vue)",
+                            type: 'string',
+                            description: 'Filter by framework (angular, react, vue)'
                         },
                         language: {
-                            type: "string",
-                            description: "Filter by programming language",
+                            type: 'string',
+                            description: 'Filter by programming language'
                         },
                         componentType: {
-                            type: "string",
-                            description: "Filter by component type (component, service, directive, etc.)",
+                            type: 'string',
+                            description: 'Filter by component type (component, service, directive, etc.)'
                         },
                         layer: {
-                            type: "string",
-                            description: "Filter by architectural layer (presentation, business, data, state, core, shared)",
+                            type: 'string',
+                            description: 'Filter by architectural layer (presentation, business, data, state, core, shared)'
                         },
                         tags: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Filter by tags",
-                        },
-                    },
-                },
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Filter by tags'
+                        }
+                    }
+                }
             },
-            required: ["query"],
-        },
+            required: ['query']
+        }
     },
     {
-        name: "get_codebase_metadata",
-        description: "Get codebase metadata including framework information, dependencies, architecture patterns, " +
-            "and project statistics.",
+        name: 'get_codebase_metadata',
+        description: 'Get codebase metadata including framework information, dependencies, architecture patterns, ' +
+            'and project statistics.',
         inputSchema: {
-            type: "object",
-            properties: {},
-        },
+            type: 'object',
+            properties: {}
+        }
     },
     {
-        name: "get_indexing_status",
-        description: "Get current indexing status: state, statistics, and progress. " +
-            "Use refresh_index to manually trigger re-indexing when needed.",
+        name: 'get_indexing_status',
+        description: 'Get current indexing status: state, statistics, and progress. ' +
+            'Use refresh_index to manually trigger re-indexing when needed.',
         inputSchema: {
-            type: "object",
-            properties: {},
-        },
+            type: 'object',
+            properties: {}
+        }
     },
     {
-        name: "refresh_index",
-        description: "Re-index the codebase. Supports full re-index or incremental mode. " +
-            "Use incrementalOnly=true to only process files changed since last index.",
+        name: 'refresh_index',
+        description: 'Re-index the codebase. Supports full re-index or incremental mode. ' +
+            'Use incrementalOnly=true to only process files changed since last index.',
         inputSchema: {
-            type: "object",
+            type: 'object',
             properties: {
                 reason: {
-                    type: "string",
-                    description: "Reason for refreshing the index (for logging)",
+                    type: 'string',
+                    description: 'Reason for refreshing the index (for logging)'
                 },
                 incrementalOnly: {
-                    type: "boolean",
-                    description: "If true, only re-index files changed since last full index (faster). Default: false (full re-index)",
-                },
-            },
-        },
+                    type: 'boolean',
+                    description: 'If true, only re-index files changed since last full index (faster). Default: false (full re-index)'
+                }
+            }
+        }
     },
     {
-        name: "get_style_guide",
-        description: "Query style guide rules and architectural patterns from project documentation.",
+        name: 'get_style_guide',
+        description: 'Query style guide rules and architectural patterns from project documentation.',
         inputSchema: {
-            type: "object",
+            type: 'object',
             properties: {
                 query: {
-                    type: "string",
-                    description: 'Query for specific style guide rules (e.g., "component naming", "service patterns")',
+                    type: 'string',
+                    description: 'Query for specific style guide rules (e.g., "component naming", "service patterns")'
                 },
                 category: {
-                    type: "string",
-                    description: "Filter by category (naming, structure, patterns, testing)",
-                },
+                    type: 'string',
+                    description: 'Filter by category (naming, structure, patterns, testing)'
+                }
             },
-            required: ["query"],
-        },
+            required: ['query']
+        }
     },
     {
-        name: "get_team_patterns",
-        description: "Get actionable team pattern recommendations based on codebase analysis. " +
-            "Returns consensus patterns for DI, state management, testing, library wrappers, etc.",
+        name: 'get_team_patterns',
+        description: 'Get actionable team pattern recommendations based on codebase analysis. ' +
+            'Returns consensus patterns for DI, state management, testing, library wrappers, etc.',
         inputSchema: {
-            type: "object",
+            type: 'object',
             properties: {
                 category: {
-                    type: "string",
-                    description: "Pattern category to retrieve",
-                    enum: ["all", "di", "state", "testing", "libraries"],
-                },
-            },
-        },
+                    type: 'string',
+                    description: 'Pattern category to retrieve',
+                    enum: ['all', 'di', 'state', 'testing', 'libraries']
+                }
+            }
+        }
     },
     {
-        name: "get_component_usage",
-        description: "Find WHERE a library or component is used in the codebase. " +
+        name: 'get_component_usage',
+        description: 'Find WHERE a library or component is used in the codebase. ' +
             "This is 'Find Usages' - returns all files that import a given package/module. " +
             "Example: get_component_usage('@mycompany/utils') → shows all 34 files using it.",
         inputSchema: {
-            type: "object",
+            type: 'object',
             properties: {
                 name: {
-                    type: "string",
-                    description: "Import source to find usages for (e.g., 'primeng/table', '@mycompany/ui/button', 'lodash')",
-                },
+                    type: 'string',
+                    description: "Import source to find usages for (e.g., 'primeng/table', '@mycompany/ui/button', 'lodash')"
+                }
             },
-            required: ["name"],
-        },
+            required: ['name']
+        }
     },
     {
-        name: "detect_circular_dependencies",
-        description: "Analyze the import graph to detect circular dependencies between files. " +
-            "Circular dependencies can cause initialization issues, tight coupling, and maintenance problems. " +
-            "Returns all detected cycles sorted by length (shorter cycles are often more problematic).",
+        name: 'detect_circular_dependencies',
+        description: 'Analyze the import graph to detect circular dependencies between files. ' +
+            'Circular dependencies can cause initialization issues, tight coupling, and maintenance problems. ' +
+            'Returns all detected cycles sorted by length (shorter cycles are often more problematic).',
         inputSchema: {
-            type: "object",
+            type: 'object',
             properties: {
                 scope: {
-                    type: "string",
-                    description: "Optional path prefix to limit analysis (e.g., 'src/features', 'libs/shared')",
+                    type: 'string',
+                    description: "Optional path prefix to limit analysis (e.g., 'src/features', 'libs/shared')"
+                }
+            }
+        }
+    },
+    {
+        name: 'remember',
+        description: '📝 CALL IMMEDIATELY when user explicitly asks to remember/record something.\n\n' +
+            'USER TRIGGERS:\n' +
+            '• "Remember this: [X]"\n' +
+            '• "Record this: [Y]"\n' +
+            '• "Save this for next time: [Z]"\n\n' +
+            '⚠️ DO NOT call unless user explicitly requests it.\n\n' +
+            'HOW TO WRITE:\n' +
+            '• ONE convention per memory (if user lists 5 things, call this 5 times)\n' +
+            '• memory: 5-10 words (the specific rule)\n' +
+            '• reason: 1 sentence (why it matters)\n' +
+            '• Skip: one-time features, code examples, essays',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: ['convention', 'decision', 'gotcha'],
+                    description: 'Type of memory being recorded'
+                },
+                category: {
+                    type: 'string',
+                    description: 'Broader category for filtering',
+                    enum: ['tooling', 'architecture', 'testing', 'dependencies', 'conventions']
+                },
+                memory: {
+                    type: 'string',
+                    description: 'What to remember (concise)'
                 },
+                reason: {
+                    type: 'string',
+                    description: 'Why this matters or what breaks otherwise'
+                }
             },
-        },
+            required: ['type', 'category', 'memory', 'reason']
+        }
     },
+    {
+        name: 'get_memory',
+        description: 'Retrieves team conventions, architectural decisions, and known gotchas.\n' +
+            'CALL BEFORE suggesting patterns, libraries, or architecture.\n\n' +
+            'Filters: category (tooling/architecture/testing/dependencies/conventions), type (convention/decision/gotcha), query (keyword search).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: 'Filter by category',
+                    enum: ['tooling', 'architecture', 'testing', 'dependencies', 'conventions']
+                },
+                type: {
+                    type: 'string',
+                    description: 'Filter by memory type',
+                    enum: ['convention', 'decision', 'gotcha']
+                },
+                query: {
+                    type: 'string',
+                    description: 'Keyword search across memory and reason'
+                }
+            }
+        }
+    }
 ];
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools: TOOLS };
@@ -201,59 +341,59 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 // MCP Resources - Proactive context injection
 const RESOURCES = [
     {
-        uri: "codebase://context",
-        name: "Codebase Intelligence",
-        description: "Automatic codebase context: libraries used, team patterns, and conventions. " +
-            "Read this BEFORE generating code to follow team standards.",
-        mimeType: "text/plain",
-    },
+        uri: 'codebase://context',
+        name: 'Codebase Intelligence',
+        description: 'Automatic codebase context: libraries used, team patterns, and conventions. ' +
+            'Read this BEFORE generating code to follow team standards.',
+        mimeType: 'text/plain'
+    }
 ];
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
     return { resources: RESOURCES };
 });
 async function generateCodebaseContext() {
-    const intelligencePath = path.join(ROOT_PATH, ".codebase-intelligence.json");
+    const intelligencePath = PATHS.intelligence;
     try {
-        const content = await fs.readFile(intelligencePath, "utf-8");
+        const content = await fs.readFile(intelligencePath, 'utf-8');
         const intelligence = JSON.parse(content);
         const lines = [];
-        lines.push("# Codebase Intelligence");
-        lines.push("");
-        lines.push("⚠️  CRITICAL: This is what YOUR codebase actually uses, not generic recommendations.");
-        lines.push("These are FACTS from analyzing your code, not best practices from the internet.");
-        lines.push("");
+        lines.push('# Codebase Intelligence');
+        lines.push('');
+        lines.push('⚠️  CRITICAL: This is what YOUR codebase actually uses, not generic recommendations.');
+        lines.push('These are FACTS from analyzing your code, not best practices from the internet.');
+        lines.push('');
         // Library usage - sorted by count
         const libraryEntries = Object.entries(intelligence.libraryUsage || {})
             .map(([lib, data]) => ({
             lib,
-            count: data.count,
+            count: data.count
         }))
             .sort((a, b) => b.count - a.count);
         if (libraryEntries.length > 0) {
-            lines.push("## Libraries Actually Used (Top 15)");
-            lines.push("");
+            lines.push('## Libraries Actually Used (Top 15)');
+            lines.push('');
             for (const { lib, count } of libraryEntries.slice(0, 15)) {
                 lines.push(`- **${lib}** (${count} uses)`);
             }
-            lines.push("");
+            lines.push('');
         }
         // Show tsconfig paths if available (helps AI understand internal imports)
         if (intelligence.tsconfigPaths && Object.keys(intelligence.tsconfigPaths).length > 0) {
-            lines.push("## Import Aliases (from tsconfig.json)");
-            lines.push("");
-            lines.push("These path aliases map to internal project code:");
+            lines.push('## Import Aliases (from tsconfig.json)');
+            lines.push('');
+            lines.push('These path aliases map to internal project code:');
             for (const [alias, paths] of Object.entries(intelligence.tsconfigPaths)) {
-                lines.push(`- \`${alias}\` → ${paths.join(", ")}`);
+                lines.push(`- \`${alias}\` → ${paths.join(', ')}`);
             }
-            lines.push("");
+            lines.push('');
         }
         // Pattern consensus
         if (intelligence.patterns && Object.keys(intelligence.patterns).length > 0) {
             lines.push("## YOUR Codebase's Actual Patterns (Not Generic Best Practices)");
-            lines.push("");
-            lines.push("These patterns were detected by analyzing your actual code.");
-            lines.push("This is what YOUR team does in practice, not what tutorials recommend.");
-            lines.push("");
+            lines.push('');
+            lines.push('These patterns were detected by analyzing your actual code.');
+            lines.push('This is what YOUR team does in practice, not what tutorials recommend.');
+            lines.push('');
             for (const [category, data] of Object.entries(intelligence.patterns)) {
                 const patternData = data;
                 const primary = patternData.primary;
@@ -261,7 +401,7 @@ async function generateCodebaseContext() {
                     continue;
                 const percentage = parseInt(primary.frequency);
                 const categoryName = category
-                    .replace(/([A-Z])/g, " $1")
+                    .replace(/([A-Z])/g, ' $1')
                     .trim()
                     .replace(/^./, (str) => str.toUpperCase());
                 if (percentage === 100) {
@@ -295,40 +435,40 @@ async function generateCodebaseContext() {
                     }
                     lines.push(`   → ASK the team which approach to use for new features`);
                 }
-                lines.push("");
+                lines.push('');
             }
         }
-        lines.push("---");
+        lines.push('---');
         lines.push(`Generated: ${intelligence.generatedAt || new Date().toISOString()}`);
-        return lines.join("\n");
+        return lines.join('\n');
     }
     catch (error) {
-        return ("# Codebase Intelligence\n\n" +
-            "Intelligence data not yet generated. Run indexing first.\n" +
+        return ('# Codebase Intelligence\n\n' +
+            'Intelligence data not yet generated. Run indexing first.\n' +
             `Error: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const uri = request.params.uri;
-    if (uri === "codebase://context") {
+    if (uri === 'codebase://context') {
         const content = await generateCodebaseContext();
         return {
             contents: [
                 {
                     uri,
-                    mimeType: "text/plain",
-                    text: content,
-                },
-            ],
+                    mimeType: 'text/plain',
+                    text: content
+                }
+            ]
         };
     }
     throw new Error(`Unknown resource: ${uri}`);
 });
 async function performIndexing() {
-    indexState.status = "indexing";
+    indexState.status = 'indexing';
     console.error(`Indexing: ${ROOT_PATH}`);
     try {
-        let lastLoggedProgress = { phase: "", percentage: -1 };
+        let lastLoggedProgress = { phase: '', percentage: -1 };
         const indexer = new CodebaseIndexer({
             rootPath: ROOT_PATH,
             onProgress: (progress) => {
@@ -339,23 +479,23 @@ async function performIndexing() {
                     console.error(`[${progress.phase}] ${progress.percentage}%`);
                     lastLoggedProgress = { phase: progress.phase, percentage: progress.percentage };
                 }
-            },
+            }
         });
         indexState.indexer = indexer;
         const stats = await indexer.index();
-        indexState.status = "ready";
+        indexState.status = 'ready';
         indexState.lastIndexed = new Date();
         indexState.stats = stats;
         console.error(`Complete: ${stats.indexedFiles} files, ${stats.totalChunks} chunks in ${(stats.duration / 1000).toFixed(2)}s`);
     }
     catch (error) {
-        indexState.status = "error";
+        indexState.status = 'error';
         indexState.error = error instanceof Error ? error.message : String(error);
-        console.error("Indexing failed:", indexState.error);
+        console.error('Indexing failed:', indexState.error);
     }
 }
 async function shouldReindex() {
-    const indexPath = path.join(ROOT_PATH, ".codebase-index.json");
+    const indexPath = PATHS.keywordIndex;
     try {
         await fs.access(indexPath);
         return false;
@@ -368,43 +508,99 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
         switch (name) {
-            case "search_codebase": {
+            case 'search_codebase': {
                 const { query, limit, filters } = args;
-                if (indexState.status === "indexing") {
+                if (indexState.status === 'indexing') {
                     return {
                         content: [
                             {
-                                type: "text",
+                                type: 'text',
                                 text: JSON.stringify({
-                                    status: "indexing",
-                                    message: "Index is still being built. Retry in a moment.",
-                                    progress: indexState.indexer?.getProgress(),
-                                }, null, 2),
-                            },
-                        ],
+                                    status: 'indexing',
+                                    message: 'Index is still being built. Retry in a moment.',
+                                    progress: indexState.indexer?.getProgress()
+                                }, null, 2)
+                            }
+                        ]
                     };
                 }
-                if (indexState.status === "error") {
+                if (indexState.status === 'error') {
                     return {
                         content: [
                             {
-                                type: "text",
+                                type: 'text',
                                 text: JSON.stringify({
-                                    status: "error",
-                                    message: `Indexing failed: ${indexState.error}`,
-                                }, null, 2),
-                            },
-                        ],
+                                    status: 'error',
+                                    message: `Indexing failed: ${indexState.error}`
+                                }, null, 2)
+                            }
+                        ]
                     };
                 }
                 const searcher = new CodebaseSearcher(ROOT_PATH);
-                const results = await searcher.search(query, limit || 5, filters);
+                let results;
+                try {
+                    results = await searcher.search(query, limit || 5, filters);
+                }
+                catch (error) {
+                    if (error instanceof IndexCorruptedError) {
+                        console.error('[Auto-Heal] Index corrupted. Triggering full re-index...');
+                        await performIndexing();
+                        if (indexState.status === 'ready') {
+                            console.error('[Auto-Heal] Success. Retrying search...');
+                            const freshSearcher = new CodebaseSearcher(ROOT_PATH);
+                            try {
+                                results = await freshSearcher.search(query, limit || 5, filters);
+                            }
+                            catch (retryError) {
+                                return {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: JSON.stringify({
+                                                status: 'error',
+                                                message: `Auto-heal retry failed: ${retryError instanceof Error ? retryError.message : String(retryError)}`
+                                            }, null, 2)
+                                        }
+                                    ]
+                                };
+                            }
+                        }
+                        else {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: JSON.stringify({
+                                            status: 'error',
+                                            message: `Auto-heal failed: Indexing ended with status '${indexState.status}'`,
+                                            error: indexState.error
+                                        }, null, 2)
+                                    }
+                                ]
+                            };
+                        }
+                    }
+                    else {
+                        throw error; // Propagate unexpected errors
+                    }
+                }
+                // Load memories for keyword matching
+                const allMemories = await readMemoriesFile(PATHS.memory);
+                const findRelatedMemories = (queryTerms) => {
+                    return allMemories.filter((m) => {
+                        const searchText = `${m.memory} ${m.reason}`.toLowerCase();
+                        return queryTerms.some((term) => searchText.includes(term));
+                    });
+                };
+                const queryTerms = query.toLowerCase().split(/\s+/);
+                const relatedMemories = findRelatedMemories(queryTerms);
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: JSON.stringify({
-                                status: "success",
+                                status: 'success',
                                 results: results.map((r) => ({
                                     summary: r.summary,
                                     snippet: r.snippet,
@@ -414,22 +610,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                     componentType: r.componentType,
                                     layer: r.layer,
                                     framework: r.framework,
-                                    // v1.2: Pattern momentum awareness
                                     trend: r.trend,
-                                    patternWarning: r.patternWarning,
+                                    patternWarning: r.patternWarning
                                 })),
                                 totalResults: results.length,
-                            }, null, 2),
-                        },
-                    ],
+                                ...(relatedMemories.length > 0 && { relatedMemories })
+                            }, null, 2)
+                        }
+                    ]
                 };
             }
-            case "get_indexing_status": {
+            case 'get_indexing_status': {
                 const progress = indexState.indexer?.getProgress();
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: JSON.stringify({
                                 status: indexState.status,
                                 rootPath: ROOT_PATH,
@@ -439,7 +635,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                         totalFiles: indexState.stats.totalFiles,
                                         indexedFiles: indexState.stats.indexedFiles,
                                         totalChunks: indexState.stats.totalChunks,
-                                        duration: `${(indexState.stats.duration / 1000).toFixed(2)}s`,
+                                        duration: `${(indexState.stats.duration / 1000).toFixed(2)}s`
                                     }
                                     : undefined,
                                 progress: progress
@@ -447,20 +643,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                         phase: progress.phase,
                                         percentage: progress.percentage,
                                         filesProcessed: progress.filesProcessed,
-                                        totalFiles: progress.totalFiles,
+                                        totalFiles: progress.totalFiles
                                     }
                                     : undefined,
                                 error: indexState.error,
-                                hint: "Use refresh_index to manually trigger re-indexing when needed.",
-                            }, null, 2),
-                        },
-                    ],
+                                hint: 'Use refresh_index to manually trigger re-indexing when needed.'
+                            }, null, 2)
+                        }
+                    ]
                 };
             }
-            case "refresh_index": {
+            case 'refresh_index': {
                 const { reason, incrementalOnly } = args;
-                const mode = incrementalOnly ? "incremental" : "full";
-                console.error(`Refresh requested (${mode}): ${reason || "Manual trigger"}`);
+                const mode = incrementalOnly ? 'incremental' : 'full';
+                console.error(`Refresh requested (${mode}): ${reason || 'Manual trigger'}`);
                 // TODO: When incremental indexing is implemented (Phase 2),
                 // use `incrementalOnly` to only re-index changed files.
                 // For now, always do full re-index but acknowledge the intention.
@@ -468,48 +664,48 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: JSON.stringify({
-                                status: "started",
+                                status: 'started',
                                 mode,
                                 message: incrementalOnly
-                                    ? "Incremental re-indexing requested. Check status with get_indexing_status."
-                                    : "Full re-indexing started. Check status with get_indexing_status.",
+                                    ? 'Incremental re-indexing requested. Check status with get_indexing_status.'
+                                    : 'Full re-indexing started. Check status with get_indexing_status.',
                                 reason,
                                 note: incrementalOnly
-                                    ? "Incremental mode requested. Full re-index for now; true incremental indexing coming in Phase 2."
-                                    : undefined,
-                            }, null, 2),
-                        },
-                    ],
+                                    ? 'Incremental mode requested. Full re-index for now; true incremental indexing coming in Phase 2.'
+                                    : undefined
+                            }, null, 2)
+                        }
+                    ]
                 };
             }
-            case "get_codebase_metadata": {
+            case 'get_codebase_metadata': {
                 const indexer = new CodebaseIndexer({ rootPath: ROOT_PATH });
                 const metadata = await indexer.detectMetadata();
                 // Load team patterns from intelligence file
                 let teamPatterns = {};
                 try {
-                    const intelligencePath = path.join(ROOT_PATH, ".codebase-intelligence.json");
-                    const intelligenceContent = await fs.readFile(intelligencePath, "utf-8");
+                    const intelligencePath = PATHS.intelligence;
+                    const intelligenceContent = await fs.readFile(intelligencePath, 'utf-8');
                     const intelligence = JSON.parse(intelligenceContent);
                     if (intelligence.patterns) {
                         teamPatterns = {
                             dependencyInjection: intelligence.patterns.dependencyInjection,
                             stateManagement: intelligence.patterns.stateManagement,
-                            componentInputs: intelligence.patterns.componentInputs,
+                            componentInputs: intelligence.patterns.componentInputs
                         };
                     }
                 }
-                catch (error) {
+                catch (_error) {
                     // No intelligence file or parsing error
                 }
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: JSON.stringify({
-                                status: "success",
+                                status: 'success',
                                 metadata: {
                                     name: metadata.name,
                                     framework: metadata.framework,
@@ -518,23 +714,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                     architecture: metadata.architecture,
                                     projectStructure: metadata.projectStructure,
                                     statistics: metadata.statistics,
-                                    teamPatterns,
-                                },
-                            }, null, 2),
-                        },
-                    ],
+                                    teamPatterns
+                                }
+                            }, null, 2)
+                        }
+                    ]
                 };
             }
-            case "get_style_guide": {
+            case 'get_style_guide': {
                 const { query, category } = args;
                 const styleGuidePatterns = [
-                    "STYLE_GUIDE.md",
-                    "CODING_STYLE.md",
-                    "ARCHITECTURE.md",
-                    "CONTRIBUTING.md",
-                    "docs/style-guide.md",
-                    "docs/coding-style.md",
-                    "docs/ARCHITECTURE.md",
+                    'STYLE_GUIDE.md',
+                    'CODING_STYLE.md',
+                    'ARCHITECTURE.md',
+                    'CONTRIBUTING.md',
+                    'docs/style-guide.md',
+                    'docs/coding-style.md',
+                    'docs/ARCHITECTURE.md'
                 ];
                 const foundGuides = [];
                 const queryLower = query.toLowerCase();
@@ -543,13 +739,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     try {
                         const files = await glob(pattern, {
                             cwd: ROOT_PATH,
-                            absolute: true,
+                            absolute: true
                         });
                         for (const file of files) {
                             try {
                                 // Normalize line endings to \n for consistent output
-                                const rawContent = await fs.readFile(file, "utf-8");
-                                const content = rawContent.replace(/\r\n/g, "\n");
+                                const rawContent = await fs.readFile(file, 'utf-8');
+                                const content = rawContent.replace(/\r\n/g, '\n');
                                 const relativePath = path.relative(ROOT_PATH, file);
                                 // Find relevant sections based on query
                                 const sections = content.split(/^##\s+/m);
@@ -560,27 +756,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                     if (isRelevant) {
                                         // Limit section size to ~500 words
                                         const words = section.split(/\s+/);
-                                        const truncated = words.slice(0, 500).join(" ");
-                                        relevantSections.push("## " +
-                                            (words.length > 500
-                                                ? truncated + "..."
-                                                : section.trim()));
+                                        const truncated = words.slice(0, 500).join(' ');
+                                        relevantSections.push('## ' + (words.length > 500 ? truncated + '...' : section.trim()));
                                     }
                                 }
                                 if (relevantSections.length > 0) {
                                     foundGuides.push({
                                         file: relativePath,
-                                        content: content.slice(0, 200) + "...",
-                                        relevantSections: relevantSections.slice(0, 3), // Max 3 sections per file
+                                        content: content.slice(0, 200) + '...',
+                                        relevantSections: relevantSections.slice(0, 3) // Max 3 sections per file
                                     });
                                 }
                             }
-                            catch (e) {
+                            catch (_e) {
                                 // Skip unreadable files
                             }
                         }
                     }
-                    catch (e) {
+                    catch (_e) {
                         // Pattern didn't match, continue
                     }
                 }
@@ -588,86 +781,106 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return {
                         content: [
                             {
-                                type: "text",
+                                type: 'text',
                                 text: JSON.stringify({
-                                    status: "no_results",
+                                    status: 'no_results',
                                     message: `No style guide content found matching: ${query}`,
                                     searchedPatterns: styleGuidePatterns,
-                                    hint: "Try broader terms like 'naming', 'patterns', 'testing', 'components'",
-                                }, null, 2),
-                            },
-                        ],
+                                    hint: "Try broader terms like 'naming', 'patterns', 'testing', 'components'"
+                                }, null, 2)
+                            }
+                        ]
                     };
                 }
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: JSON.stringify({
-                                status: "success",
+                                status: 'success',
                                 query,
                                 category,
                                 results: foundGuides,
-                                totalFiles: foundGuides.length,
-                            }, null, 2),
-                        },
-                    ],
+                                totalFiles: foundGuides.length
+                            }, null, 2)
+                        }
+                    ]
                 };
             }
-            case "get_team_patterns": {
+            case 'get_team_patterns': {
                 const { category } = args;
                 try {
-                    const intelligencePath = path.join(ROOT_PATH, ".codebase-intelligence.json");
-                    const content = await fs.readFile(intelligencePath, "utf-8");
+                    const intelligencePath = PATHS.intelligence;
+                    const content = await fs.readFile(intelligencePath, 'utf-8');
                     const intelligence = JSON.parse(content);
-                    const result = { status: "success" };
-                    if (category === "all" || !category) {
+                    const result = { status: 'success' };
+                    if (category === 'all' || !category) {
                         result.patterns = intelligence.patterns || {};
                         result.goldenFiles = intelligence.goldenFiles || [];
                         if (intelligence.tsconfigPaths) {
                             result.tsconfigPaths = intelligence.tsconfigPaths;
                         }
                     }
-                    else if (category === "di") {
+                    else if (category === 'di') {
                         result.dependencyInjection = intelligence.patterns?.dependencyInjection;
                     }
-                    else if (category === "state") {
+                    else if (category === 'state') {
                         result.stateManagement = intelligence.patterns?.stateManagement;
                     }
-                    else if (category === "testing") {
+                    else if (category === 'testing') {
                         result.testingFramework = intelligence.patterns?.testingFramework;
                         result.testMocking = intelligence.patterns?.testMocking;
                     }
-                    else if (category === "libraries") {
+                    else if (category === 'libraries') {
                         result.topUsed = intelligence.importGraph?.topUsed || [];
                         if (intelligence.tsconfigPaths) {
                             result.tsconfigPaths = intelligence.tsconfigPaths;
                         }
                     }
+                    // Load and append matching memories
+                    try {
+                        const allMemories = await readMemoriesFile(PATHS.memory);
+                        // Map pattern categories to decision categories
+                        const categoryMap = {
+                            all: ['tooling', 'architecture', 'testing', 'dependencies', 'conventions'],
+                            di: ['architecture', 'conventions'],
+                            state: ['architecture', 'conventions'],
+                            testing: ['testing'],
+                            libraries: ['dependencies']
+                        };
+                        const relevantCategories = categoryMap[category || 'all'] || [];
+                        const matchingMemories = allMemories.filter((m) => relevantCategories.includes(m.category));
+                        if (matchingMemories.length > 0) {
+                            result.memories = matchingMemories;
+                        }
+                    }
+                    catch (_error) {
+                        // No memory file yet, that's fine - don't fail the whole request
+                    }
                     return {
-                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
                     };
                 }
                 catch (error) {
                     return {
                         content: [
                             {
-                                type: "text",
+                                type: 'text',
                                 text: JSON.stringify({
-                                    status: "error",
-                                    message: "Failed to load team patterns",
-                                    error: error instanceof Error ? error.message : String(error),
-                                }, null, 2),
-                            },
-                        ],
+                                    status: 'error',
+                                    message: 'Failed to load team patterns',
+                                    error: error instanceof Error ? error.message : String(error)
+                                }, null, 2)
+                            }
+                        ]
                     };
                 }
             }
-            case "get_component_usage": {
+            case 'get_component_usage': {
                 const { name: componentName } = args;
                 try {
-                    const intelligencePath = path.join(ROOT_PATH, ".codebase-intelligence.json");
-                    const content = await fs.readFile(intelligencePath, "utf-8");
+                    const intelligencePath = PATHS.intelligence;
+                    const content = await fs.readFile(intelligencePath, 'utf-8');
                     const intelligence = JSON.parse(content);
                     const importGraph = intelligence.importGraph || {};
                     const usages = importGraph.usages || {};
@@ -675,68 +888,76 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     let matchedUsage = usages[componentName];
                     // Try partial match if exact match not found
                     if (!matchedUsage) {
-                        const matchingKeys = Object.keys(usages).filter(key => key.includes(componentName) || componentName.includes(key));
+                        const matchingKeys = Object.keys(usages).filter((key) => key.includes(componentName) || componentName.includes(key));
                         if (matchingKeys.length > 0) {
                             matchedUsage = usages[matchingKeys[0]];
                         }
                     }
                     if (matchedUsage) {
                         return {
-                            content: [{
-                                    type: "text",
+                            content: [
+                                {
+                                    type: 'text',
                                     text: JSON.stringify({
-                                        status: "success",
+                                        status: 'success',
                                         component: componentName,
                                         usageCount: matchedUsage.usageCount,
-                                        usedIn: matchedUsage.usedIn,
-                                    }, null, 2),
-                                }],
+                                        usedIn: matchedUsage.usedIn
+                                    }, null, 2)
+                                }
+                            ]
                         };
                     }
                     else {
                         // Show top used as alternatives
                         const topUsed = importGraph.topUsed || [];
                         return {
-                            content: [{
-                                    type: "text",
+                            content: [
+                                {
+                                    type: 'text',
                                     text: JSON.stringify({
-                                        status: "not_found",
+                                        status: 'not_found',
                                         component: componentName,
                                         message: `No usages found for '${componentName}'.`,
-                                        suggestions: topUsed.slice(0, 10),
-                                    }, null, 2),
-                                }],
+                                        suggestions: topUsed.slice(0, 10)
+                                    }, null, 2)
+                                }
+                            ]
                         };
                     }
                 }
                 catch (error) {
                     return {
-                        content: [{
-                                type: "text",
+                        content: [
+                            {
+                                type: 'text',
                                 text: JSON.stringify({
-                                    status: "error",
-                                    message: "Failed to get component usage. Run indexing first.",
-                                    error: error instanceof Error ? error.message : String(error),
-                                }, null, 2),
-                            }],
+                                    status: 'error',
+                                    message: 'Failed to get component usage. Run indexing first.',
+                                    error: error instanceof Error ? error.message : String(error)
+                                }, null, 2)
+                            }
+                        ]
                     };
                 }
             }
-            case "detect_circular_dependencies": {
+            case 'detect_circular_dependencies': {
                 const { scope } = args;
                 try {
-                    const intelligencePath = path.join(ROOT_PATH, ".codebase-intelligence.json");
-                    const content = await fs.readFile(intelligencePath, "utf-8");
+                    const intelligencePath = PATHS.intelligence;
+                    const content = await fs.readFile(intelligencePath, 'utf-8');
                     const intelligence = JSON.parse(content);
                     if (!intelligence.internalFileGraph) {
                         return {
-                            content: [{
-                                    type: "text",
+                            content: [
+                                {
+                                    type: 'text',
                                     text: JSON.stringify({
-                                        status: "error",
-                                        message: "Internal file graph not found. Please run refresh_index to rebuild the index with cycle detection support.",
-                                    }, null, 2),
-                                }],
+                                        status: 'error',
+                                        message: 'Internal file graph not found. Please run refresh_index to rebuild the index with cycle detection support.'
+                                    }, null, 2)
+                                }
+                            ]
                         };
                     }
                     // Reconstruct the graph from stored data
@@ -745,48 +966,169 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const graphStats = intelligence.internalFileGraph.stats || graph.getStats();
                     if (cycles.length === 0) {
                         return {
-                            content: [{
-                                    type: "text",
+                            content: [
+                                {
+                                    type: 'text',
                                     text: JSON.stringify({
-                                        status: "success",
+                                        status: 'success',
                                         message: scope
                                             ? `No circular dependencies detected in scope: ${scope}`
-                                            : "No circular dependencies detected in the codebase.",
+                                            : 'No circular dependencies detected in the codebase.',
                                         scope,
-                                        graphStats,
-                                    }, null, 2),
-                                }],
+                                        graphStats
+                                    }, null, 2)
+                                }
+                            ]
                         };
                     }
                     return {
-                        content: [{
-                                type: "text",
+                        content: [
+                            {
+                                type: 'text',
                                 text: JSON.stringify({
-                                    status: "warning",
+                                    status: 'warning',
                                     message: `Found ${cycles.length} circular dependency cycle(s).`,
                                     scope,
-                                    cycles: cycles.map(c => ({
+                                    cycles: cycles.map((c) => ({
                                         files: c.files,
                                         length: c.length,
-                                        severity: c.length === 2 ? "high" : c.length <= 3 ? "medium" : "low",
+                                        severity: c.length === 2 ? 'high' : c.length <= 3 ? 'medium' : 'low'
                                     })),
                                     count: cycles.length,
                                     graphStats,
-                                    advice: "Shorter cycles (length 2-3) are typically more problematic. Consider breaking the cycle by extracting shared dependencies.",
-                                }, null, 2),
-                            }],
+                                    advice: 'Shorter cycles (length 2-3) are typically more problematic. Consider breaking the cycle by extracting shared dependencies.'
+                                }, null, 2)
+                            }
+                        ]
                     };
                 }
                 catch (error) {
                     return {
-                        content: [{
-                                type: "text",
+                        content: [
+                            {
+                                type: 'text',
                                 text: JSON.stringify({
-                                    status: "error",
-                                    message: "Failed to detect circular dependencies. Run indexing first.",
-                                    error: error instanceof Error ? error.message : String(error),
-                                }, null, 2),
-                            }],
+                                    status: 'error',
+                                    message: 'Failed to detect circular dependencies. Run indexing first.',
+                                    error: error instanceof Error ? error.message : String(error)
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+            }
+            case 'remember': {
+                const args_typed = args;
+                const { type = 'decision', category, memory, reason } = args_typed;
+                try {
+                    const crypto = await import('crypto');
+                    const memoryPath = PATHS.memory;
+                    const hashContent = `${type}:${category}:${memory}:${reason}`;
+                    const hash = crypto.createHash('sha256').update(hashContent).digest('hex');
+                    const id = hash.substring(0, 12);
+                    const newMemory = {
+                        id,
+                        type,
+                        category,
+                        memory,
+                        reason,
+                        date: new Date().toISOString()
+                    };
+                    const result = await appendMemoryFile(memoryPath, newMemory);
+                    if (result.status === 'duplicate') {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        status: 'info',
+                                        message: 'This memory was already recorded.',
+                                        memory: result.memory
+                                    }, null, 2)
+                                }
+                            ]
+                        };
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'success',
+                                    message: 'Memory recorded successfully.',
+                                    memory: result.memory
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'error',
+                                    message: 'Failed to record memory.',
+                                    error: error instanceof Error ? error.message : String(error)
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+            }
+            case 'get_memory': {
+                const { category, type, query } = args;
+                try {
+                    const memoryPath = PATHS.memory;
+                    const allMemories = await readMemoriesFile(memoryPath);
+                    if (allMemories.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        status: 'success',
+                                        message: "No team conventions recorded yet. Use 'remember' to build tribal knowledge or memory when the user corrects you over a repeatable pattern.",
+                                        memories: [],
+                                        count: 0
+                                    }, null, 2)
+                                }
+                            ]
+                        };
+                    }
+                    const filtered = filterMemories(allMemories, { category, type, query });
+                    const limited = applyUnfilteredLimit(filtered, { category, type, query }, 20);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'success',
+                                    count: limited.memories.length,
+                                    totalCount: limited.totalCount,
+                                    truncated: limited.truncated,
+                                    message: limited.truncated
+                                        ? 'Showing 20 most recent. Use filters (category/type/query) for targeted results.'
+                                        : undefined,
+                                    memories: limited.memories
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'error',
+                                    message: 'Failed to retrieve memories.',
+                                    error: error instanceof Error ? error.message : String(error)
+                                }, null, 2)
+                            }
+                        ]
                     };
                 }
             }
@@ -794,13 +1136,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: JSON.stringify({
-                                error: `Unknown tool: ${name}`,
-                            }, null, 2),
-                        },
+                                error: `Unknown tool: ${name}`
+                            }, null, 2)
+                        }
                     ],
-                    isError: true,
+                    isError: true
                 };
         }
     }
@@ -808,27 +1150,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return {
             content: [
                 {
-                    type: "text",
+                    type: 'text',
                     text: JSON.stringify({
                         error: error instanceof Error ? error.message : String(error),
-                        stack: error instanceof Error ? error.stack : undefined,
-                    }, null, 2),
-                },
+                        stack: error instanceof Error ? error.stack : undefined
+                    }, null, 2)
+                }
             ],
-            isError: true,
+            isError: true
         };
     }
 });
 async function main() {
-    // Server startup banner (guarded to avoid stderr during MCP STDIO handshake)
-    if (process.env.CODEBASE_CONTEXT_DEBUG) {
-        console.error("[DEBUG] Codebase Context MCP Server");
-        console.error(`[DEBUG] Root: ${ROOT_PATH}`);
-        console.error(`[DEBUG] Analyzers: ${analyzerRegistry
-            .getAll()
-            .map((a) => a.name)
-            .join(", ")}`);
-    }
     // Validate root path exists and is a directory
     try {
         const stats = await fs.stat(ROOT_PATH);
@@ -838,15 +1171,37 @@ async function main() {
             process.exit(1);
         }
     }
-    catch (error) {
+    catch (_error) {
         console.error(`ERROR: Root path does not exist: ${ROOT_PATH}`);
         console.error(`Please specify a valid project directory.`);
         process.exit(1);
     }
+    // Migrate legacy structure before server starts
+    try {
+        const migrated = await migrateToNewStructure();
+        if (migrated && process.env.CODEBASE_CONTEXT_DEBUG) {
+            console.error('[DEBUG] Migrated to .codebase-context/ structure');
+        }
+    }
+    catch (error) {
+        // Non-fatal: continue with current paths
+        if (process.env.CODEBASE_CONTEXT_DEBUG) {
+            console.error('[DEBUG] Migration failed:', error);
+        }
+    }
+    // Server startup banner (guarded to avoid stderr during MCP STDIO handshake)
+    if (process.env.CODEBASE_CONTEXT_DEBUG) {
+        console.error('[DEBUG] Codebase Context MCP Server');
+        console.error(`[DEBUG] Root: ${ROOT_PATH}`);
+        console.error(`[DEBUG] Analyzers: ${analyzerRegistry
+            .getAll()
+            .map((a) => a.name)
+            .join(', ')}`);
+    }
     // Check for package.json to confirm it's a project root (guarded to avoid stderr during handshake)
     if (process.env.CODEBASE_CONTEXT_DEBUG) {
         try {
-            await fs.access(path.join(ROOT_PATH, "package.json"));
+            await fs.access(path.join(ROOT_PATH, 'package.json'));
             console.error(`[DEBUG] Project detected: ${path.basename(ROOT_PATH)}`);
         }
         catch {
@@ -856,29 +1211,29 @@ async function main() {
     const needsIndex = await shouldReindex();
     if (needsIndex) {
         if (process.env.CODEBASE_CONTEXT_DEBUG)
-            console.error("[DEBUG] Starting indexing...");
+            console.error('[DEBUG] Starting indexing...');
         performIndexing();
     }
     else {
         if (process.env.CODEBASE_CONTEXT_DEBUG)
-            console.error("[DEBUG] Index found. Ready.");
-        indexState.status = "ready";
+            console.error('[DEBUG] Index found. Ready.');
+        indexState.status = 'ready';
         indexState.lastIndexed = new Date();
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     if (process.env.CODEBASE_CONTEXT_DEBUG)
-        console.error("[DEBUG] Server ready");
+        console.error('[DEBUG] Server ready');
 }
 // Export server components for programmatic use
 export { server, performIndexing, resolveRootPath, shouldReindex, TOOLS };
 // Only auto-start when run directly as CLI (not when imported as module)
 // Check if this module is the entry point
-const isDirectRun = process.argv[1]?.replace(/\\/g, "/").endsWith("index.js") ||
-    process.argv[1]?.replace(/\\/g, "/").endsWith("index.ts");
+const isDirectRun = process.argv[1]?.replace(/\\/g, '/').endsWith('index.js') ||
+    process.argv[1]?.replace(/\\/g, '/').endsWith('index.ts');
 if (isDirectRun) {
     main().catch((error) => {
-        console.error("Fatal:", error);
+        console.error('Fatal:', error);
         process.exit(1);
     });
 }