@asd412id/mcp-context-manager 1.0.3 → 1.0.5

package/dist/index.js

@@ -8,6 +8,7 @@ import { registerSummarizerTools } from './tools/summarizer.js';
 import { registerTrackerTools } from './tools/tracker.js';
 import { registerCheckpointTools } from './tools/checkpoint.js';
 import { registerLoaderTools } from './tools/loader.js';
+import { registerSessionTools } from './tools/session.js';
 import { registerPrompts } from './prompts.js';
 const SERVER_NAME = 'mcp-context-manager';
 const SERVER_VERSION = '1.0.0';
@@ -23,6 +24,7 @@ async function main() {
     registerTrackerTools(server);
     registerCheckpointTools(server);
     registerLoaderTools(server);
+    registerSessionTools(server);
     registerPrompts(server);
     // Log before connecting (MCP uses stdio after connect)
     console.error(`${SERVER_NAME} v${SERVER_VERSION} starting...`);

package/dist/storage/file-store.d.ts

@@ -1,11 +1,17 @@
 export interface StoreOptions {
     basePath: string;
+    enableBackup?: boolean;
+    maxBackups?: number;
 }
 export declare class FileStore {
     private basePath;
+    private enableBackup;
+    private maxBackups;
     constructor(options: StoreOptions);
+    private ensureDirSync;
     private ensureDir;
     private getFilePath;
+    private createBackup;
     read<T>(filename: string, defaultValue: T): Promise<T>;
     write<T>(filename: string, data: T): Promise<void>;
     append<T>(filename: string, item: T): Promise<void>;
@@ -15,4 +21,4 @@ export declare class FileStore {
     getSubStore(subdir: string): FileStore;
 }
 export declare function getStore(basePath?: string): FileStore;
-export declare function initStore(basePath: string): FileStore;
+export declare function initStore(basePath: string, options?: Partial<StoreOptions>): FileStore;

package/dist/storage/file-store.js

@@ -1,37 +1,82 @@
 import * as fs from 'fs';
+import * as fsp from 'fs/promises';
 import * as path from 'path';
 export class FileStore {
     basePath;
+    enableBackup;
+    maxBackups;
     constructor(options) {
         this.basePath = options.basePath;
-        this.ensureDir(this.basePath);
+        this.enableBackup = options.enableBackup ?? true;
+        this.maxBackups = options.maxBackups ?? 3;
+        this.ensureDirSync(this.basePath);
     }
-    ensureDir(dirPath) {
+    ensureDirSync(dirPath) {
         if (!fs.existsSync(dirPath)) {
             fs.mkdirSync(dirPath, { recursive: true });
         }
     }
+    async ensureDir(dirPath) {
+        try {
+            await fsp.access(dirPath);
+        }
+        catch {
+            await fsp.mkdir(dirPath, { recursive: true });
+        }
+    }
     getFilePath(filename) {
         return path.join(this.basePath, filename);
     }
+    async createBackup(filePath) {
+        if (!this.enableBackup)
+            return;
+        try {
+            await fsp.access(filePath);
+            const timestamp = Date.now();
+            const backupPath = `${filePath}.${timestamp}.bak`;
+            await fsp.copyFile(filePath, backupPath);
+            // Cleanup old backups
+            const dir = path.dirname(filePath);
+            const basename = path.basename(filePath);
+            const files = await fsp.readdir(dir);
+            const backups = files
+                .filter(f => f.startsWith(basename) && f.endsWith('.bak'))
+                .sort()
+                .reverse();
+            // Remove excess backups
+            for (let i = this.maxBackups; i < backups.length; i++) {
+                await fsp.unlink(path.join(dir, backups[i])).catch(() => { });
+            }
+        }
+        catch {
+            // File doesn't exist, no backup needed
+        }
+    }
     async read(filename, defaultValue) {
         const filePath = this.getFilePath(filename);
         try {
-            if (fs.existsSync(filePath)) {
-                const content = fs.readFileSync(filePath, 'utf-8');
-                return JSON.parse(content);
-            }
+            const content = await fsp.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
         }
         catch (error) {
-            console.error(`Error reading ${filename}:`, error);
+            const err = error;
+            if (err.code !== 'ENOENT') {
+                console.error(`Error reading ${filename}:`, error);
+            }
+            return defaultValue;
         }
-        return defaultValue;
     }
     async write(filename, data) {
         const filePath = this.getFilePath(filename);
         const dir = path.dirname(filePath);
-        this.ensureDir(dir);
-        fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+        await this.ensureDir(dir);
+        // Create backup before write
+        await this.createBackup(filePath);
+        // Write to temp file first, then rename (atomic write)
+        const tempPath = `${filePath}.tmp`;
+        const content = JSON.stringify(data, null, 2);
+        await fsp.writeFile(tempPath, content, 'utf-8');
+        await fsp.rename(tempPath, filePath);
     }
     async append(filename, item) {
         const existing = await this.read(filename, []);
@@ -41,24 +86,32 @@ export class FileStore {
     async delete(filename) {
         const filePath = this.getFilePath(filename);
         try {
-            if (fs.existsSync(filePath)) {
-                fs.unlinkSync(filePath);
-                return true;
-            }
+            await fsp.unlink(filePath);
+            return true;
         }
         catch (error) {
-            console.error(`Error deleting ${filename}:`, error);
+            const err = error;
+            if (err.code !== 'ENOENT') {
+                console.error(`Error deleting ${filename}:`, error);
+            }
+            return false;
         }
-        return false;
     }
     async exists(filename) {
-        return fs.existsSync(this.getFilePath(filename));
+        try {
+            await fsp.access(this.getFilePath(filename));
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
     async list(subdir) {
         const dirPath = subdir ? path.join(this.basePath, subdir) : this.basePath;
-        this.ensureDir(dirPath);
+        await this.ensureDir(dirPath);
         try {
-            return fs.readdirSync(dirPath).filter(f => f.endsWith('.json'));
+            const files = await fsp.readdir(dirPath);
+            return files.filter(f => f.endsWith('.json'));
         }
         catch {
             return [];
@@ -66,7 +119,9 @@ export class FileStore {
     }
     getSubStore(subdir) {
         return new FileStore({
-            basePath: path.join(this.basePath, subdir)
+            basePath: path.join(this.basePath, subdir),
+            enableBackup: this.enableBackup,
+            maxBackups: this.maxBackups
         });
     }
 }
@@ -78,7 +133,10 @@ export function getStore(basePath) {
     }
     return storeInstance;
 }
-export function initStore(basePath) {
-    storeInstance = new FileStore({ basePath });
+export function initStore(basePath, options) {
+    storeInstance = new FileStore({
+        basePath,
+        ...options
+    });
     return storeInstance;
 }

package/dist/tools/checkpoint.js

@@ -1,12 +1,18 @@
 import * as z from 'zod';
 import { getStore } from '../storage/file-store.js';
+const STORAGE_VERSION = 1;
+const MAX_CHECKPOINTS = 50;
 const CHECKPOINTS_DIR = 'checkpoints';
 async function getCheckpointStore() {
     const store = getStore().getSubStore(CHECKPOINTS_DIR);
-    return store.read('index.json', { checkpoints: [] });
+    const data = await store.read('index.json', { version: STORAGE_VERSION, checkpoints: [] });
+    if (!data.version)
+        data.version = STORAGE_VERSION;
+    return data;
 }
 async function saveCheckpointStore(data) {
     const store = getStore().getSubStore(CHECKPOINTS_DIR);
+    data.version = STORAGE_VERSION;
     await store.write('index.json', data);
 }
 async function saveCheckpointData(id, data) {
@@ -23,7 +29,13 @@ async function loadCheckpointData(id) {
 export function registerCheckpointTools(server) {
     server.registerTool('checkpoint_save', {
         title: 'Save Checkpoint',
-        description: 'Save current session state as a checkpoint. Use before context gets too long or at important milestones.',
+        description: `Save current session state as a checkpoint.
+WHEN TO USE:
+- Every 10-15 messages in long conversations
+- Before major refactoring or risky changes
+- At important milestones (feature complete, bug fixed)
+- Before context gets too long (>60% used)
+- When ending a work session`,
         inputSchema: {
             name: z.string().describe('Checkpoint name (e.g., "before-refactor", "feature-complete")'),
             description: z.string().optional().describe('Description of what was accomplished'),
@@ -45,6 +57,15 @@ export function registerCheckpointTools(server) {
             ...checkpoint,
             state: {}
         });
+        // Auto-cleanup old checkpoints
+        if (checkpointStore.checkpoints.length > MAX_CHECKPOINTS) {
+            const store = getStore().getSubStore(CHECKPOINTS_DIR);
+            const toRemove = checkpointStore.checkpoints.splice(0, checkpointStore.checkpoints.length - MAX_CHECKPOINTS);
+            // Delete old checkpoint data files
+            for (const cp of toRemove) {
+                await store.delete(`${cp.id}.json`).catch(() => { });
+            }
+        }
         await saveCheckpointStore(checkpointStore);
         return {
             content: [{
@@ -55,7 +76,11 @@ export function registerCheckpointTools(server) {
     });
     server.registerTool('checkpoint_load', {
         title: 'Load Checkpoint',
-        description: 'Load a previously saved checkpoint to restore context.',
+        description: `Load a previously saved checkpoint to restore context.
+WHEN TO USE:
+- At session start (or use session_init instead)
+- To restore to a specific point in time
+- After context reset to recover previous work`,
         inputSchema: {
             id: z.string().optional().describe('Checkpoint ID (loads latest if not specified)'),
             name: z.string().optional().describe('Checkpoint name to search for')

package/dist/tools/loader.js

@@ -1,6 +1,13 @@
 import * as z from 'zod';
 import * as fs from 'fs';
+import * as fsp from 'fs/promises';
 import * as path from 'path';
+// Safe glob pattern to regex - escapes special chars except *
+function safeGlobToRegex(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    const regexPattern = '^' + escaped.replace(/\*/g, '.*') + '$';
+    return new RegExp(regexPattern, 'i');
+}
 function readFileLines(filePath, startLine, endLine) {
     try {
         if (!fs.existsSync(filePath))
@@ -94,7 +101,12 @@ function extractCodeStructure(content, extension) {
 export function registerLoaderTools(server) {
     server.registerTool('file_smart_read', {
         title: 'Smart File Read',
-        description: 'Read a file with smart options: specific lines, keyword search, or structure extraction. Optimized for context efficiency.',
+        description: `Read a file with smart options: specific lines, keyword search, or structure extraction.
+WHEN TO USE:
+- For large files (>200 lines): use structureOnly:true first to see outline
+- To find specific code: use keywords:["functionName", "className"]
+- For partial reads: use startLine/endLine
+- Saves context vs reading entire file`,
         inputSchema: {
             path: z.string().describe('File path to read'),
             startLine: z.number().optional().describe('Start line (1-indexed)'),
@@ -164,7 +176,11 @@ export function registerLoaderTools(server) {
     });
     server.registerTool('file_info', {
         title: 'File Info',
-        description: 'Get file metadata without reading content. Use to check file existence, size, and modification time.',
+        description: `Get file metadata without reading content.
+WHEN TO USE:
+- Before reading to check if file exists
+- To check file size before deciding read strategy
+- To see modification time`,
         inputSchema: {
             paths: z.array(z.string()).describe('File paths to check')
         }
@@ -183,14 +199,26 @@ export function registerLoaderTools(server) {
             contextLines: z.number().optional().describe('Number of context lines before/after match (default: 2)')
         }
     }, async ({ path: filePath, pattern, contextLines = 2 }) => {
-        if (!fs.existsSync(filePath)) {
+        try {
+            await fsp.access(filePath);
+        }
+        catch {
             return {
                 content: [{ type: 'text', text: `File not found: ${filePath}` }]
             };
         }
-        const content = fs.readFileSync(filePath, 'utf-8');
+        const content = await fsp.readFile(filePath, 'utf-8');
         const lines = content.split('\n');
-        const regex = new RegExp(pattern, 'gi');
+        // Validate regex pattern
+        let regex;
+        try {
+            regex = new RegExp(pattern, 'gi');
+        }
+        catch {
+            return {
+                content: [{ type: 'text', text: `Invalid regex pattern: "${pattern}"` }]
+            };
+        }
         const matches = [];
         for (let i = 0; i < lines.length; i++) {
             if (regex.test(lines[i])) {
@@ -223,24 +251,27 @@ export function registerLoaderTools(server) {
             recursive: z.boolean().optional().describe('Include subdirectories (default: false)')
         }
     }, async ({ path: dirPath, pattern, recursive = false }) => {
-        if (!fs.existsSync(dirPath)) {
+        try {
+            await fsp.access(dirPath);
+        }
+        catch {
             return {
                 content: [{ type: 'text', text: `Directory not found: ${dirPath}` }]
             };
         }
         const results = [];
-        function walkDir(dir) {
-            const items = fs.readdirSync(dir);
+        const patternRegex = pattern ? safeGlobToRegex(pattern) : null;
+        async function walkDir(dir) {
+            const items = await fsp.readdir(dir);
             for (const item of items) {
                 const fullPath = path.join(dir, item);
-                const stat = fs.statSync(fullPath);
+                const stat = await fsp.stat(fullPath);
                 if (stat.isDirectory() && recursive) {
-                    walkDir(fullPath);
+                    await walkDir(fullPath);
                 }
                 else if (stat.isFile()) {
-                    if (pattern) {
-                        const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
-                        if (regex.test(item)) {
+                    if (patternRegex) {
+                        if (patternRegex.test(item)) {
                             results.push(fullPath);
                         }
                     }
@@ -250,7 +281,7 @@ export function registerLoaderTools(server) {
                 }
             }
         }
-        walkDir(dirPath);
+        await walkDir(dirPath);
         return {
             content: [{
                     type: 'text',

package/dist/tools/memory.d.ts

@@ -1,2 +1,3 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function cleanupExpiredMemories(): Promise<number>;
 export declare function registerMemoryTools(server: McpServer): void;

package/dist/tools/memory.js

@@ -1,12 +1,18 @@
 import * as z from 'zod';
 import { getStore } from '../storage/file-store.js';
+const STORAGE_VERSION = 1;
 const MEMORY_FILE = 'memory.json';
 async function getMemoryStore() {
     const store = getStore();
-    return store.read(MEMORY_FILE, { entries: {} });
+    const data = await store.read(MEMORY_FILE, { version: STORAGE_VERSION, entries: {} });
+    // Ensure version field exists for old stores
+    if (!data.version)
+        data.version = STORAGE_VERSION;
+    return data;
 }
 async function saveMemoryStore(data) {
     const store = getStore();
+    data.version = STORAGE_VERSION;
     await store.write(MEMORY_FILE, data);
 }
 function isExpired(entry) {
@@ -15,10 +21,39 @@ function isExpired(entry) {
     const expiresAt = new Date(entry.createdAt).getTime() + entry.ttl;
     return Date.now() > expiresAt;
 }
+// Safe pattern conversion - escape special regex chars except *
+function safePatternToRegex(pattern) {
+    // Escape all special regex characters except *
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    // Convert * to non-greedy .*
+    const regexPattern = '^' + escaped.replace(/\*/g, '.*?') + '$';
+    return new RegExp(regexPattern, 'i');
+}
+// Cleanup expired entries and return count
+export async function cleanupExpiredMemories() {
+    const memStore = await getMemoryStore();
+    const keys = Object.keys(memStore.entries);
+    let removed = 0;
+    for (const key of keys) {
+        if (isExpired(memStore.entries[key])) {
+            delete memStore.entries[key];
+            removed++;
+        }
+    }
+    if (removed > 0) {
+        await saveMemoryStore(memStore);
+    }
+    return removed;
+}
 export function registerMemoryTools(server) {
     server.registerTool('memory_set', {
         title: 'Memory Set',
-        description: 'Store a key-value pair in persistent memory. Use for saving important context, decisions, or data across sessions.',
+        description: `Store a key-value pair in persistent memory.
+WHEN TO USE: 
+- After discovering important info (API endpoints, configs, credentials refs)
+- When user says "remember this" or "save this"
+- To store frequently referenced data
+- Before ending a session to preserve key context`,
         inputSchema: {
             key: z.string().describe('Unique identifier for this memory'),
             value: z.unknown().describe('Data to store (any JSON-serializable value)'),
@@ -47,7 +82,11 @@ export function registerMemoryTools(server) {
     });
     server.registerTool('memory_get', {
         title: 'Memory Get',
-        description: 'Retrieve a value from persistent memory by key.',
+        description: `Retrieve a value from persistent memory by key.
+WHEN TO USE:
+- Before starting work to recall saved context
+- When you need specific info you saved earlier
+- After session_init if you need detailed value (not just key list)`,
         inputSchema: {
             key: z.string().describe('Key to retrieve')
         }
@@ -81,7 +120,11 @@ export function registerMemoryTools(server) {
     });
     server.registerTool('memory_search', {
         title: 'Memory Search',
-        description: 'Search memories by key pattern or tags.',
+        description: `Search memories by key pattern or tags.
+WHEN TO USE:
+- When you need to find memories but don't know exact key
+- To find all memories related to a topic (via tags)
+- Pattern examples: "api.*" matches "api.users", "api.posts"`,
         inputSchema: {
             pattern: z.string().optional().describe('Key pattern to search (supports * wildcard)'),
             tags: z.array(z.string()).optional().describe('Filter by tags (any match)')
@@ -89,10 +132,18 @@ export function registerMemoryTools(server) {
     }, async ({ pattern, tags }) => {
         const memStore = await getMemoryStore();
         let results = Object.values(memStore.entries);
+        // Filter out expired entries
         results = results.filter(entry => !isExpired(entry));
         if (pattern) {
-            const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$', 'i');
-            results = results.filter(entry => regex.test(entry.key));
+            try {
+                const regex = safePatternToRegex(pattern);
+                results = results.filter(entry => regex.test(entry.key));
+            }
+            catch {
+                return {
+                    content: [{ type: 'text', text: `Invalid search pattern: "${pattern}"` }]
+                };
+            }
         }
         if (tags && tags.length > 0) {
             results = results.filter(entry => tags.some(tag => entry.tags.includes(tag)));
@@ -133,7 +184,11 @@ export function registerMemoryTools(server) {
     });
     server.registerTool('memory_list', {
         title: 'Memory List',
-        description: 'List all memory keys with their tags.',
+        description: `List all memory keys with their tags.
+WHEN TO USE:
+- At session start (or use session_init instead)
+- To see what's been saved
+- Before deciding what to store (avoid duplicates)`,
         inputSchema: {}
     }, async () => {
         const memStore = await getMemoryStore();
@@ -179,4 +234,19 @@ export function registerMemoryTools(server) {
             content: [{ type: 'text', text: `Cleared ${count} memories` }]
         };
     });
+    server.registerTool('memory_cleanup', {
+        title: 'Memory Cleanup',
+        description: 'Remove all expired memory entries. Call periodically to free up storage.',
+        inputSchema: {}
+    }, async () => {
+        const removed = await cleanupExpiredMemories();
+        return {
+            content: [{
+                    type: 'text',
+                    text: removed > 0
+                        ? `Cleaned up ${removed} expired memories`
+                        : 'No expired memories to clean up'
+                }]
+        };
+    });
 }

package/dist/tools/session.d.ts

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

package/dist/tools/session.js

@@ -0,0 +1,213 @@
+import * as z from 'zod';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getStore } from '../storage/file-store.js';
+import { cleanupExpiredMemories } from './memory.js';
+function detectProject(cwd) {
+    // Try package.json first
+    const packageJsonPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            return {
+                name: pkg.name || path.basename(cwd),
+                type: pkg.type === 'module' ? 'esm' : 'commonjs',
+                path: cwd,
+                detectedFrom: 'package.json'
+            };
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
+    // Try .git
+    const gitPath = path.join(cwd, '.git');
+    if (fs.existsSync(gitPath)) {
+        // Try to get repo name from git config
+        const gitConfigPath = path.join(gitPath, 'config');
+        if (fs.existsSync(gitConfigPath)) {
+            try {
+                const config = fs.readFileSync(gitConfigPath, 'utf-8');
+                const urlMatch = config.match(/url\s*=\s*.*\/([^\/\s]+?)(?:\.git)?$/m);
+                if (urlMatch) {
+                    return {
+                        name: urlMatch[1],
+                        type: 'git',
+                        path: cwd,
+                        detectedFrom: 'git'
+                    };
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        return {
+            name: path.basename(cwd),
+            type: 'git',
+            path: cwd,
+            detectedFrom: 'git-folder'
+        };
+    }
+    // Try pyproject.toml
+    const pyprojectPath = path.join(cwd, 'pyproject.toml');
+    if (fs.existsSync(pyprojectPath)) {
+        try {
+            const content = fs.readFileSync(pyprojectPath, 'utf-8');
+            const nameMatch = content.match(/name\s*=\s*"([^"]+)"/);
+            return {
+                name: nameMatch ? nameMatch[1] : path.basename(cwd),
+                type: 'python',
+                path: cwd,
+                detectedFrom: 'pyproject.toml'
+            };
+        }
+        catch {
+            // ignore
+        }
+    }
+    // Try Cargo.toml (Rust)
+    const cargoPath = path.join(cwd, 'Cargo.toml');
+    if (fs.existsSync(cargoPath)) {
+        try {
+            const content = fs.readFileSync(cargoPath, 'utf-8');
+            const nameMatch = content.match(/name\s*=\s*"([^"]+)"/);
+            return {
+                name: nameMatch ? nameMatch[1] : path.basename(cwd),
+                type: 'rust',
+                path: cwd,
+                detectedFrom: 'Cargo.toml'
+            };
+        }
+        catch {
+            // ignore
+        }
+    }
+    // Fallback to folder name
+    return {
+        name: path.basename(cwd),
+        type: 'unknown',
+        path: cwd,
+        detectedFrom: 'folder-name'
+    };
+}
+async function getCheckpointLatest() {
+    const store = getStore().getSubStore('checkpoints');
+    const index = await store.read('index.json', { checkpoints: [] });
+    if (index.checkpoints.length === 0)
+        return null;
+    const latest = index.checkpoints[index.checkpoints.length - 1];
+    const stateData = await store.read(`${latest.id}.json`, {});
+    return {
+        id: latest.id,
+        name: latest.name,
+        description: latest.description,
+        createdAt: latest.createdAt,
+        files: latest.files,
+        state: stateData
+    };
+}
+async function getTrackerStatus() {
+    const store = getStore();
+    const trackerStore = await store.read('tracker.json', { entries: [] });
+    const entries = trackerStore.entries;
+    const limit = 5;
+    return {
+        projectName: trackerStore.projectName,
+        totalEntries: entries.length,
+        decisions: entries.filter(e => e.type === 'decision').slice(-limit).map(d => ({ id: d.id, content: d.content, date: d.createdAt })),
+        pendingTodos: entries.filter(e => e.type === 'todo' && e.status === 'pending').slice(-limit).map(t => ({ id: t.id, content: t.content, tags: t.tags })),
+        recentChanges: entries.filter(e => e.type === 'change').slice(-limit).map(c => ({ id: c.id, content: c.content, date: c.createdAt })),
+        recentErrors: entries.filter(e => e.type === 'error').slice(-limit).map(e => ({ id: e.id, content: e.content, date: e.createdAt }))
+    };
+}
+async function getMemoryList() {
+    const store = getStore();
+    const memStore = await store.read('memory.json', { entries: {} });
+    const entries = Object.values(memStore.entries).filter(e => {
+        if (!e.ttl)
+            return true;
+        const expiresAt = new Date(e.createdAt).getTime() + e.ttl;
+        return Date.now() <= expiresAt;
+    });
+    if (entries.length === 0)
+        return [];
+    return entries.map(e => ({
+        key: e.key,
+        tags: e.tags,
+        updatedAt: e.updatedAt
+    }));
+}
+export function registerSessionTools(server) {
+    server.registerTool('session_init', {
+        title: 'Session Init',
+        description: `Initialize session by loading all previous context in ONE call. 
+WHEN TO USE: Call this ONCE at the START of every session/conversation.
+Returns: latest checkpoint, tracker status (todos/decisions), all memories, and auto-detected project info.
+This replaces calling checkpoint_load(), tracker_status(), and memory_list() separately.`,
+        inputSchema: {
+            cwd: z.string().optional().describe('Current working directory for project detection (defaults to process.cwd())')
+        }
+    }, async ({ cwd }) => {
+        const workingDir = cwd || process.cwd();
+        // Cleanup expired memories first
+        const cleanedUp = await cleanupExpiredMemories();
+        const [checkpoint, tracker, memories] = await Promise.all([
+            getCheckpointLatest(),
+            getTrackerStatus(),
+            getMemoryList()
+        ]);
+        const project = detectProject(workingDir);
+        // Auto-set project name if detected and not already set
+        if (project && !tracker?.projectName) {
+            const store = getStore();
+            const trackerStore = await store.read('tracker.json', { entries: [] });
+            trackerStore.projectName = project.name;
+            await store.write('tracker.json', trackerStore);
+        }
+        const state = {
+            checkpoint,
+            tracker,
+            memories,
+            project
+        };
+        const summary = {
+            initialized: true,
+            project: project ? `${project.name} (${project.type})` : 'unknown',
+            hasCheckpoint: !!checkpoint,
+            pendingTodos: (tracker?.pendingTodos || []).length,
+            totalDecisions: (tracker?.decisions || []).length,
+            memoriesCount: Array.isArray(memories) ? memories.length : 0,
+            cleanedUpExpiredMemories: cleanedUp
+        };
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        summary,
+                        ...state
+                    }, null, 2)
+                }]
+        };
+    });
+    server.registerTool('project_detect', {
+        title: 'Project Detect',
+        description: `Auto-detect project information from current directory.
+WHEN TO USE: When you need to know what project you're working on.
+Detects from: package.json, .git, pyproject.toml, Cargo.toml, or folder name.`,
+        inputSchema: {
+            cwd: z.string().optional().describe('Directory to detect project from')
+        }
+    }, async ({ cwd }) => {
+        const workingDir = cwd || process.cwd();
+        const project = detectProject(workingDir);
+        return {
+            content: [{
+                    type: 'text',
+                    text: project
+                        ? JSON.stringify(project, null, 2)
+                        : 'Could not detect project'
+                }]
+        };
+    });
+}

package/dist/tools/summarizer.js

@@ -1,12 +1,22 @@
 import * as z from 'zod';
 import { getStore } from '../storage/file-store.js';
+const STORAGE_VERSION = 1;
+const MAX_SUMMARIES = 100;
 const SUMMARIES_DIR = 'summaries';
 async function getSummaryStore() {
     const store = getStore().getSubStore(SUMMARIES_DIR);
-    return store.read('index.json', { summaries: [] });
+    const data = await store.read('index.json', { version: STORAGE_VERSION, summaries: [] });
+    if (!data.version)
+        data.version = STORAGE_VERSION;
+    return data;
 }
 async function saveSummaryStore(data) {
     const store = getStore().getSubStore(SUMMARIES_DIR);
+    data.version = STORAGE_VERSION;
+    // Auto-cleanup old summaries
+    if (data.summaries.length > MAX_SUMMARIES) {
+        data.summaries = data.summaries.slice(-MAX_SUMMARIES);
+    }
     await store.write('index.json', data);
 }
 function extractKeyPoints(text) {
@@ -90,7 +100,12 @@ function compressText(text, maxLength) {
 export function registerSummarizerTools(server) {
     server.registerTool('context_summarize', {
         title: 'Context Summarize',
-        description: 'Summarize and compress context/conversation. Extracts key points, decisions, and action items. Use this when context is getting too long.',
+        description: `Summarize and compress context/conversation. Extracts key points, decisions, and action items.
+WHEN TO USE:
+- When context is getting long (>60% used)
+- Before checkpoint_save to compress conversation
+- To extract key decisions and action items from long text
+- When you need to free up context space`,
         inputSchema: {
             text: z.string().describe('Text to summarize'),
             maxLength: z.number().optional().describe('Maximum length for compressed summary (default: 2000)'),

package/dist/tools/tracker.js

@@ -1,18 +1,36 @@
 import * as z from 'zod';
 import { getStore } from '../storage/file-store.js';
+const STORAGE_VERSION = 1;
+const MAX_ENTRIES = 1000;
+const ROTATE_KEEP = 800;
 const TRACKER_FILE = 'tracker.json';
 async function getTrackerStore() {
     const store = getStore();
-    return store.read(TRACKER_FILE, { entries: [] });
+    const data = await store.read(TRACKER_FILE, { version: STORAGE_VERSION, entries: [] });
+    if (!data.version)
+        data.version = STORAGE_VERSION;
+    return data;
 }
 async function saveTrackerStore(data) {
     const store = getStore();
+    data.version = STORAGE_VERSION;
+    // Auto-rotate when exceeding limit
+    if (data.entries.length > MAX_ENTRIES) {
+        data.entries = data.entries.slice(-ROTATE_KEEP);
+    }
     await store.write(TRACKER_FILE, data);
 }
 export function registerTrackerTools(server) {
     server.registerTool('tracker_log', {
         title: 'Tracker Log',
-        description: 'Log a decision, change, todo, note, or error to the project tracker.',
+        description: `Log a decision, change, todo, note, or error to the project tracker.
+WHEN TO USE:
+- type:"decision" - After making ANY architectural/implementation choice
+- type:"change" - After modifying ANY file
+- type:"todo" - When user mentions task/TODO/fix needed
+- type:"error" - When encountering errors or bugs
+- type:"note" - For general observations
+ALWAYS log these events - this is MANDATORY, not optional.`,
         inputSchema: {
             type: z.enum(['decision', 'change', 'todo', 'note', 'error']).describe('Type of entry'),
             content: z.string().describe('Description of the entry'),
@@ -43,7 +61,11 @@ export function registerTrackerTools(server) {
     });
     server.registerTool('tracker_status', {
         title: 'Tracker Status',
-        description: 'Get current project status including recent decisions, pending todos, and recent changes.',
+        description: `Get current project status including recent decisions, pending todos, and recent changes.
+WHEN TO USE:
+- At session start (or use session_init instead)
+- To review what needs to be done (pending todos)
+- To recall recent decisions and changes`,
         inputSchema: {
             limit: z.number().optional().describe('Maximum entries per type (default: 5)')
         }
@@ -76,7 +98,11 @@ export function registerTrackerTools(server) {
     });
     server.registerTool('tracker_todo_update', {
         title: 'Update Todo',
-        description: 'Update the status of a todo item.',
+        description: `Update the status of a todo item.
+WHEN TO USE:
+- After completing a task -> status:"done"
+- When task is no longer needed -> status:"cancelled"
+- To re-open a task -> status:"pending"`,
         inputSchema: {
             id: z.string().describe('Todo ID to update'),
             status: z.enum(['pending', 'done', 'cancelled']).describe('New status')
@@ -193,4 +219,29 @@ export function registerTrackerTools(server) {
             content: [{ type: 'text', text: md }]
         };
     });
+    server.registerTool('tracker_cleanup', {
+        title: 'Tracker Cleanup',
+        description: `Clean up old tracker entries. Keeps the most recent entries.
+WHEN TO USE:
+- When tracker has too many old entries
+- To free up storage space
+- Periodically for maintenance`,
+        inputSchema: {
+            keepCount: z.number().optional().describe('Number of entries to keep (default: 500)')
+        }
+    }, async ({ keepCount = 500 }) => {
+        const trackerStore = await getTrackerStore();
+        const originalCount = trackerStore.entries.length;
+        if (originalCount <= keepCount) {
+            return {
+                content: [{ type: 'text', text: `No cleanup needed. Current entries: ${originalCount}` }]
+            };
+        }
+        trackerStore.entries = trackerStore.entries.slice(-keepCount);
+        await saveTrackerStore(trackerStore);
+        const removed = originalCount - keepCount;
+        return {
+            content: [{ type: 'text', text: `Cleaned up ${removed} old entries. Remaining: ${keepCount}` }]
+        };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asd412id/mcp-context-manager",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "MCP tools for context management - summarizer, memory store, project tracker, checkpoints, and smart file loader",
   "type": "module",
   "main": "dist/index.js",