codebase-context 1.6.0 → 1.6.2

package/dist/index.js

@@ -16,10 +16,10 @@ 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 { getFileCommitDates } from './utils/git-dates.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, withConfidence } from './memory/store.js';
+import { handleMemoryCli } from './cli.js';
 import { parseGitLogLineToMemory } from './memory/git-memory.js';
 import { buildEvidenceLock } from './preflight/evidence-lock.js';
 import { shouldIncludePatternConflictCategory } from './preflight/query-scope.js';
@@ -132,11 +132,8 @@ const server = new Server({
 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. ' +
-            'When intent is "edit", "refactor", or "migrate", returns a preflight card with risk level, ' +
-            'patterns to use/avoid, impact candidates, related memories, and an evidence lock score — all in one call. ' +
-            'Use the returned filePath with other tools to read complete file contents.',
+        description: 'Search the indexed codebase. Returns ranked results and a searchQuality confidence summary. ' +
+            'IMPORTANT: Pass the intent="edit"|"refactor"|"migrate" to get preflight: edit readiness check with evidence gating.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -147,15 +144,18 @@ const TOOLS = [
                 intent: {
                     type: 'string',
                     enum: ['explore', 'edit', 'refactor', 'migrate'],
-                    description: 'Search intent. Use "explore" (default) for read-only browsing. ' +
-                        'Use "edit", "refactor", or "migrate" to get a preflight card with risk assessment, ' +
-                        'patterns to prefer/avoid, affected files, relevant team memories, and ready-to-edit evidence checks.'
+                    description: 'Optional. Use "edit", "refactor", or "migrate" to get the full preflight card before making changes.'
                 },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of results to return (default: 5)',
                     default: 5
                 },
+                includeSnippets: {
+                    type: 'boolean',
+                    description: 'Include code snippets in results (default: false). If you need code, prefer read_file instead.',
+                    default: false
+                },
                 filters: {
                     type: 'object',
                     description: 'Optional filters',
@@ -237,8 +237,7 @@ const TOOLS = [
                     type: 'string',
                     description: 'Filter by category (naming, structure, patterns, testing)'
                 }
-            },
-            required: ['query']
+            }
         }
     },
     {
@@ -260,7 +259,7 @@ const TOOLS = [
         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.",
+            "Example: get_component_usage('@mycompany/utils') -> shows all files using it.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -289,24 +288,24 @@ const TOOLS = [
     },
     {
         name: 'remember',
-        description: '📝 CALL IMMEDIATELY when user explicitly asks to remember/record something.\n\n' +
+        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' +
+            '- "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',
+            '- 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', 'failure'],
-                    description: 'Type of memory being recorded. Use "failure" for things that were tried and failed — ' +
+                    description: 'Type of memory being recorded. Use "failure" for things that were tried and failed - ' +
                         'prevents repeating the same mistakes.'
                 },
                 category: {
@@ -376,7 +375,7 @@ async function generateCodebaseContext() {
         const lines = [];
         lines.push('# Codebase Intelligence');
         lines.push('');
-        lines.push('⚠️  CRITICAL: This is what YOUR codebase actually uses, not generic recommendations.');
+        lines.push('WARNING: 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
@@ -400,7 +399,7 @@ async function generateCodebaseContext() {
             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('');
         }
@@ -429,8 +428,8 @@ async function generateCodebaseContext() {
                             .trim()
                             .replace(/^./, (str) => str.toUpperCase());
                         lines.push(`### ${categoryName}: **${primary.name}** (${primary.frequency}) + **${secondary.name}** (${secondary.frequency})`);
-                        lines.push('   → Computed and effect are complementary Signals primitives and are commonly used together.');
-                        lines.push('   → Treat this as balanced usage, not a hard split decision.');
+                        lines.push('   -> Computed and effect are complementary Signals primitives and are commonly used together.');
+                        lines.push('   -> Treat this as balanced usage, not a hard split decision.');
                         lines.push('');
                         continue;
                     }
@@ -442,26 +441,26 @@ async function generateCodebaseContext() {
                     .replace(/^./, (str) => str.toUpperCase());
                 if (percentage === 100) {
                     lines.push(`### ${categoryName}: **${primary.name}** (${primary.frequency} - unanimous)`);
-                    lines.push(`   → Your codebase is 100% consistent - ALWAYS use ${primary.name}`);
+                    lines.push(`   -> Your codebase is 100% consistent - ALWAYS use ${primary.name}`);
                 }
                 else if (percentage >= 80) {
                     lines.push(`### ${categoryName}: **${primary.name}** (${primary.frequency} - strong consensus)`);
-                    lines.push(`   → Your team strongly prefers ${primary.name}`);
+                    lines.push(`   -> Your team strongly prefers ${primary.name}`);
                     if (alternatives.length) {
                         const alt = alternatives[0];
-                        lines.push(`   → Minority pattern: ${alt.name} (${alt.frequency}) - avoid for new code`);
+                        lines.push(`   -> Minority pattern: ${alt.name} (${alt.frequency}) - avoid for new code`);
                     }
                 }
                 else if (percentage >= 60) {
                     lines.push(`### ${categoryName}: **${primary.name}** (${primary.frequency} - majority)`);
-                    lines.push(`   → Most code uses ${primary.name}, but not unanimous`);
+                    lines.push(`   -> Most code uses ${primary.name}, but not unanimous`);
                     if (alternatives.length) {
-                        lines.push(`   → Also detected: ${alternatives[0].name} (${alternatives[0].frequency})`);
+                        lines.push(`   -> Also detected: ${alternatives[0].name} (${alternatives[0].frequency})`);
                     }
                 }
                 else {
                     // Split decision
-                    lines.push(`### ${categoryName}: ⚠️ NO TEAM CONSENSUS`);
+                    lines.push(`### ${categoryName}: WARNING: NO TEAM CONSENSUS`);
                     lines.push(`   Your codebase is split between multiple approaches:`);
                     lines.push(`   - ${primary.name} (${primary.frequency})`);
                     if (alternatives.length) {
@@ -469,7 +468,7 @@ async function generateCodebaseContext() {
                             lines.push(`   - ${alt.name} (${alt.frequency})`);
                         }
                     }
-                    lines.push(`   → ASK the team which approach to use for new features`);
+                    lines.push(`   -> ASK the team which approach to use for new features`);
                 }
                 lines.push('');
             }
@@ -593,7 +592,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         switch (name) {
             case 'search_codebase': {
-                const { query, limit, filters, intent } = args;
+                const { query, limit, filters, intent, includeSnippets } = args;
+                const queryStr = typeof query === 'string' ? query.trim() : '';
+                if (!queryStr) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'error',
+                                    errorCode: 'invalid_params',
+                                    message: "Invalid params: 'query' is required and must be a non-empty string.",
+                                    hint: "Provide a query like 'how are routes configured' or 'AlbumApiService'."
+                                }, null, 2)
+                            }
+                        ],
+                        isError: true
+                    };
+                }
                 if (indexState.status === 'indexing') {
                     return {
                         content: [
@@ -627,7 +643,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ? intent
                     : 'explore';
                 try {
-                    results = await searcher.search(query, limit || 5, filters, {
+                    results = await searcher.search(queryStr, limit || 5, filters, {
                         profile: searchProfile
                     });
                 }
@@ -639,7 +655,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             console.error('[Auto-Heal] Success. Retrying search...');
                             const freshSearcher = new CodebaseSearcher(ROOT_PATH);
                             try {
-                                results = await freshSearcher.search(query, limit || 5, filters, {
+                                results = await freshSearcher.search(queryStr, limit || 5, filters, {
                                     profile: searchProfile
                                 });
                             }
@@ -679,7 +695,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 // Load memories for keyword matching, enriched with confidence
                 const allMemories = await readMemoriesFile(PATHS.memory);
                 const allMemoriesWithConf = withConfidence(allMemories);
-                const queryTerms = query.toLowerCase().split(/\s+/);
+                const queryTerms = queryStr.toLowerCase().split(/\s+/).filter(Boolean);
                 const relatedMemories = allMemoriesWithConf
                     .filter((m) => {
                     const searchText = `${m.memory} ${m.reason}`.toLowerCase();
@@ -695,6 +711,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 catch {
                     /* graceful degradation — intelligence file may not exist yet */
                 }
+                function computeIndexConfidence() {
+                    let confidence = 'stale';
+                    if (intelligence?.generatedAt) {
+                        const indexAge = Date.now() - new Date(intelligence.generatedAt).getTime();
+                        const hoursOld = indexAge / (1000 * 60 * 60);
+                        if (hoursOld < 24) {
+                            confidence = 'fresh';
+                        }
+                        else if (hoursOld < 168) {
+                            confidence = 'aging';
+                        }
+                    }
+                    return confidence;
+                }
+                // Cheap impact breadth estimate from the import graph (used for risk assessment).
+                function computeImpactCandidates(resultPaths) {
+                    const impactCandidates = [];
+                    if (!intelligence?.internalFileGraph?.imports)
+                        return impactCandidates;
+                    const allImports = intelligence.internalFileGraph.imports;
+                    for (const [file, deps] of Object.entries(allImports)) {
+                        if (deps.some((dep) => resultPaths.some((rp) => dep.endsWith(rp) || rp.endsWith(dep)))) {
+                            if (!resultPaths.some((rp) => file.endsWith(rp) || rp.endsWith(file))) {
+                                impactCandidates.push(file);
+                            }
+                        }
+                    }
+                    return impactCandidates;
+                }
                 // Build reverse import map from intelligence graph
                 const reverseImports = new Map();
                 if (intelligence?.internalFileGraph?.imports) {
@@ -706,14 +751,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         }
                     }
                 }
-                // Load git dates for lastModified enrichment
-                let gitDates = null;
-                try {
-                    gitDates = await getFileCommitDates(ROOT_PATH);
-                }
-                catch {
-                    /* not a git repo */
-                }
                 // Enrich a search result with relationship data
                 function enrichResult(r) {
                     const rPath = r.filePath;
@@ -745,31 +782,62 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             }
                         }
                     }
-                    // lastModified: from git dates
-                    let lastModified;
-                    if (gitDates) {
-                        // Try matching by relative path (git dates use repo-relative forward-slash paths)
-                        const relPath = path.relative(ROOT_PATH, rPath).replace(/\\/g, '/');
-                        const date = gitDates.get(relPath);
-                        if (date) {
-                            lastModified = date.toISOString();
-                        }
-                    }
                     // Only return if we have at least one piece of data
-                    if (importedBy.length === 0 &&
-                        imports.length === 0 &&
-                        testedIn.length === 0 &&
-                        !lastModified) {
+                    if (importedBy.length === 0 && imports.length === 0 && testedIn.length === 0) {
                         return undefined;
                     }
                     return {
                         ...(importedBy.length > 0 && { importedBy }),
                         ...(imports.length > 0 && { imports }),
-                        ...(testedIn.length > 0 && { testedIn }),
-                        ...(lastModified && { lastModified })
+                        ...(testedIn.length > 0 && { testedIn })
                     };
                 }
                 const searchQuality = assessSearchQuality(query, results);
+                // Always-on edit preflight (lite): do not require intent and keep payload small.
+                let editPreflight = undefined;
+                if (intelligence && (!intent || intent === 'explore')) {
+                    try {
+                        const resultPaths = results.map((r) => r.filePath);
+                        const impactCandidates = computeImpactCandidates(resultPaths);
+                        let riskLevel = 'low';
+                        if (impactCandidates.length > 10) {
+                            riskLevel = 'high';
+                        }
+                        else if (impactCandidates.length > 3) {
+                            riskLevel = 'medium';
+                        }
+                        // Use existing pattern intelligence for evidenceLock scoring, but keep the output payload lite.
+                        const preferredPatternsForEvidence = [];
+                        const patterns = intelligence.patterns || {};
+                        for (const [_, data] of Object.entries(patterns)) {
+                            if (data.primary) {
+                                const p = data.primary;
+                                if (p.trend === 'Rising' || p.trend === 'Stable') {
+                                    preferredPatternsForEvidence.push({
+                                        pattern: p.name,
+                                        ...(p.canonicalExample && { example: p.canonicalExample.file })
+                                    });
+                                }
+                            }
+                        }
+                        editPreflight = {
+                            mode: 'lite',
+                            riskLevel,
+                            confidence: computeIndexConfidence(),
+                            evidenceLock: buildEvidenceLock({
+                                results,
+                                preferredPatterns: preferredPatternsForEvidence.slice(0, 5),
+                                relatedMemories,
+                                failureWarnings: [],
+                                patternConflicts: [],
+                                searchQualityStatus: searchQuality.status
+                            })
+                        };
+                    }
+                    catch {
+                        // editPreflight is best-effort - never fail search over it
+                    }
+                }
                 // Compose preflight card for edit/refactor/migrate intents
                 let preflight = undefined;
                 const preflightIntents = ['edit', 'refactor', 'migrate'];
@@ -810,18 +878,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             }
                         }
                         // --- Impact candidates (files importing the result files) ---
-                        const impactCandidates = [];
                         const resultPaths = results.map((r) => r.filePath);
-                        if (intelligence.internalFileGraph?.imports) {
-                            const allImports = intelligence.internalFileGraph.imports;
-                            for (const [file, deps] of Object.entries(allImports)) {
-                                if (deps.some((dep) => resultPaths.some((rp) => dep.endsWith(rp) || rp.endsWith(dep)))) {
-                                    if (!resultPaths.some((rp) => file.endsWith(rp) || rp.endsWith(file))) {
-                                        impactCandidates.push(file);
-                                    }
-                                }
-                            }
-                        }
+                        const impactCandidates = computeImpactCandidates(resultPaths);
                         // --- Risk level (based on circular deps + impact breadth) ---
                         let riskLevel = 'low';
                         let cycleCount = 0;
@@ -855,17 +913,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             score: g.score
                         }));
                         // --- Confidence (index freshness) ---
-                        let confidence = 'stale';
-                        if (intelligence.generatedAt) {
-                            const indexAge = Date.now() - new Date(intelligence.generatedAt).getTime();
-                            const hoursOld = indexAge / (1000 * 60 * 60);
-                            if (hoursOld < 24) {
-                                confidence = 'fresh';
-                            }
-                            else if (hoursOld < 168) {
-                                confidence = 'aging';
-                            }
-                        }
+                        const confidence = computeIndexConfidence();
                         // --- Failure memories (1.5x relevance boost) ---
                         const failureWarnings = relatedMemories
                             .filter((m) => m.type === 'failure' && !m.stale)
@@ -910,7 +958,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             preferredPatterns: preferredPatternsForOutput,
                             relatedMemories,
                             failureWarnings,
-                            patternConflicts
+                            patternConflicts,
+                            searchQualityStatus: searchQuality.status
                         });
                         // Bump risk if there are active failure memories for this area
                         if (failureWarnings.length > 0 && riskLevel === 'low') {
@@ -947,33 +996,70 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         // Preflight construction failed — skip preflight, don't fail the search
                     }
                 }
+                // For edit/refactor/migrate: return full preflight card (risk, patterns, impact, etc.).
+                // For explore or lite-only: return flattened { ready, reason }.
+                let preflightPayload;
+                if (preflight) {
+                    const el = preflight.evidenceLock;
+                    // Full card per tool schema; add top-level ready/reason for backward compatibility
+                    preflightPayload = {
+                        ...preflight,
+                        ready: el?.readyToEdit ?? false,
+                        ...(el && !el.readyToEdit && el.nextAction && { reason: el.nextAction })
+                    };
+                }
+                else if (editPreflight) {
+                    const el = editPreflight.evidenceLock;
+                    preflightPayload = {
+                        ready: el?.readyToEdit ?? false,
+                        ...(el && !el.readyToEdit && el.nextAction && { reason: el.nextAction })
+                    };
+                }
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
                                 status: 'success',
-                                ...(preflight && { preflight }),
-                                searchQuality,
+                                searchQuality: {
+                                    status: searchQuality.status,
+                                    confidence: searchQuality.confidence,
+                                    ...(searchQuality.status === 'low_confidence' &&
+                                        searchQuality.nextSteps?.[0] && {
+                                        hint: searchQuality.nextSteps[0]
+                                    })
+                                },
+                                ...(preflightPayload && { preflight: preflightPayload }),
                                 results: results.map((r) => {
                                     const relationships = enrichResult(r);
+                                    // Condensed relationships: importedBy count + hasTests flag
+                                    const condensedRel = relationships
+                                        ? {
+                                            ...(relationships.importedBy &&
+                                                relationships.importedBy.length > 0 && {
+                                                importedByCount: relationships.importedBy.length
+                                            }),
+                                            ...(relationships.testedIn &&
+                                                relationships.testedIn.length > 0 && { hasTests: true })
+                                        }
+                                        : undefined;
+                                    const hasCondensedRel = condensedRel && Object.keys(condensedRel).length > 0;
                                     return {
+                                        file: `${r.filePath}:${r.startLine}-${r.endLine}`,
                                         summary: r.summary,
-                                        snippet: r.snippet,
-                                        filePath: `${r.filePath}:${r.startLine}-${r.endLine}`,
-                                        score: r.score,
-                                        relevanceReason: r.relevanceReason,
-                                        componentType: r.componentType,
-                                        layer: r.layer,
-                                        framework: r.framework,
-                                        trend: r.trend,
-                                        patternWarning: r.patternWarning,
-                                        ...(relationships && { relationships })
+                                        score: Math.round(r.score * 100) / 100,
+                                        ...(r.componentType && r.layer && { type: `${r.componentType}:${r.layer}` }),
+                                        ...(r.trend && r.trend !== 'Stable' && { trend: r.trend }),
+                                        ...(r.patternWarning && { patternWarning: r.patternWarning }),
+                                        ...(hasCondensedRel && { relationships: condensedRel }),
+                                        ...(includeSnippets && r.snippet && { snippet: r.snippet })
                                     };
                                 }),
                                 totalResults: results.length,
                                 ...(relatedMemories.length > 0 && {
-                                    relatedMemories: relatedMemories.slice(0, 5)
+                                    relatedMemories: relatedMemories
+                                        .slice(0, 3)
+                                        .map((m) => `${m.memory} (${m.effectiveConfidence})`)
                                 })
                             }, null, 2)
                         }
@@ -1078,6 +1164,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case 'get_style_guide': {
                 const { query, category } = args;
+                const queryStr = typeof query === 'string' ? query.trim() : '';
+                const queryLower = queryStr.toLowerCase();
+                const queryTerms = queryLower.split(/\s+/).filter(Boolean);
+                const categoryLower = typeof category === 'string' ? category.trim().toLowerCase() : '';
+                const limitedMode = queryTerms.length === 0;
+                const LIMITED_MAX_FILES = 3;
+                const LIMITED_MAX_SECTIONS_PER_FILE = 2;
                 const styleGuidePatterns = [
                     'STYLE_GUIDE.md',
                     'CODING_STYLE.md',
@@ -1088,8 +1181,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     'docs/ARCHITECTURE.md'
                 ];
                 const foundGuides = [];
-                const queryLower = query.toLowerCase();
-                const queryTerms = queryLower.split(/\s+/);
                 for (const pattern of styleGuidePatterns) {
                     try {
                         const files = await glob(pattern, {
@@ -1105,21 +1196,44 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 // Find relevant sections based on query
                                 const sections = content.split(/^##\s+/m);
                                 const relevantSections = [];
-                                for (const section of sections) {
-                                    const sectionLower = section.toLowerCase();
-                                    const isRelevant = queryTerms.some((term) => sectionLower.includes(term));
-                                    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()));
+                                if (limitedMode) {
+                                    const headings = (content.match(/^##\s+.+$/gm) || [])
+                                        .map((h) => h.trim())
+                                        .filter(Boolean)
+                                        .slice(0, LIMITED_MAX_SECTIONS_PER_FILE);
+                                    if (headings.length > 0) {
+                                        relevantSections.push(...headings);
+                                    }
+                                    else {
+                                        const words = content.split(/\s+/).filter(Boolean);
+                                        if (words.length > 0) {
+                                            relevantSections.push(`Overview: ${words.slice(0, 80).join(' ')}...`);
+                                        }
                                     }
                                 }
+                                else {
+                                    for (const section of sections) {
+                                        const sectionLower = section.toLowerCase();
+                                        const isRelevant = queryTerms.some((term) => sectionLower.includes(term));
+                                        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 categoryMatch = !categoryLower ||
+                                    relativePath.toLowerCase().includes(categoryLower) ||
+                                    relevantSections.some((section) => section.toLowerCase().includes(categoryLower));
+                                if (!categoryMatch) {
+                                    continue;
+                                }
                                 if (relevantSections.length > 0) {
                                     foundGuides.push({
                                         file: relativePath,
                                         content: content.slice(0, 200) + '...',
-                                        relevantSections: relevantSections.slice(0, 3) // Max 3 sections per file
+                                        relevantSections: relevantSections.slice(0, limitedMode ? LIMITED_MAX_SECTIONS_PER_FILE : 3)
                                     });
                                 }
                             }
@@ -1132,16 +1246,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         // Pattern didn't match, continue
                     }
                 }
-                if (foundGuides.length === 0) {
+                const results = limitedMode ? foundGuides.slice(0, LIMITED_MAX_FILES) : foundGuides;
+                if (results.length === 0) {
                     return {
                         content: [
                             {
                                 type: 'text',
                                 text: JSON.stringify({
                                     status: 'no_results',
-                                    message: `No style guide content found matching: ${query}`,
+                                    message: limitedMode
+                                        ? 'No style guide files found in the default locations.'
+                                        : `No style guide content found matching: ${queryStr}`,
                                     searchedPatterns: styleGuidePatterns,
-                                    hint: "Try broader terms like 'naming', 'patterns', 'testing', 'components'"
+                                    hint: limitedMode
+                                        ? "Run get_style_guide with a query or category (e.g. category: 'testing') for targeted results."
+                                        : "Try broader terms like 'naming', 'patterns', 'testing', 'components'"
                                 }, null, 2)
                             }
                         ]
@@ -1153,10 +1272,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             type: 'text',
                             text: JSON.stringify({
                                 status: 'success',
-                                query,
+                                query: queryStr || undefined,
                                 category,
-                                results: foundGuides,
-                                totalFiles: foundGuides.length
+                                limited: limitedMode,
+                                notice: limitedMode
+                                    ? 'No query provided. Results are capped. Provide query and/or category for targeted guidance.'
+                                    : undefined,
+                                resultLimits: limitedMode
+                                    ? {
+                                        maxFiles: LIMITED_MAX_FILES,
+                                        maxSectionsPerFile: LIMITED_MAX_SECTIONS_PER_FILE
+                                    }
+                                    : undefined,
+                                results,
+                                totalFiles: results.length,
+                                totalMatches: foundGuides.length
                             }, null, 2)
                         }
                     ]
@@ -1637,9 +1767,18 @@ export { server, performIndexing, resolveRootPath, shouldReindex, TOOLS };
 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);
-        process.exit(1);
-    });
+    // CLI subcommand: memory list/add/remove
+    if (process.argv[2] === 'memory') {
+        handleMemoryCli(process.argv.slice(3)).catch((error) => {
+            console.error('Error:', error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        });
+    }
+    else {
+        main().catch((error) => {
+            console.error('Fatal:', error);
+            process.exit(1);
+        });
+    }
 }
 //# sourceMappingURL=index.js.map