@gotza02/sequential-thinking 2026.2.19 → 2026.2.21

package/dist/lib.js

@@ -5,12 +5,12 @@ import * as path from 'path';
 import { AsyncMutex } from './utils.js';
 export class SequentialThinkingServer {
     thoughtHistory = [];
+    blocks = [];
+    currentBlockId = null;
     branches = {};
     disableThoughtLogging;
     storagePath;
     delayMs;
-    isSaving = false;
-    hasPendingSave = false;
     saveMutex = new AsyncMutex();
     constructor(storagePath = 'thoughts_history.json', delayMs = 0) {
         this.disableThoughtLogging = (process.env.DISABLE_THOUGHT_LOGGING || "").toLowerCase() === "true";
@@ -23,39 +23,38 @@ export class SequentialThinkingServer {
             if (existsSync(this.storagePath)) {
                 const data = readFileSync(this.storagePath, 'utf-8');
                 if (!data.trim())
-                    return; // Empty file is fine
+                    return;
                 try {
-                    const history = JSON.parse(data);
-                    if (Array.isArray(history)) {
+                    const parsed = JSON.parse(data);
+                    // New format with version
+                    if (parsed.version && parsed.blocks) {
+                        this.blocks = parsed.blocks;
+                        this.thoughtHistory = parsed.thoughtHistory || [];
+                        if (this.blocks.length > 0) {
+                            const activeBlock = this.blocks.find(b => b.status === 'active');
+                            this.currentBlockId = activeBlock?.id || this.blocks[this.blocks.length - 1].id;
+                        }
+                        this.rebuildBranches();
+                        return;
+                    }
+                    // Legacy format (array of thoughts)
+                    if (Array.isArray(parsed)) {
                         this.thoughtHistory = [];
                         this.branches = {};
-                        history.forEach(thought => {
+                        parsed.forEach(thought => {
                             if (thought && typeof thought === 'object' && 'thought' in thought) {
+                                // Migrate to new format
+                                thought.thoughtType = thought.thoughtType || 'analysis';
+                                thought.blockId = thought.blockId || 'legacy-default';
                                 this.addToMemory(thought);
                             }
                         });
+                        this.rebuildBlocks();
                     }
                 }
                 catch (parseError) {
                     console.error(`Error parsing history from ${this.storagePath}, attempting recovery:`, parseError);
-                    // Basic Recovery: Try to fix truncated JSON by finding the last complete object
-                    // This is a simple heuristic: find the last '}' that closes a thought object
-                    const lastBrace = data.lastIndexOf('}');
-                    if (lastBrace !== -1) {
-                        try {
-                            const recoveredData = data.substring(0, lastBrace + 1).trim();
-                            // If it's part of an array, we might need to add ']'
-                            const attemptedJson = recoveredData.endsWith(']') ? recoveredData : recoveredData + ']';
-                            const history = JSON.parse(attemptedJson);
-                            if (Array.isArray(history)) {
-                                history.forEach(thought => this.addToMemory(thought));
-                                console.log(`Successfully recovered ${history.length} thoughts.`);
-                            }
-                        }
-                        catch (recoveryError) {
-                            console.error('Recovery failed, starting with empty history.');
-                        }
-                    }
+                    this.attemptRecovery(data);
                 }
             }
         }
@@ -63,12 +62,72 @@ export class SequentialThinkingServer {
             console.error(`Error loading history from ${this.storagePath}:`, error);
         }
     }
+    attemptRecovery(data) {
+        const lastBrace = data.lastIndexOf('}');
+        if (lastBrace !== -1) {
+            try {
+                const recoveredData = data.substring(0, lastBrace + 1).trim();
+                const attemptedJson = recoveredData.endsWith(']') ? recoveredData : recoveredData + ']';
+                const history = JSON.parse(attemptedJson);
+                if (Array.isArray(history)) {
+                    history.forEach(thought => this.addToMemory(thought));
+                    this.rebuildBlocks();
+                    console.log(`Successfully recovered ${history.length} thoughts.`);
+                }
+            }
+            catch (recoveryError) {
+                console.error('Recovery failed, starting with empty history.');
+            }
+        }
+    }
+    rebuildBlocks() {
+        const blockMap = new Map();
+        for (const t of this.thoughtHistory) {
+            const bid = t.blockId || 'default';
+            if (!blockMap.has(bid)) {
+                const newBlock = {
+                    id: bid,
+                    topic: t.thought.substring(0, 50),
+                    status: 'active',
+                    thoughts: [],
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString()
+                };
+                blockMap.set(bid, newBlock);
+                this.blocks.push(newBlock);
+            }
+            blockMap.get(bid).thoughts.push(t);
+        }
+        if (this.blocks.length > 0) {
+            this.currentBlockId = this.blocks[this.blocks.length - 1].id;
+        }
+    }
+    rebuildBranches() {
+        this.branches = {};
+        for (const t of this.thoughtHistory) {
+            if (t.branchFromThought && t.branchId) {
+                const branchKey = `${t.branchFromThought}-${t.branchId}`;
+                if (!this.branches[branchKey]) {
+                    this.branches[branchKey] = [];
+                }
+                this.branches[branchKey].push(t);
+            }
+        }
+    }
     async saveHistory() {
-        // Use mutex to ensure only one file operation happens at a time
         await this.saveMutex.dispatch(async () => {
             try {
+                // Auto-Pruning: Keep max 100 thoughts, summarize older blocks
+                if (this.thoughtHistory.length > 100) {
+                    this.autoPrune();
+                }
+                const storage = {
+                    version: '2.0',
+                    blocks: this.blocks,
+                    thoughtHistory: this.thoughtHistory
+                };
                 const tmpPath = `${this.storagePath}.tmp`;
-                await fs.writeFile(tmpPath, JSON.stringify(this.thoughtHistory, null, 2), 'utf-8');
+                await fs.writeFile(tmpPath, JSON.stringify(storage, null, 2), 'utf-8');
                 await fs.rename(tmpPath, this.storagePath);
             }
             catch (error) {
@@ -76,9 +135,24 @@ export class SequentialThinkingServer {
             }
         });
     }
+    autoPrune() {
+        // Keep last 2 blocks full, mark others as completed
+        if (this.blocks.length > 2) {
+            for (let i = 0; i < this.blocks.length - 2; i++) {
+                this.blocks[i].status = 'completed';
+            }
+        }
+        // Keep only last 100 thoughts
+        if (this.thoughtHistory.length > 100) {
+            const removed = this.thoughtHistory.splice(0, this.thoughtHistory.length - 100);
+            console.error(`[AutoPrune] Removed ${removed.length} old thoughts to maintain performance.`);
+        }
+    }
     async clearHistory() {
         this.thoughtHistory = [];
         this.branches = {};
+        this.blocks = [];
+        this.currentBlockId = null;
         await this.saveHistory();
     }
     async archiveHistory(startIndex, endIndex, summary) {
@@ -90,29 +164,25 @@ export class SequentialThinkingServer {
             thoughtNumber: startIndex,
             totalThoughts: this.thoughtHistory[this.thoughtHistory.length - 1].totalThoughts - (endIndex - startIndex),
             nextThoughtNeeded: true,
-            thoughtType: 'analysis'
+            thoughtType: 'analysis',
+            blockId: this.currentBlockId || undefined
         };
-        // Remove the range and insert summary
         const removedCount = endIndex - startIndex + 1;
         this.thoughtHistory.splice(startIndex - 1, removedCount, summaryThought);
-        // Update all thoughts to reflect the new total and renumber subsequent ones
         const newTotal = this.thoughtHistory.length;
         const shiftAmount = removedCount - 1;
         for (let i = 0; i < this.thoughtHistory.length; i++) {
             const t = this.thoughtHistory[i];
-            // 1. Update total thoughts for everyone
             t.totalThoughts = newTotal;
-            // 2. Renumber thoughts that came after the summarized range
             if (i >= startIndex) {
                 t.thoughtNumber -= shiftAmount;
             }
-            // 3. Update references for all thoughts
             if (t.branchFromThought) {
                 if (t.branchFromThought > endIndex) {
                     t.branchFromThought -= shiftAmount;
                 }
                 else if (t.branchFromThought >= startIndex) {
-                    t.branchFromThought = startIndex; // Point to summary
+                    t.branchFromThought = startIndex;
                 }
             }
             if (t.revisesThought) {
@@ -120,20 +190,12 @@ export class SequentialThinkingServer {
                     t.revisesThought -= shiftAmount;
                 }
                 else if (t.revisesThought >= startIndex) {
-                    t.revisesThought = startIndex; // Point to summary
+                    t.revisesThought = startIndex;
                 }
             }
         }
-        // Rebuild branches (simplification: clear and let it rebuild if needed, or just clear)
-        this.branches = {};
-        this.thoughtHistory.forEach(t => {
-            if (t.branchFromThought && t.branchId) {
-                const branchKey = `${t.branchFromThought}-${t.branchId}`;
-                if (!this.branches[branchKey])
-                    this.branches[branchKey] = [];
-                this.branches[branchKey].push(t);
-            }
-        });
+        this.rebuildBranches();
+        this.rebuildBlocks();
         await this.saveHistory();
         return {
             newHistoryLength: this.thoughtHistory.length,
@@ -144,7 +206,9 @@ export class SequentialThinkingServer {
         const lowerQuery = query.toLowerCase();
         return this.thoughtHistory.filter(t => t.thought.toLowerCase().includes(lowerQuery) ||
             (t.thoughtType && t.thoughtType.toLowerCase().includes(lowerQuery)) ||
-            (t.branchId && t.branchId.toLowerCase().includes(lowerQuery)));
+            (t.branchId && t.branchId.toLowerCase().includes(lowerQuery)) ||
+            (t.blockId && t.blockId.toLowerCase().includes(lowerQuery)) ||
+            (t.relatedToolCall && t.relatedToolCall.toLowerCase().includes(lowerQuery)));
     }
     addToMemory(input) {
         if (input.thoughtNumber > input.totalThoughts) {
@@ -158,81 +222,190 @@ export class SequentialThinkingServer {
             }
             this.branches[branchKey].push(input);
         }
+        // Update block
+        if (input.blockId) {
+            let block = this.blocks.find(b => b.id === input.blockId);
+            if (!block) {
+                block = {
+                    id: input.blockId,
+                    topic: input.thought.substring(0, 50),
+                    status: 'active',
+                    thoughts: [],
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString()
+                };
+                this.blocks.push(block);
+            }
+            block.thoughts.push(input);
+            block.updatedAt = new Date().toISOString();
+        }
     }
     formatThought(thoughtData) {
-        const { thoughtNumber, totalThoughts, thought, isRevision, revisesThought, branchFromThought, branchId, thoughtType, score, options, selectedOption } = thoughtData;
+        const { thoughtNumber, totalThoughts, thought, isRevision, revisesThought, branchFromThought, branchId, thoughtType, score, options, selectedOption, blockId, relatedToolCall } = thoughtData;
+        const typeEmoji = {
+            'analysis': '🔍',
+            'planning': '📋',
+            'execution': '⚡',
+            'observation': '👁️',
+            'hypothesis': '💡',
+            'reflexion': '🔄',
+            'solution': '✅',
+            'generation': '💭',
+            'evaluation': '⚖️',
+            'selection': '🎯'
+        };
         let prefix = '';
         let context = '';
-        if (thoughtType === 'reflexion' || isRevision) {
-            prefix = chalk.yellow('🔄 Reflexion');
+        const type = thoughtType || 'analysis';
+        const emoji = typeEmoji[type] || '💭';
+        if (type === 'reflexion' || isRevision) {
+            prefix = chalk.yellow(`${emoji} Reflexion`);
             if (revisesThought)
-                context += ` (revising thought ${revisesThought})`;
+                context += ` (revising #${revisesThought})`;
+        }
+        else if (type === 'execution') {
+            prefix = chalk.magenta(`${emoji} Execution`);
+            if (relatedToolCall)
+                context += ` [Tool: ${relatedToolCall}]`;
         }
-        else if (thoughtType === 'generation') {
-            prefix = chalk.magenta('💡 Generation');
+        else if (type === 'observation') {
+            prefix = chalk.cyan(`${emoji} Observation`);
         }
-        else if (thoughtType === 'evaluation') {
-            prefix = chalk.cyan('⚖️ Evaluation');
-            if (score)
-                context += ` (Score: ${score})`;
+        else if (type === 'planning') {
+            prefix = chalk.blue(`${emoji} Planning`);
         }
-        else if (thoughtType === 'selection') {
-            prefix = chalk.green('✅ Selection');
-            if (selectedOption)
-                context += ` (Selected: ${selectedOption})`;
+        else if (type === 'solution') {
+            prefix = chalk.green(`${emoji} Solution`);
         }
         else if (branchFromThought) {
-            prefix = chalk.green('🌿 Branch');
-            context = ` (from thought ${branchFromThought}, ID: ${branchId})`;
+            prefix = chalk.green(`🌿 Branch`);
+            context = ` (from #${branchFromThought}, ID: ${branchId})`;
         }
         else {
-            prefix = chalk.blue('💭 Thought');
-            context = '';
+            prefix = chalk.blue(`${emoji} ${type.charAt(0).toUpperCase() + type.slice(1)}`);
         }
+        if (blockId && blockId !== 'default' && blockId !== 'legacy-default') {
+            context += ` [Block: ${blockId}]`;
+        }
+        if (score)
+            context += ` (Score: ${score})`;
+        if (selectedOption)
+            context += ` (Selected: ${selectedOption})`;
         const header = `${prefix} ${thoughtNumber}/${totalThoughts}${context}`;
-        const borderLength = Math.max(header.length, thought.length) + 4;
+        const borderLength = Math.max(header.length, Math.min(thought.length, 80)) + 4;
         const border = '─'.repeat(borderLength);
         let extraContent = '';
         if (options && options.length > 0) {
-            extraContent += `
-│ Options:
-` + options.map(o => `│ - ${o}`).join('\n');
+            extraContent += `\n│ Options:\n` + options.map(o => `│ - ${o}`).join('\n');
         }
+        // Wrap long thoughts
+        const wrappedThought = thought.length > 76
+            ? thought.match(/.{1,76}/g)?.map(line => `│ ${line.padEnd(borderLength - 2)} │`).join('\n') || thought
+            : `│ ${thought.padEnd(borderLength - 2)} │`;
         return `
 ┌${border}┐
-│ ${header} │
+│ ${header.padEnd(borderLength - 2)} │
 ├${border}┤
-│ ${thought.padEnd(borderLength - 2)} │${extraContent}
+${typeof wrappedThought === 'string' && wrappedThought.startsWith('│') ? wrappedThought : `│ ${thought.padEnd(borderLength - 2)} │`}${extraContent}
 └${border}┘`;
     }
+    // --- 2. The New Brain: Process Thought with Interleaved Logic (Opus 4.5 Style) ---
     async processThought(input) {
         try {
             if (this.delayMs > 0) {
                 await new Promise(resolve => setTimeout(resolve, this.delayMs));
             }
-            // --- 🧠 Logic Upgrade: Intelligence & Feedback ---
+            // A. Block Management (Auto-Create Block)
+            if (!input.blockId) {
+                if (!this.currentBlockId) {
+                    this.currentBlockId = `block-${Date.now()}`;
+                    this.blocks.push({
+                        id: this.currentBlockId,
+                        topic: input.thought.substring(0, 50),
+                        status: 'active',
+                        thoughts: [],
+                        createdAt: new Date().toISOString(),
+                        updatedAt: new Date().toISOString()
+                    });
+                }
+                input.blockId = this.currentBlockId;
+            }
+            else if (input.blockId !== this.currentBlockId) {
+                // Context switch detected
+                const oldBlock = this.blocks.find(b => b.id === this.currentBlockId);
+                if (oldBlock) {
+                    oldBlock.status = 'completed';
+                }
+                this.currentBlockId = input.blockId;
+                const existingBlock = this.blocks.find(b => b.id === input.blockId);
+                if (!existingBlock) {
+                    this.blocks.push({
+                        id: input.blockId,
+                        topic: input.thought.substring(0, 50),
+                        status: 'active',
+                        thoughts: [],
+                        createdAt: new Date().toISOString(),
+                        updatedAt: new Date().toISOString()
+                    });
+                }
+                else {
+                    existingBlock.status = 'active';
+                }
+            }
+            // B. Smart Loop Detection (Opus Style)
             const warnings = [];
-            // 1. Loop Detection (ตรวจการคิดวน)
-            const recentThoughts = this.thoughtHistory.slice(-3);
-            if (recentThoughts.length >= 3 && recentThoughts.every(t => t.thoughtType === input.thoughtType)) {
-                warnings.push(`⚠️ WARNING: You have used '${input.thoughtType}' for 4 consecutive steps. Consider 'reflexion' or 'generation' to progress.`);
+            const blockThoughts = this.thoughtHistory.filter(t => t.blockId === input.blockId);
+            const recentInBlock = blockThoughts.slice(-3);
+            const lastThought = this.thoughtHistory[this.thoughtHistory.length - 1];
+            // Rule 1: Stalling Detection (Thinking too much without Action)
+            const thinkingTypes = ['analysis', 'planning', 'hypothesis', 'generation'];
+            if (recentInBlock.length >= 3 &&
+                recentInBlock.every(t => thinkingTypes.includes(t.thoughtType || 'analysis')) &&
+                thinkingTypes.includes(input.thoughtType || 'analysis')) {
+                warnings.push(`⚠️ STALLING DETECTED: You have been thinking for 4 consecutive steps without execution. Consider changing thoughtType to 'execution' and calling a tool to make progress.`);
+            }
+            // Rule 2: Repeating Action Detection (Insanity Check)
+            if (input.thoughtType === 'execution' &&
+                recentInBlock.some(t => t.thoughtType === 'execution' && t.thought === input.thought)) {
+                warnings.push(`🛑 LOOP DETECTED: You are attempting to execute the exact same action again. You MUST change your strategy or create a branch with a different approach.`);
+            }
+            // Rule 3: Missing Observation (Interleaved Enforcer)
+            if (lastThought &&
+                lastThought.thoughtType === 'execution' &&
+                input.thoughtType !== 'observation') {
+                warnings.push(`💡 INTERLEAVED HINT: Your last step was 'execution'. The next step SHOULD be 'observation' to record and analyze the tool result before continuing.`);
             }
-            // 2. Completion Guard (เตือนถ้าลืมเทส)
+            // Rule 4: Skipping Planning (Rushing Detection)
+            const hasPlanning = blockThoughts.some(t => t.thoughtType === 'planning');
+            if (!hasPlanning &&
+                blockThoughts.length >= 2 &&
+                input.thoughtType === 'execution') {
+                warnings.push(`📋 PLANNING HINT: You're about to execute without a planning step. Consider adding a 'planning' thought first to outline your approach.`);
+            }
+            // Rule 5: Ending without Verification
             if (input.nextThoughtNeeded === false) {
                 const hasVerification = this.thoughtHistory.some(t => t.thought.toLowerCase().includes('test') ||
                     t.thought.toLowerCase().includes('verify') ||
-                    t.thought.toLowerCase().includes('check'));
+                    t.thought.toLowerCase().includes('check') ||
+                    t.thoughtType === 'observation');
                 if (!hasVerification) {
-                    warnings.push(`🚨 CRITICAL: You are ending the task without explicit verification/testing steps. It is recommended to verify changes first.`);
+                    warnings.push(`🚨 CRITICAL: You are ending without explicit verification/testing. Consider adding an 'observation' or verification step.`);
                 }
             }
+            // Rule 6: Same type loop (general)
+            if (recentInBlock.length >= 3 &&
+                recentInBlock.every(t => t.thoughtType === input.thoughtType)) {
+                warnings.push(`⚠️ TYPE LOOP: You've used '${input.thoughtType}' for 4 consecutive steps. Consider using a different thought type to progress.`);
+            }
+            // C. Update State
             this.addToMemory(input);
             await this.saveHistory();
             if (!this.disableThoughtLogging) {
                 const formattedThought = this.formatThought(input);
                 console.error(formattedThought);
             }
-            // 3. Visualization (Mermaid Diagram)
+            // D. Generate Contextual Output
+            const currentBlock = this.blocks.find(b => b.id === input.blockId);
             const mermaid = this.generateMermaid();
             return {
                 content: [{
@@ -241,9 +414,14 @@ export class SequentialThinkingServer {
                             thoughtNumber: input.thoughtNumber,
                             totalThoughts: input.totalThoughts,
                             nextThoughtNeeded: input.nextThoughtNeeded,
+                            currentBlock: input.blockId,
+                            blockContext: currentBlock
+                                ? `Block '${currentBlock.topic.substring(0, 30)}' has ${currentBlock.thoughts.length} thoughts.`
+                                : 'No active block',
                             branches: Object.keys(this.branches),
                             thoughtHistoryLength: this.thoughtHistory.length,
-                            feedback: warnings.length > 0 ? warnings : "Analysis healthy",
+                            feedback: warnings.length > 0 ? warnings : "Flow Healthy ✅",
+                            interleavedState: this.getInterleavedState(input),
                             visualization: mermaid
                         }, null, 2)
                     }]
@@ -262,22 +440,84 @@ export class SequentialThinkingServer {
             };
         }
     }
+    getInterleavedState(input) {
+        const lastThought = this.thoughtHistory[this.thoughtHistory.length - 2]; // -2 because current is already added
+        if (!lastThought)
+            return 'START';
+        if (lastThought.thoughtType === 'execution') {
+            return input.thoughtType === 'observation'
+                ? 'INTERLEAVED_CORRECT'
+                : 'INTERLEAVED_EXPECTED_OBSERVATION';
+        }
+        if (lastThought.thoughtType === 'observation') {
+            return 'POST_OBSERVATION';
+        }
+        return 'THINKING';
+    }
     generateMermaid() {
         let diagram = 'graph TD\n';
-        this.thoughtHistory.forEach((t, i) => {
+        const recentThoughts = this.thoughtHistory.slice(-15); // Last 15 for readability
+        recentThoughts.forEach((t, i) => {
             const id = `T${t.thoughtNumber}`;
-            const label = `${t.thoughtNumber}[${t.thoughtType || 'thought'}]`;
+            const typeIcon = {
+                'analysis': '🔍',
+                'planning': '📋',
+                'execution': '⚡',
+                'observation': '👁️',
+                'hypothesis': '💡',
+                'reflexion': '🔄',
+                'solution': '✅',
+                'generation': '💭',
+                'evaluation': '⚖️',
+                'selection': '🎯'
+            }[t.thoughtType || 'analysis'] || '💭';
+            const label = `${typeIcon} ${t.thoughtNumber}`;
             diagram += `  ${id}("${label}")\n`;
             if (i > 0) {
-                const prevId = `T${this.thoughtHistory[i - 1].thoughtNumber}`;
+                const prevT = recentThoughts[i - 1];
+                const prevId = `T${prevT.thoughtNumber}`;
                 if (t.branchFromThought) {
                     diagram += `  T${t.branchFromThought} -->|branch: ${t.branchId}| ${id}\n`;
                 }
                 else {
-                    diagram += `  ${prevId} --> ${id}\n`;
+                    const edgeLabel = t.thoughtType === 'observation' ? '|result|' : '';
+                    diagram += `  ${prevId} -->${edgeLabel} ${id}\n`;
                 }
             }
         });
         return diagram;
     }
+    // Public method to start a new block explicitly
+    startNewBlock(blockId, topic) {
+        if (this.currentBlockId) {
+            const oldBlock = this.blocks.find(b => b.id === this.currentBlockId);
+            if (oldBlock) {
+                oldBlock.status = 'completed';
+            }
+        }
+        this.currentBlockId = blockId;
+        this.blocks.push({
+            id: blockId,
+            topic: topic,
+            status: 'active',
+            thoughts: [],
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString()
+        });
+    }
+    // Get current block info
+    getCurrentBlock() {
+        if (!this.currentBlockId)
+            return null;
+        return this.blocks.find(b => b.id === this.currentBlockId) || null;
+    }
+    // Get all blocks summary
+    getBlocksSummary() {
+        return this.blocks.map(b => ({
+            id: b.id,
+            topic: b.topic,
+            status: b.status,
+            thoughtCount: b.thoughts.length
+        }));
+    }
 }

package/dist/notes.d.ts

@@ -0,0 +1,25 @@
+export type Priority = 'low' | 'medium' | 'high' | 'critical';
+export interface Note {
+    id: string;
+    title: string;
+    content: string;
+    tags: string[];
+    priority: Priority;
+    expiresAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare class NotesManager {
+    private filePath;
+    private notes;
+    private loaded;
+    private mutex;
+    constructor(storagePath?: string);
+    private load;
+    private save;
+    addNote(title: string, content: string, tags?: string[], priority?: Priority, expiresAt?: string): Promise<Note>;
+    listNotes(tag?: string, includeExpired?: boolean): Promise<Note[]>;
+    searchNotes(query: string): Promise<Note[]>;
+    deleteNote(id: string): Promise<boolean>;
+    updateNote(id: string, updates: Partial<Pick<Note, 'title' | 'content' | 'tags'>>): Promise<Note | null>;
+}

package/dist/system_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test_ts_req.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/codestore.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CodeDatabase } from '../codestore.js';
+export declare function registerCodeDbTools(server: McpServer, db: CodeDatabase): void;

package/dist/tools/coding.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ProjectKnowledgeGraph } from '../graph.js';
+export declare function registerCodingTools(server: McpServer, graph: ProjectKnowledgeGraph): void;

package/dist/tools/coding.js

@@ -31,9 +31,46 @@ export function registerCodingTools(server, graph) {
                 doc += `- ${d.path} (Symbols: ${d.symbols.join(', ')})\n`;
             });
             doc += `\nDEPENDENTS (Files that use this file):\n`;
-            context.dependents.forEach(d => {
-                doc += `- ${d.path} (Symbols: ${d.symbols.join(', ')})\n`;
-            });
+            // Helper to find usages (defined inline to capture context/scope)
+            const findUsages = async (fileToSearch, targetPath, symbols) => {
+                try {
+                    const content = await fs.readFile(fileToSearch, 'utf-8');
+                    const lines = content.split('\n');
+                    const matches = [];
+                    const baseName = path.basename(targetPath, path.extname(targetPath));
+                    // Escape regex special chars
+                    const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                    const symbolRegexes = symbols.map(s => new RegExp(`\\b${escapeRegExp(s)}\\b`));
+                    lines.forEach((line, index) => {
+                        // Check for import of the file itself (simple heuristic)
+                        if ((line.includes('import') || line.includes('require')) && line.includes(baseName)) {
+                            matches.push(`Line ${index + 1}: ${line.trim()}`);
+                            return;
+                        }
+                        // Check for symbols
+                        for (const regex of symbolRegexes) {
+                            if (regex.test(line)) {
+                                matches.push(`Line ${index + 1}: ${line.trim()}`);
+                                break; // One match per line is enough
+                            }
+                        }
+                    });
+                    return matches;
+                }
+                catch (e) {
+                    return [];
+                }
+            };
+            for (const d of context.dependents) {
+                doc += `- ${d.path}\n`;
+                const usages = await findUsages(d.path, filePath, context.targetFile.symbols);
+                if (usages.length > 0) {
+                    // Limit to top 3 to save context
+                    usages.slice(0, 3).forEach(u => doc += `  ${u}\n`);
+                    if (usages.length > 3)
+                        doc += `  ... (${usages.length - 3} more references)\n`;
+                }
+            }
             doc += `\n--- END OF CONTEXT ---`;
             return {
                 content: [{ type: "text", text: doc }]

package/dist/tools/filesystem.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFileSystemTools(server: McpServer): void;