@contextmirror/claude-memory 0.2.1 → 0.3.0

package/dist/scanner/contextGenerator.js

@@ -1,38 +1,125 @@
 /**
  * Context Generator - Produces markdown context files
  */
-import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { writeFileSync, mkdirSync, existsSync, readFileSync, renameSync, unlinkSync, copyFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
+import { SCHEMA_VERSION } from '../types/index.js';
 const MEMORY_DIR = join(homedir(), '.claude-memory');
+/**
+ * Load existing context from disk (if any)
+ */
+export function loadExistingContext() {
+    const jsonPath = join(MEMORY_DIR, 'context.json');
+    if (!existsSync(jsonPath)) {
+        return null;
+    }
+    try {
+        const data = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+        return migrateContext(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Migrate old context format to current schema
+ */
+function migrateContext(data) {
+    const version = data.schemaVersion || 0;
+    // Migration from v0 (no version) to v1
+    if (version < 1) {
+        // v0 didn't have schemaVersion, excludedProjects
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            lastUpdated: data.lastUpdated || new Date().toISOString(),
+            projects: data.projects || [],
+            insights: data.insights || [],
+            userPatterns: data.userPatterns || [],
+            excludedProjects: [],
+        };
+    }
+    // Already current version
+    return data;
+}
 /**
  * Generate global context from scanned projects
+ * Preserves existing insights and user patterns
  */
 export function generateGlobalContext(projects) {
+    // Load existing context to preserve insights
+    const existing = loadExistingContext();
     return {
+        schemaVersion: SCHEMA_VERSION,
         lastUpdated: new Date().toISOString(),
         projects,
-        insights: [], // TODO: Cross-project analysis
-        userPatterns: [], // TODO: Pattern detection
+        // Preserve existing insights and patterns!
+        insights: existing?.insights || [],
+        userPatterns: existing?.userPatterns || [],
+        excludedProjects: existing?.excludedProjects || [],
     };
 }
 /**
  * Write global context to ~/.claude-memory/
+ * Uses atomic write (write to temp, then rename) to prevent corruption
+ * Creates backup before overwriting
  */
 export function writeGlobalContext(context) {
     // Ensure directory exists
     if (!existsSync(MEMORY_DIR)) {
         mkdirSync(MEMORY_DIR, { recursive: true });
     }
-    // Write JSON for MCP server
     const jsonPath = join(MEMORY_DIR, 'context.json');
-    writeFileSync(jsonPath, JSON.stringify(context, null, 2));
-    // Write markdown for human readability
     const mdPath = join(MEMORY_DIR, 'global-context.md');
-    writeFileSync(mdPath, formatGlobalContextMarkdown(context));
-    console.log(`\n📝 Written to:`);
-    console.log(`   ${jsonPath}`);
-    console.log(`   ${mdPath}`);
+    const jsonTempPath = join(MEMORY_DIR, 'context.json.tmp');
+    const mdTempPath = join(MEMORY_DIR, 'global-context.md.tmp');
+    const jsonBackupPath = join(MEMORY_DIR, 'context.json.bak');
+    try {
+        // Create backup of existing context before overwriting
+        if (existsSync(jsonPath)) {
+            try {
+                copyFileSync(jsonPath, jsonBackupPath);
+            }
+            catch {
+                // Backup failed, but continue anyway
+                console.warn('   ⚠️  Could not create backup');
+            }
+        }
+        // Write to temp files first (atomic write pattern)
+        const jsonContent = JSON.stringify(context, null, 2);
+        writeFileSync(jsonTempPath, jsonContent, 'utf-8');
+        const mdContent = formatGlobalContextMarkdown(context);
+        writeFileSync(mdTempPath, mdContent, 'utf-8');
+        // Verify JSON can be parsed back
+        const verification = JSON.parse(readFileSync(jsonTempPath, 'utf-8'));
+        if (verification.projects.length !== context.projects.length) {
+            throw new Error(`Write verification failed: expected ${context.projects.length} projects, got ${verification.projects.length}`);
+        }
+        // Atomic rename (much safer than direct write)
+        renameSync(jsonTempPath, jsonPath);
+        renameSync(mdTempPath, mdPath);
+        console.log(`\n📝 Written to:`);
+        console.log(`   ${jsonPath} (${context.projects.length} projects)`);
+        console.log(`   ${mdPath}`);
+    }
+    catch (err) {
+        // Clean up temp files if they exist
+        try {
+            if (existsSync(jsonTempPath))
+                unlinkSync(jsonTempPath);
+            if (existsSync(mdTempPath))
+                unlinkSync(mdTempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        console.error(`\n❌ Failed to write context:`);
+        console.error(`   ${err instanceof Error ? err.message : 'Unknown error'}`);
+        if (existsSync(jsonBackupPath)) {
+            console.error(`   💾 Backup available at: ${jsonBackupPath}`);
+        }
+        throw err; // Re-throw so caller knows it failed
+    }
 }
 /**
  * Format global context as markdown

package/dist/scanner/projectScanner.d.ts

@@ -2,7 +2,15 @@
  * Project Scanner - Discovers and analyzes projects
  */
 import { ProjectInfo, ScanOptions } from '../types/index.js';
+/**
+ * Extended scan options with onlyPaths support
+ */
+interface ExtendedScanOptions extends Partial<ScanOptions> {
+    /** If provided, only scan these specific paths (for quick/incremental scan) */
+    onlyPaths?: string[];
+}
 /**
  * Scan a directory for projects and extract information
  */
-export declare function scanProjects(options?: Partial<ScanOptions>): Promise<ProjectInfo[]>;
+export declare function scanProjects(options?: ExtendedScanOptions): Promise<ProjectInfo[]>;
+export {};

package/dist/scanner/projectScanner.js

@@ -5,27 +5,86 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { join, basename } from 'path';
 import { simpleGit } from 'simple-git';
 import { DEFAULT_SCAN_OPTIONS } from '../types/index.js';
+import { loadExistingContext } from './contextGenerator.js';
 /**
  * Scan a directory for projects and extract information
  */
 export async function scanProjects(options = {}) {
     const opts = { ...DEFAULT_SCAN_OPTIONS, ...options };
     const projects = [];
+    const errors = [];
+    // Quick mode: only scan specific paths
+    if (options.onlyPaths && options.onlyPaths.length > 0) {
+        console.log(`🔍 Quick scan: ${options.onlyPaths.length} project(s)...`);
+        for (const projectPath of options.onlyPaths) {
+            if (!existsSync(projectPath)) {
+                console.warn(`  ⚠ Path not found: ${projectPath}`);
+                continue;
+            }
+            try {
+                const info = await analyzeProject(projectPath);
+                if (info) {
+                    projects.push(info);
+                    console.log(`  ✓ ${info.name} (${info.language})`);
+                }
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : 'Unknown error';
+                errors.push({ path: projectPath, error: errorMsg });
+                console.warn(`  ⚠ Failed: ${basename(projectPath)} - ${errorMsg}`);
+            }
+        }
+        console.log(`\n📊 Quick scan results: ${projects.length} project(s) updated`);
+        return projects;
+    }
+    // Full scan mode
     console.log(`🔍 Scanning ${opts.rootDir} for projects...`);
+    // Verify root directory exists
+    if (!existsSync(opts.rootDir)) {
+        console.error(`❌ Directory does not exist: ${opts.rootDir}`);
+        console.error(`   Check the path and try again.`);
+        return [];
+    }
     const candidates = findProjectRoots(opts.rootDir, opts.maxDepth, opts.ignore);
-    for (const projectPath of candidates) {
+    if (candidates.length === 0) {
+        console.log(`   No project directories found in ${opts.rootDir}`);
+        console.log(`   Looking for: package.json, Cargo.toml, pyproject.toml, go.mod, or .git`);
+        return [];
+    }
+    // Load excluded projects from existing context
+    const existingContext = loadExistingContext();
+    const excludedProjects = new Set(existingContext?.excludedProjects || []);
+    // Filter out excluded projects
+    const filteredCandidates = candidates.filter(path => {
+        if (excludedProjects.has(path)) {
+            console.log(`   ⊘ Skipping excluded: ${basename(path)}`);
+            return false;
+        }
+        return true;
+    });
+    console.log(`   Found ${filteredCandidates.length} candidate directories\n`);
+    if (excludedProjects.size > 0) {
+        console.log(`   (${excludedProjects.size} excluded)\n`);
+    }
+    for (const projectPath of filteredCandidates) {
         try {
             const info = await analyzeProject(projectPath);
             if (info) {
                 projects.push(info);
-                console.log(`  ✓ Found: ${info.name} (${info.language})`);
+                console.log(`  ✓ ${info.name} (${info.language}) - ${info.techStack.join(', ') || 'no stack detected'}`);
             }
         }
         catch (err) {
-            console.warn(`  ⚠ Failed to analyze: ${projectPath}`);
+            const errorMsg = err instanceof Error ? err.message : 'Unknown error';
+            errors.push({ path: projectPath, error: errorMsg });
+            console.warn(`  ⚠ Failed: ${basename(projectPath)} - ${errorMsg}`);
         }
     }
-    console.log(`\n📊 Found ${projects.length} projects`);
+    console.log(`\n📊 Results:`);
+    console.log(`   ✅ Successfully scanned: ${projects.length}`);
+    if (errors.length > 0) {
+        console.log(`   ⚠️  Failed to scan: ${errors.length}`);
+    }
     return projects;
 }
 /**
@@ -77,23 +136,33 @@ async function analyzeProject(projectPath) {
     const name = detectProjectName(projectPath);
     const description = detectDescription(projectPath);
     const { language, techStack } = detectTechStack(projectPath);
-    // Git info
+    // Git info with timeout to prevent hanging on large/slow repos
     let lastActivity = new Date().toISOString();
     let currentBranch = 'unknown';
     let isDirty = false;
     if (existsSync(join(projectPath, '.git'))) {
         try {
-            const git = simpleGit(projectPath);
-            const log = await git.log({ maxCount: 1 });
-            if (log.latest) {
-                lastActivity = log.latest.date;
-            }
-            const status = await git.status();
-            currentBranch = status.current || 'unknown';
-            isDirty = !status.isClean();
+            // 10 second timeout for git operations
+            const git = simpleGit(projectPath, { timeout: { block: 10000 } });
+            // Wrap in Promise.race for extra safety
+            const gitOps = async () => {
+                const log = await git.log({ maxCount: 1 });
+                if (log.latest) {
+                    lastActivity = log.latest.date;
+                }
+                const status = await git.status();
+                currentBranch = status.current || 'unknown';
+                isDirty = !status.isClean();
+            };
+            const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('Git timeout')), 10000));
+            await Promise.race([gitOps(), timeout]);
         }
-        catch {
-            // Git operations failed, use defaults
+        catch (err) {
+            // Git operations failed or timed out, use defaults
+            const errorMsg = err instanceof Error ? err.message : 'Unknown error';
+            if (errorMsg.includes('timeout') || errorMsg.includes('Timeout')) {
+                console.warn(`   ⚠️  Git timeout for ${basename(projectPath)} - using defaults`);
+            }
         }
     }
     // Extract insights from CLAUDE.md if it exists

package/dist/scanner/stalenessDetector.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Staleness detection for claude-memory
+ * Detects which projects need rescanning based on age and git activity
+ */
+import { GlobalContext, ProjectInfo } from '../types/index.js';
+export interface StaleProject {
+    name: string;
+    path: string;
+    daysSinceScanned: number;
+    reason: 'age' | 'git_activity' | 'file_changed' | 'never_scanned';
+    details?: string;
+}
+export interface StalenessReport {
+    /** Overall data age in hours */
+    dataAgeHours: number;
+    /** Projects that need rescanning */
+    staleProjects: StaleProject[];
+    /** Projects that are fresh */
+    freshCount: number;
+    /** Human-readable summary */
+    summary: string;
+    /** Suggested CLI command */
+    suggestion?: string;
+}
+/**
+ * Detect all stale projects in the global context
+ */
+export declare function detectStaleProjects(context: GlobalContext): StalenessReport;
+/**
+ * Get a quick staleness check for the current working directory
+ */
+export declare function checkCurrentProjectStaleness(context: GlobalContext, cwd: string): {
+    isStale: boolean;
+    project?: ProjectInfo;
+    reason?: string;
+};
+/**
+ * Format staleness report for MCP output
+ */
+export declare function formatStalenessForMcp(report: StalenessReport): string;

package/dist/scanner/stalenessDetector.js

@@ -0,0 +1,198 @@
+/**
+ * Staleness detection for claude-memory
+ * Detects which projects need rescanning based on age and git activity
+ */
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+/** Thresholds for staleness (in days) */
+const STALENESS_THRESHOLDS = {
+    WARNING: 3, // Yellow warning
+    STALE: 7, // Orange warning
+    CRITICAL: 14, // Red warning
+};
+/**
+ * Check if a project has new git commits since last scan
+ */
+function hasNewCommits(projectPath, lastScanned) {
+    try {
+        const gitDir = path.join(projectPath, '.git');
+        if (!fs.existsSync(gitDir))
+            return false;
+        // Get latest commit date
+        const result = execSync('git log -1 --format=%cI 2>/dev/null || echo ""', { cwd: projectPath, timeout: 5000, encoding: 'utf-8' }).trim();
+        if (!result)
+            return false;
+        const lastCommitDate = new Date(result);
+        const lastScannedDate = new Date(lastScanned);
+        return lastCommitDate > lastScannedDate;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if key project files have been modified since last scan
+ */
+function hasModifiedFiles(projectPath, lastScanned) {
+    const keyFiles = [
+        'package.json',
+        'CLAUDE.md',
+        'README.md',
+        'Cargo.toml',
+        'pyproject.toml',
+        'go.mod',
+    ];
+    const lastScannedTime = new Date(lastScanned).getTime();
+    for (const file of keyFiles) {
+        try {
+            const filePath = path.join(projectPath, file);
+            if (fs.existsSync(filePath)) {
+                const stat = fs.statSync(filePath);
+                if (stat.mtimeMs > lastScannedTime) {
+                    return true;
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    return false;
+}
+/**
+ * Analyze a single project for staleness
+ */
+function analyzeProjectStaleness(project) {
+    const now = new Date();
+    const lastScanned = new Date(project.lastScanned);
+    const daysSinceScanned = Math.floor((now.getTime() - lastScanned.getTime()) / (1000 * 60 * 60 * 24));
+    // Check for git activity first (most reliable signal)
+    if (hasNewCommits(project.path, project.lastScanned)) {
+        return {
+            name: project.name,
+            path: project.path,
+            daysSinceScanned,
+            reason: 'git_activity',
+            details: 'New commits since last scan',
+        };
+    }
+    // Check for modified key files
+    if (hasModifiedFiles(project.path, project.lastScanned)) {
+        return {
+            name: project.name,
+            path: project.path,
+            daysSinceScanned,
+            reason: 'file_changed',
+            details: 'Key files modified since last scan',
+        };
+    }
+    // Check age threshold
+    if (daysSinceScanned >= STALENESS_THRESHOLDS.STALE) {
+        return {
+            name: project.name,
+            path: project.path,
+            daysSinceScanned,
+            reason: 'age',
+            details: `Not scanned in ${daysSinceScanned} days`,
+        };
+    }
+    return null;
+}
+/**
+ * Detect all stale projects in the global context
+ */
+export function detectStaleProjects(context) {
+    const now = new Date();
+    const lastUpdated = new Date(context.lastUpdated);
+    const dataAgeHours = Math.floor((now.getTime() - lastUpdated.getTime()) / (1000 * 60 * 60));
+    const staleProjects = [];
+    for (const project of context.projects) {
+        const staleness = analyzeProjectStaleness(project);
+        if (staleness) {
+            staleProjects.push(staleness);
+        }
+    }
+    // Sort by days since scanned (most stale first)
+    staleProjects.sort((a, b) => b.daysSinceScanned - a.daysSinceScanned);
+    const freshCount = context.projects.length - staleProjects.length;
+    // Generate summary
+    let summary;
+    let suggestion;
+    if (staleProjects.length === 0) {
+        summary = `All ${context.projects.length} projects are up to date.`;
+    }
+    else if (staleProjects.length === 1) {
+        const p = staleProjects[0];
+        summary = `1 project needs updating: ${p.name} (${p.details})`;
+        suggestion = `claude-memory scan --quick`;
+    }
+    else {
+        const critical = staleProjects.filter(p => p.daysSinceScanned >= STALENESS_THRESHOLDS.CRITICAL);
+        if (critical.length > 0) {
+            summary = `⚠️ ${staleProjects.length} projects need updating (${critical.length} critical)`;
+        }
+        else {
+            summary = `${staleProjects.length} projects could use a refresh`;
+        }
+        suggestion = `claude-memory scan --quick`;
+    }
+    return {
+        dataAgeHours,
+        staleProjects,
+        freshCount,
+        summary,
+        suggestion,
+    };
+}
+/**
+ * Get a quick staleness check for the current working directory
+ */
+export function checkCurrentProjectStaleness(context, cwd) {
+    // Find the project that matches the cwd
+    const project = context.projects.find(p => cwd.startsWith(p.path) || p.path.startsWith(cwd));
+    if (!project) {
+        return { isStale: false };
+    }
+    const staleness = analyzeProjectStaleness(project);
+    if (staleness) {
+        return {
+            isStale: true,
+            project,
+            reason: staleness.details,
+        };
+    }
+    return { isStale: false, project };
+}
+/**
+ * Format staleness report for MCP output
+ */
+export function formatStalenessForMcp(report) {
+    const lines = [];
+    if (report.staleProjects.length === 0) {
+        return ''; // Don't add noise if everything is fresh
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push('### 🔄 Data Freshness');
+    lines.push('');
+    lines.push(report.summary);
+    if (report.staleProjects.length > 0 && report.staleProjects.length <= 5) {
+        lines.push('');
+        for (const p of report.staleProjects) {
+            const icon = p.reason === 'git_activity' ? '📝' :
+                p.reason === 'file_changed' ? '📄' : '⏰';
+            lines.push(`- ${icon} **${p.name}**: ${p.details}`);
+        }
+    }
+    else if (report.staleProjects.length > 5) {
+        lines.push('');
+        lines.push(`Stale projects: ${report.staleProjects.map(p => p.name).join(', ')}`);
+    }
+    if (report.suggestion) {
+        lines.push('');
+        lines.push(`> Run \`${report.suggestion}\` to refresh`);
+    }
+    return lines.join('\n');
+}

package/dist/setup/setupWizard.js

@@ -25,12 +25,33 @@ const MCP_SERVER_CONFIG = {
  * Run the setup wizard
  */
 export async function runSetupWizard(options = {}) {
-    const { projectsDir = guessProjectsDir(), skipMcp = false, skipBriefing = false, interactive = true, } = options;
+    const { projectsDir: providedDir, skipMcp = false, skipBriefing = false, interactive = true, } = options;
     console.log('');
     console.log('╔══════════════════════════════════════════════════════════╗');
     console.log('║         🧠 Claude Memory - Setup Wizard                  ║');
     console.log('╚══════════════════════════════════════════════════════════╝');
     console.log('');
+    // Determine projects directory
+    let projectsDir = providedDir || guessProjectsDir();
+    if (!projectsDir) {
+        console.log('📍 Step 0: Locate your projects\n');
+        console.log('   Could not auto-detect your projects directory.');
+        console.log('   Common locations like ~/Projects, ~/Code, ~/dev were not found.\n');
+        if (interactive) {
+            const answer = await ask('   Enter your projects directory path: ');
+            if (!answer || !existsSync(answer)) {
+                console.log('\n   ❌ Invalid directory. Please run:');
+                console.log('   claude-memory setup -d /path/to/your/projects');
+                return;
+            }
+            projectsDir = answer;
+        }
+        else {
+            console.log('   ❌ Cannot continue without a projects directory.');
+            console.log('   Run: claude-memory setup -d /path/to/your/projects');
+            return;
+        }
+    }
     // Step 1: Find projects
     console.log('📍 Step 1: Scanning for projects\n');
     console.log(`   Looking in: ${projectsDir}`);
@@ -164,6 +185,7 @@ export async function runSetupWizard(options = {}) {
 }
 /**
  * Guess the user's projects directory
+ * Returns null if we can't find a reasonable guess (better than scanning home!)
  */
 function guessProjectsDir() {
     const home = homedir();
@@ -178,14 +200,17 @@ function guessProjectsDir() {
         join(home, 'src'),
         join(home, 'repos'),
         join(home, 'git'),
+        join(home, 'workspace'),
+        join(home, 'Workspace'),
     ];
     for (const dir of candidates) {
         if (existsSync(dir)) {
             return dir;
         }
     }
-    // Fall back to home directory
-    return home;
+    // Don't fall back to home - that scans way too much and causes issues
+    // Return null and let the caller handle it
+    return null;
 }
 /**
  * Save memory config to ~/.claude-memory/config.json

package/dist/types/index.d.ts

@@ -1,6 +1,8 @@
 /**
  * Core types for Claude Memory
  */
+/** Current schema version - increment when making breaking changes */
+export declare const SCHEMA_VERSION = 1;
 export interface ProjectInfo {
     /** Absolute path to project root */
     path: string;
@@ -43,14 +45,18 @@ export interface ProjectInsight {
     discoveredAt: string;
 }
 export interface GlobalContext {
+    /** Schema version for migration support */
+    schemaVersion: number;
     /** When the global context was last updated */
     lastUpdated: string;
     /** All scanned projects */
     projects: ProjectInfo[];
-    /** Cross-project insights */
+    /** Cross-project insights (preserved across rescans) */
     insights: GlobalInsight[];
     /** User preferences/patterns observed */
     userPatterns: UserPattern[];
+    /** Projects to exclude from scanning (by path) */
+    excludedProjects?: string[];
 }
 export interface GlobalInsight {
     /** Insight content */

package/dist/types/index.js

@@ -1,10 +1,43 @@
 /**
  * Core types for Claude Memory
  */
+/** Current schema version - increment when making breaking changes */
+export const SCHEMA_VERSION = 1;
+/**
+ * Get a sensible default projects directory
+ * Checks common locations, doesn't fall back to home
+ */
+function getDefaultProjectsDir() {
+    const home = process.env.HOME || '';
+    if (!home)
+        return './projects';
+    const candidates = [
+        `${home}/Projects`,
+        `${home}/Project`,
+        `${home}/projects`,
+        `${home}/Code`,
+        `${home}/code`,
+        `${home}/dev`,
+    ];
+    // Import fs dynamically to avoid issues
+    try {
+        const fs = require('fs');
+        for (const dir of candidates) {
+            if (fs.existsSync(dir)) {
+                return dir;
+            }
+        }
+    }
+    catch {
+        // fs not available, use first candidate
+    }
+    // Default to ~/Projects (most common convention)
+    return `${home}/Projects`;
+}
 export const DEFAULT_SCAN_OPTIONS = {
-    rootDir: process.env.HOME ? `${process.env.HOME}/Project` : './projects',
+    rootDir: getDefaultProjectsDir(),
     maxDepth: 2,
-    ignore: ['node_modules', '.git', 'dist', 'build', '__pycache__', 'target'],
+    ignore: ['node_modules', '.git', 'dist', 'build', '__pycache__', 'target', '.venv', 'venv', 'coverage', '.next'],
     generateClaudeMd: false,
     overwriteClaudeMd: false,
 };