neuronlayer 0.1.2 → 0.1.4

package/src/core/refresh/activity-gate.ts

@@ -0,0 +1,256 @@
+/**
+ * ActivityGate - Track user activity and manage idle-time maintenance tasks
+ *
+ * This component enables intelligent refresh by:
+ * 1. Tracking when the user was last active
+ * 2. Detecting idle periods
+ * 3. Executing maintenance tasks during idle time
+ * 4. Ensuring only one idle task runs at a time
+ */
+
+export interface IdleTask {
+  name: string;
+  callback: () => void | Promise<void>;
+  minIdleMs: number; // Minimum idle time before this task can run
+  lastRun: number;
+  intervalMs: number; // Minimum time between runs
+}
+
+export class ActivityGate {
+  private lastActivity: number = Date.now();
+  private idleTasks: IdleTask[] = [];
+  private monitoringInterval: ReturnType<typeof setInterval> | null = null;
+  private isExecutingTask: boolean = false;
+  private currentTaskIndex: number = 0;
+
+  constructor() {
+    // Activity is recorded at construction time
+    this.recordActivity();
+  }
+
+  /**
+   * Record user activity (call this on API method invocations)
+   */
+  recordActivity(): void {
+    this.lastActivity = Date.now();
+  }
+
+  /**
+   * Get the timestamp of the last recorded activity
+   */
+  getLastActivity(): number {
+    return this.lastActivity;
+  }
+
+  /**
+   * Check if the user has been idle for at least the given threshold
+   */
+  isIdle(thresholdMs: number = 30_000): boolean {
+    return Date.now() - this.lastActivity > thresholdMs;
+  }
+
+  /**
+   * Get the duration of the current idle period in milliseconds
+   */
+  getIdleDuration(): number {
+    return Date.now() - this.lastActivity;
+  }
+
+  /**
+   * Register an idle-time task
+   * Tasks are executed during idle periods, one at a time
+   */
+  registerIdleTask(
+    name: string,
+    callback: () => void | Promise<void>,
+    options: {
+      minIdleMs?: number;
+      intervalMs?: number;
+    } = {}
+  ): void {
+    const { minIdleMs = 30_000, intervalMs = 300_000 } = options;
+
+    // Remove existing task with same name
+    this.idleTasks = this.idleTasks.filter(t => t.name !== name);
+
+    this.idleTasks.push({
+      name,
+      callback,
+      minIdleMs,
+      lastRun: 0,
+      intervalMs
+    });
+  }
+
+  /**
+   * Unregister an idle-time task
+   */
+  unregisterIdleTask(name: string): boolean {
+    const initialLength = this.idleTasks.length;
+    this.idleTasks = this.idleTasks.filter(t => t.name !== name);
+    return this.idleTasks.length < initialLength;
+  }
+
+  /**
+   * Get all registered idle tasks
+   */
+  getIdleTasks(): readonly IdleTask[] {
+    return this.idleTasks;
+  }
+
+  /**
+   * Start monitoring for idle periods
+   * Will check every checkIntervalMs and execute tasks when idle
+   */
+  startIdleMonitoring(checkIntervalMs: number = 10_000): void {
+    if (this.monitoringInterval) {
+      return; // Already monitoring
+    }
+
+    this.monitoringInterval = setInterval(() => {
+      this.executeNextIdleTaskIfReady();
+    }, checkIntervalMs);
+  }
+
+  /**
+   * Stop idle monitoring
+   */
+  stopIdleMonitoring(): void {
+    if (this.monitoringInterval) {
+      clearInterval(this.monitoringInterval);
+      this.monitoringInterval = null;
+    }
+  }
+
+  /**
+   * Execute the next idle task if conditions are met
+   * - User must be idle
+   * - No other task is currently executing
+   * - Task's minimum idle time must be met
+   * - Task's minimum interval since last run must be met
+   */
+  private async executeNextIdleTaskIfReady(): Promise<void> {
+    if (this.isExecutingTask) {
+      return; // Already executing a task
+    }
+
+    if (this.idleTasks.length === 0) {
+      return; // No tasks registered
+    }
+
+    const now = Date.now();
+    const idleDuration = this.getIdleDuration();
+
+    // Find the next task that's ready to run
+    for (let i = 0; i < this.idleTasks.length; i++) {
+      const taskIndex = (this.currentTaskIndex + i) % this.idleTasks.length;
+      const task = this.idleTasks[taskIndex];
+
+      // Safety check (TypeScript strictness)
+      if (!task) continue;
+
+      // Check if task is ready
+      if (idleDuration < task.minIdleMs) {
+        continue; // Not idle long enough
+      }
+
+      if (now - task.lastRun < task.intervalMs) {
+        continue; // Too soon since last run
+      }
+
+      // Execute this task
+      this.currentTaskIndex = (taskIndex + 1) % this.idleTasks.length;
+      await this.executeTask(task);
+      return; // Only execute one task per check
+    }
+  }
+
+  /**
+   * Execute a specific task
+   */
+  private async executeTask(task: IdleTask): Promise<void> {
+    this.isExecutingTask = true;
+
+    try {
+      await Promise.resolve(task.callback());
+      task.lastRun = Date.now();
+    } catch (error) {
+      console.error(`Idle task '${task.name}' failed:`, error);
+      // Still update lastRun to prevent rapid retries
+      task.lastRun = Date.now();
+    } finally {
+      this.isExecutingTask = false;
+    }
+  }
+
+  /**
+   * Manually trigger execution of all ready idle tasks
+   * Useful for testing or manual refresh
+   */
+  async executeReadyTasks(): Promise<string[]> {
+    const executed: string[] = [];
+    const now = Date.now();
+    const idleDuration = this.getIdleDuration();
+
+    for (const task of this.idleTasks) {
+      if (idleDuration >= task.minIdleMs && now - task.lastRun >= task.intervalMs) {
+        await this.executeTask(task);
+        executed.push(task.name);
+      }
+    }
+
+    return executed;
+  }
+
+  /**
+   * Force immediate execution of a specific task by name
+   * Ignores idle and interval requirements
+   */
+  async forceExecuteTask(name: string): Promise<boolean> {
+    const task = this.idleTasks.find(t => t.name === name);
+    if (!task) {
+      return false;
+    }
+
+    await this.executeTask(task);
+    return true;
+  }
+
+  /**
+   * Get status of all idle tasks
+   */
+  getStatus(): {
+    isIdle: boolean;
+    idleDuration: number;
+    isExecutingTask: boolean;
+    tasks: Array<{
+      name: string;
+      lastRun: number;
+      timeSinceRun: number;
+      readyToRun: boolean;
+    }>;
+  } {
+    const now = Date.now();
+    const idleDuration = this.getIdleDuration();
+
+    return {
+      isIdle: this.isIdle(),
+      idleDuration,
+      isExecutingTask: this.isExecutingTask,
+      tasks: this.idleTasks.map(task => ({
+        name: task.name,
+        lastRun: task.lastRun,
+        timeSinceRun: now - task.lastRun,
+        readyToRun: idleDuration >= task.minIdleMs && now - task.lastRun >= task.intervalMs
+      }))
+    };
+  }
+
+  /**
+   * Shutdown the activity gate
+   */
+  shutdown(): void {
+    this.stopIdleMonitoring();
+    this.idleTasks = [];
+  }
+}

package/src/core/refresh/git-staleness-checker.ts

@@ -0,0 +1,108 @@
+import { execSync } from 'child_process';
+
+/**
+ * GitStalenessChecker - Cheap HEAD caching and change detection
+ *
+ * Instead of running expensive `git log` operations, we cache the HEAD commit
+ * and only run full syncs when HEAD has changed. This reduces polling overhead
+ * from ~100ms+ to ~5ms per check.
+ */
+export class GitStalenessChecker {
+  private cachedHead: string | null = null;
+  private lastCheckTime: number = 0;
+  private projectPath: string;
+
+  constructor(projectPath: string) {
+    this.projectPath = projectPath;
+  }
+
+  /**
+   * Get the current HEAD commit hash
+   * This is a cheap operation (~5ms)
+   */
+  getCurrentHead(): string | null {
+    try {
+      const head = execSync('git rev-parse HEAD', {
+        cwd: this.projectPath,
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      return head;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if there are new commits since the last check
+   * Returns true if HEAD has changed (meaning we need to sync)
+   */
+  hasNewCommits(): boolean {
+    const current = this.getCurrentHead();
+    this.lastCheckTime = Date.now();
+
+    if (current === null) {
+      return false; // Not a git repo or git command failed
+    }
+
+    if (this.cachedHead === null) {
+      // First check - cache the current HEAD
+      this.cachedHead = current;
+      return false; // No need to sync on first check (assume we synced on init)
+    }
+
+    if (current !== this.cachedHead) {
+      // HEAD has changed - update cache and signal sync needed
+      this.cachedHead = current;
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Force update the cached HEAD (call after successful sync)
+   */
+  updateCachedHead(): void {
+    this.cachedHead = this.getCurrentHead();
+    this.lastCheckTime = Date.now();
+  }
+
+  /**
+   * Get the cached HEAD without checking git
+   */
+  getCachedHead(): string | null {
+    return this.cachedHead;
+  }
+
+  /**
+   * Get the time of the last check
+   */
+  getLastCheckTime(): number {
+    return this.lastCheckTime;
+  }
+
+  /**
+   * Get time since last check in milliseconds
+   */
+  getTimeSinceLastCheck(): number {
+    return Date.now() - this.lastCheckTime;
+  }
+
+  /**
+   * Check if enough time has passed since last check
+   * Default threshold is 30 seconds
+   */
+  shouldCheck(thresholdMs: number = 30_000): boolean {
+    return this.getTimeSinceLastCheck() > thresholdMs;
+  }
+
+  /**
+   * Reset the checker state (useful for testing)
+   */
+  reset(): void {
+    this.cachedHead = null;
+    this.lastCheckTime = 0;
+  }
+}

package/src/core/refresh/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Intelligent Refresh System for MemoryLayer
+ *
+ * This module provides a tiered refresh architecture:
+ *
+ * TIER 1: REAL-TIME (via file watcher)
+ * - File changes → Chokidar watcher → immediate invalidation
+ * - User queries → immediate tracking
+ * - File access → immediate hot cache update
+ *
+ * TIER 2: ON-DEMAND WITH CHEAP PRE-CHECK
+ * - Git sync → check HEAD first (5ms), only sync if changed
+ * - Summaries → check lastModified before regenerating
+ * - Bug diagnosis → sync git first if HEAD changed
+ *
+ * TIER 3: IDLE-TIME MAINTENANCE
+ * - When user idle > 30s AND git changed → sync git
+ * - When idle > 5min since last update → update importance scores
+ * - One task at a time, non-blocking
+ *
+ * TIER 4: SESSION-BASED
+ * - Engine init → full git sync
+ * - Shutdown → persist state
+ */
+
+export { GitStalenessChecker } from './git-staleness-checker.js';
+export { ActivityGate, type IdleTask } from './activity-gate.js';

package/src/core/summarizer.ts

@@ -246,6 +246,29 @@ export class FileSummarizer {
     return fileLastModified > summary.generatedAt;
   }
 
+  // Invalidate summary when file changes (event-driven)
+  invalidateSummary(fileId: number): boolean {
+    try {
+      const result = this.db.prepare('DELETE FROM file_summaries WHERE file_id = ?').run(fileId);
+      return result.changes > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  // Invalidate summary by file path
+  invalidateSummaryByPath(filePath: string): boolean {
+    try {
+      const file = this.db.prepare('SELECT id FROM files WHERE path = ?').get(filePath) as { id: number } | undefined;
+      if (file) {
+        return this.invalidateSummary(file.id);
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
   // Get compression ratio stats
   getCompressionStats(): { totalFiles: number; avgCompression: number; totalTokensSaved: number } {
     const stmt = this.db.prepare(`

package/src/server/tools.ts

@@ -890,6 +890,28 @@ export const toolDefinitions: ToolDefinition[] = [
       },
       required: ['file']
     }
+  },
+  // Intelligent Refresh System tools
+  {
+    name: 'memory_refresh',
+    description: 'Trigger a manual refresh of the memory layer. Syncs git changes, updates importance scores, and executes pending maintenance tasks. Use this when you need the latest state after external changes (e.g., git pull).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        force: {
+          type: 'boolean',
+          description: 'Force refresh even if no changes detected (default: false)'
+        }
+      }
+    }
+  },
+  {
+    name: 'get_refresh_status',
+    description: 'Get the current status of the intelligent refresh system including idle tasks, last activity, and git state.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
   }
 ];
 
@@ -2255,6 +2277,54 @@ export async function handleToolCall(
       };
     }
 
+    // Intelligent Refresh System tools
+    case 'memory_refresh': {
+      const force = args.force as boolean | undefined;
+
+      if (force) {
+        const result = engine.triggerRefresh();
+        return {
+          success: true,
+          forced: true,
+          git_synced: result.gitSynced,
+          importance_updated: result.importanceUpdated,
+          tasks_executed: result.tasksExecuted,
+          message: `Force refresh complete: ${result.gitSynced} git changes synced`
+        };
+      } else {
+        // Normal refresh - only sync if there are new commits
+        const gitSynced = engine.syncGitChanges();
+        return {
+          success: true,
+          forced: false,
+          git_synced: gitSynced,
+          message: gitSynced > 0
+            ? `Refresh complete: ${gitSynced} git changes synced`
+            : 'No new changes to sync'
+        };
+      }
+    }
+
+    case 'get_refresh_status': {
+      const status = engine.getRefreshStatus();
+
+      return {
+        last_activity: new Date(status.lastActivity).toISOString(),
+        is_idle: status.isIdle,
+        idle_duration_seconds: Math.round(status.idleDuration / 1000),
+        git_head: status.gitHead?.slice(0, 7) || null,
+        has_pending_changes: status.hasNewCommits,
+        idle_tasks: status.idleTasks.map(t => ({
+          name: t.name,
+          last_run: t.lastRun > 0 ? new Date(t.lastRun).toISOString() : 'never',
+          ready_to_run: t.readyToRun
+        })),
+        message: status.isIdle
+          ? `System idle for ${Math.round(status.idleDuration / 1000)}s, ${status.idleTasks.filter(t => t.readyToRun).length} task(s) ready`
+          : 'System active'
+      };
+    }
+
     default:
       throw new Error(`Unknown tool: ${toolName}`);
   }

package/src/storage/database.ts

@@ -252,6 +252,15 @@ export function initializeDatabase(dbPath: string): Database.Database {
     CREATE INDEX IF NOT EXISTS idx_test_index_file ON test_index(file_path);
     CREATE INDEX IF NOT EXISTS idx_test_index_name ON test_index(test_name);
     CREATE INDEX IF NOT EXISTS idx_test_covers_files ON test_index(covers_files);
+
+    -- Intelligent Refresh System: State persistence
+    CREATE TABLE IF NOT EXISTS refresh_state (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at INTEGER DEFAULT (unixepoch())
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_refresh_state_key ON refresh_state(key);
   `);
 
   return db;

package/CONTRIBUTING.md

@@ -1,127 +0,0 @@
-# Contributing to MemoryLayer
-
-Thank you for your interest in contributing to MemoryLayer! This document provides guidelines and information for contributors.
-
-## Code of Conduct
-
-Be respectful, inclusive, and constructive. We're all here to build something great together.
-
-## How to Contribute
-
-### Reporting Bugs
-
-1. Check existing issues to avoid duplicates
-2. Use a clear, descriptive title
-3. Include:
-   - Steps to reproduce
-   - Expected vs actual behavior
-   - Environment (OS, Node.js version)
-   - Relevant logs or error messages
-
-### Suggesting Features
-
-1. Check if the feature is already planned (see Roadmap in README)
-2. Open an issue with `[Feature]` prefix
-3. Describe the use case and proposed solution
-4. Be open to discussion and alternatives
-
-### Pull Requests
-
-1. Fork the repository
-2. Create a feature branch from `main`
-3. Make your changes
-4. Write/update tests as needed
-5. Run `npm run typecheck` and `npm test`
-6. Submit a PR with a clear description
-
-## Development Setup
-
-```bash
-# Clone your fork
-git clone https://github.com/YOUR_USERNAME/memorylayer.git
-cd memorylayer
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Type check
-npm run typecheck
-```
-
-## Project Structure
-
-```
-src/
-├── core/           # Business logic (engine, features)
-├── server/         # MCP server and tools
-├── storage/        # Data persistence (SQLite, vectors)
-├── indexing/       # File indexing and AST
-├── types/          # TypeScript type definitions
-├── utils/          # Shared utilities
-└── agent/          # Standalone agent (optional)
-```
-
-## Coding Standards
-
-### TypeScript
-
-- Use TypeScript strict mode
-- Prefer explicit types over `any`
-- Use interfaces for object shapes
-- Export types from `src/types/`
-
-### Code Style
-
-- Use meaningful variable/function names
-- Keep functions focused and small
-- Add comments for non-obvious logic
-- Follow existing patterns in the codebase
-
-### Testing
-
-- Write tests for new features
-- Tests go in `__tests__/` directories or `*.test.ts` files
-- Use Vitest for testing
-
-### Commits
-
-- Use clear, descriptive commit messages
-- Follow conventional commits when possible:
-  - `feat:` new features
-  - `fix:` bug fixes
-  - `docs:` documentation
-  - `refactor:` code restructuring
-  - `test:` test additions/changes
-
-## Areas Where Help Is Needed
-
-### High Priority
-
-1. **Language Support** - Add AST parsing for Python, Go, Rust
-2. **Bug Fixes** - Check open issues
-3. **Test Coverage** - Increase test coverage
-
-### Medium Priority
-
-1. **Documentation** - Improve README, add examples
-2. **Performance** - Optimize indexing and search
-3. **IDE Extensions** - VS Code extension
-
-### Good First Issues
-
-Look for issues labeled `good-first-issue` for beginner-friendly tasks.
-
-## Questions?
-
-- Open a Discussion on GitHub
-- Check existing issues and documentation
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the MIT License.