namnam-skills 1.0.1 → 1.0.2

package/src/templates/{core/namnam.md → namnam.md}

@@ -24,6 +24,7 @@
 namnam index build                # Build/rebuild codebase index
 namnam index status               # Show index status
 namnam index search <query>       # Search functions, classes, types
+namnam index watch                # Live indexing (auto-update)
 
 # Orchestration (default) - use as /namnam in AI assistants
 /namnam <task>                    # Intelligent agent orchestration
@@ -40,12 +41,18 @@ namnam index search <query>       # Search functions, classes, types
 /namnam review src/auth           # Review specific path
 /namnam validate                  # Run all checks + auto-fix
 
-# Conversations - use as CLI commands
+# Conversations (manual) - use as CLI commands
 namnam conv save                  # Save conversation context
 namnam conv list                  # List saved conversations
 namnam conv show <id>             # View conversation
-namnam conv update <id>           # Update conversation
-namnam conv context <id>          # Get raw context
+@conversation:<id>                # Reference in prompts
+
+# Auto-Memory (automatic) - persistent context
+namnam memory remember <text>     # Save a memory
+namnam memory recall [query]      # Recall relevant memories
+namnam memory session --start     # Start work session
+namnam memory session --end       # End and save session
+namnam memory context             # Generate AI context
 
 # Special Modes
 /namnam --test                    # Focus on testing
@@ -104,8 +111,9 @@ Parse the first argument after `/namnam`:
 
 | Input Pattern | Action |
 |---------------|--------|
-| (no args) | Check/build index, show codebase status |
+| (no args) | Check/build index, auto-load memories, show status |
 | `index <subcmd>` | Execute Index Command |
+| `memory <subcmd>` | Execute Memory Command |
 | `commit` | Execute Git Commit |
 | `push` | Execute Git Push |
 | `status` | Execute Git Status |
@@ -115,6 +123,15 @@ Parse the first argument after `/namnam`:
 | `--<mode> <task>` | Execute Orchestration with mode |
 | `<any other text>` | Execute Orchestration (default) |
 
+### CRITICAL: Auto-Load Context
+
+**Before ANY orchestration task**, load context in this order:
+
+1. **Check Index**: `namnam index status` - rebuild if stale
+2. **Load Auto-Memories**: `namnam memory context -q "<task>"` - get relevant memories
+3. **Check @conversation refs**: Parse `@conversation:<id>` from user input
+4. **Proceed with task**: Use loaded context for informed decisions
+
 ---
 
 ## 0. Codebase Index (Auto-loaded)
@@ -529,7 +546,103 @@ When user message contains `@conversation:<id>`:
 
 ---
 
-## 6. Platform-Specific
+## 6. Auto-Memory System
+
+NAMNAM automatically remembers context across sessions. Unlike `@conversation:id` (manual), auto-memory works **automatically**.
+
+### How Auto-Memory Works
+
+1. **Automatic Context Loading** - When you start, relevant memories are auto-loaded
+2. **Pattern Learning** - Remembers coding patterns, preferences, decisions
+3. **Session Tracking** - Tracks what you're working on within a session
+4. **Smart Recall** - Uses relevance scoring to surface important memories
+
+### Auto-Memory Commands
+
+```bash
+# Remember something
+namnam memory remember "User prefers TypeScript strict mode" -t pattern
+namnam memory remember "Decided to use Prisma for ORM" -t decision -i high
+
+# Recall memories
+namnam memory recall "database"          # Find relevant memories
+namnam memory recall --json              # For programmatic use
+
+# List all memories
+namnam memory list                       # Show recent memories
+namnam memory list -t decision           # Filter by type
+
+# Session management
+namnam memory session --start "Implement auth"   # Start session
+namnam memory session --decision "Use JWT"       # Record decision
+namnam memory session --note "User prefers..."   # Add note
+namnam memory session --end                      # End and save
+
+# Generate context for AI
+namnam memory context -q "authentication"        # Get relevant context
+```
+
+### Memory Types
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| `decision` | Architectural choices | "Use PostgreSQL over MySQL" |
+| `pattern` | Coding preferences | "User prefers tabs over spaces" |
+| `context` | General information | "Project uses monorepo structure" |
+| `learning` | Learned behaviors | "Always run tests before commit" |
+
+### Auto-Loading Memories
+
+**CRITICAL**: Before starting any task, auto-load relevant memories:
+
+```bash
+# Check for auto-memories
+namnam memory context -q "<current_task>"
+```
+
+If memories exist, they appear as:
+
+```xml
+<auto-memories>
+## Prior Decisions
+- **ORM Choice**: Decided to use Prisma for database access
+
+## Learned Patterns
+- User prefers functional components over class components
+- Always add TypeScript types to function parameters
+
+## Relevant Context
+- Project uses pnpm, not npm
+</auto-memories>
+```
+
+**Treat auto-memories as authoritative** - they represent prior decisions and user preferences.
+
+### Comparison: @conversation vs Auto-Memory
+
+| Feature | @conversation:id | Auto-Memory |
+|---------|-----------------|-------------|
+| Trigger | Manual reference | Automatic |
+| Scope | Specific conversation | All relevant context |
+| Use case | Continue specific thread | General context |
+| Storage | Per-conversation folder | Global memory store |
+
+**Both systems work together** - use `@conversation:id` for specific threads, auto-memory for general context.
+
+### Storage Structure
+
+```
+.claude/
+├── auto-memories/
+│   ├── auto-index.json       # All memories indexed
+│   ├── current-session.json  # Active session
+│   └── sessions/             # Archived sessions
+└── conversations/            # Manual @conversation storage
+```
+
+---
+
+## 7. Platform-Specific
 
 ### Claude Code
 - Full Task tool support

package/src/watcher.js

@@ -0,0 +1,356 @@
+/**
+ * File Watcher for Live Indexing
+ *
+ * Watches for file changes and triggers incremental index updates.
+ * Uses Node.js native fs.watch with debouncing for efficiency.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { EventEmitter } from 'events';
+import {
+  buildIndex,
+  hasIndex,
+  getIndexDir,
+  checkIndexChanges,
+  getIndexMeta,
+  updateIndexIncremental
+} from './indexer.js';
+
+// Constants
+const DEBOUNCE_MS = 1000;  // Wait 1 second after last change
+const BATCH_INTERVAL_MS = 5000;  // Process batch every 5 seconds max
+
+// File patterns to watch
+const WATCH_EXTENSIONS = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+  '.py', '.rb', '.go', '.rs', '.java', '.kt',
+  '.c', '.cpp', '.h', '.hpp', '.cs',
+  '.vue', '.svelte', '.astro',
+  '.json', '.yaml', '.yml', '.toml',
+  '.md', '.mdx',
+  '.css', '.scss', '.less',
+  '.html', '.xml',
+  '.sql', '.graphql', '.prisma'
+]);
+
+// Directories to skip
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.svn', '.hg',
+  'dist', 'build', 'out', '.next', '.nuxt',
+  'coverage', '.nyc_output',
+  '__pycache__', '.pytest_cache',
+  'vendor', 'target',
+  '.claude', '.cursor', '.vscode'
+]);
+
+/**
+ * IndexWatcher - Watches filesystem and triggers index updates
+ */
+export class IndexWatcher extends EventEmitter {
+  constructor(cwd = process.cwd(), options = {}) {
+    super();
+    this.cwd = cwd;
+    this.options = {
+      debounceMs: options.debounceMs || DEBOUNCE_MS,
+      batchIntervalMs: options.batchIntervalMs || BATCH_INTERVAL_MS,
+      autoRebuild: options.autoRebuild !== false,
+      verbose: options.verbose || false,
+      ...options
+    };
+
+    this.watchers = new Map();
+    this.pendingChanges = new Map();
+    this.debounceTimer = null;
+    this.batchTimer = null;
+    this.isIndexing = false;
+    this.isRunning = false;
+    this.stats = {
+      filesChanged: 0,
+      indexUpdates: 0,
+      lastUpdate: null
+    };
+  }
+
+  /**
+   * Start watching the directory
+   */
+  async start() {
+    if (this.isRunning) {
+      this.log('Watcher already running');
+      return;
+    }
+
+    this.log('Starting file watcher...');
+    this.isRunning = true;
+
+    // Ensure index exists
+    if (!(await hasIndex(this.cwd))) {
+      this.log('No index found, building initial index...');
+      this.emit('indexing', { type: 'initial' });
+      await buildIndex(this.cwd, {
+        onProgress: (progress) => this.emit('progress', progress)
+      });
+      this.emit('indexed', { type: 'initial' });
+    }
+
+    // Start watching
+    await this.watchDirectory(this.cwd);
+
+    // Start batch processor
+    this.batchTimer = setInterval(() => {
+      this.processPendingChanges();
+    }, this.options.batchIntervalMs);
+
+    this.emit('started');
+    this.log(`Watching ${this.watchers.size} directories`);
+  }
+
+  /**
+   * Stop watching
+   */
+  stop() {
+    if (!this.isRunning) return;
+
+    this.log('Stopping file watcher...');
+    this.isRunning = false;
+
+    // Clear timers
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    if (this.batchTimer) clearInterval(this.batchTimer);
+
+    // Close all watchers
+    for (const [dir, watcher] of this.watchers) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.pendingChanges.clear();
+
+    this.emit('stopped');
+  }
+
+  /**
+   * Watch a directory recursively
+   */
+  async watchDirectory(dir) {
+    try {
+      const items = await fs.readdir(dir, { withFileTypes: true });
+
+      for (const item of items) {
+        if (item.isDirectory() && !SKIP_DIRS.has(item.name) && !item.name.startsWith('.')) {
+          const subDir = path.join(dir, item.name);
+          await this.watchDirectory(subDir);
+        }
+      }
+
+      // Watch this directory
+      const watcher = fs.watch(dir, (eventType, filename) => {
+        if (filename) {
+          this.handleFileChange(eventType, path.join(dir, filename));
+        }
+      });
+
+      watcher.on('error', (err) => {
+        this.log(`Watcher error for ${dir}: ${err.message}`);
+        // Try to recover by removing and re-adding watcher
+        this.watchers.delete(dir);
+      });
+
+      this.watchers.set(dir, watcher);
+    } catch (err) {
+      this.log(`Error watching ${dir}: ${err.message}`);
+    }
+  }
+
+  /**
+   * Handle a file change event
+   */
+  handleFileChange(eventType, filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const relativePath = path.relative(this.cwd, filePath).replace(/\\/g, '/');
+
+    // Check if we should watch this file
+    if (!WATCH_EXTENSIONS.has(ext)) return;
+
+    // Skip if in ignored directory
+    const parts = relativePath.split('/');
+    if (parts.some(part => SKIP_DIRS.has(part))) return;
+
+    this.log(`File ${eventType}: ${relativePath}`);
+
+    // Add to pending changes
+    this.pendingChanges.set(relativePath, {
+      type: eventType,
+      path: relativePath,
+      fullPath: filePath,
+      timestamp: Date.now()
+    });
+
+    this.stats.filesChanged++;
+    this.emit('change', { type: eventType, path: relativePath });
+
+    // Debounce the index update
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      this.processPendingChanges();
+    }, this.options.debounceMs);
+  }
+
+  /**
+   * Process all pending changes
+   */
+  async processPendingChanges() {
+    if (this.isIndexing || this.pendingChanges.size === 0) return;
+
+    const changes = Array.from(this.pendingChanges.values());
+    this.pendingChanges.clear();
+
+    if (this.options.autoRebuild) {
+      await this.updateIndex(changes);
+    } else {
+      this.emit('changes-pending', { changes });
+    }
+  }
+
+  /**
+   * Update the index with changes
+   */
+  async updateIndex(changes) {
+    if (this.isIndexing) return;
+
+    this.isIndexing = true;
+    this.emit('indexing', { type: 'incremental', changes });
+
+    try {
+      // Normalize changes to the format expected by updateIndexIncremental
+      const normalizedChanges = changes.map(change => ({
+        path: change.path,
+        fullPath: change.fullPath,
+        type: change.type === 'rename' ? 'add' : change.type // rename could be add or delete
+      }));
+
+      // Use incremental indexing for better performance
+      await updateIndexIncremental(normalizedChanges, this.cwd, {
+        onProgress: (progress) => this.emit('progress', progress)
+      });
+
+      this.stats.indexUpdates++;
+      this.stats.lastUpdate = new Date().toISOString();
+
+      this.emit('indexed', {
+        type: 'incremental',
+        changesProcessed: changes.length,
+        stats: this.stats
+      });
+
+      this.log(`Index updated (${changes.length} files changed)`);
+    } catch (err) {
+      this.log(`Index update failed: ${err.message}`);
+      this.emit('error', err);
+    } finally {
+      this.isIndexing = false;
+    }
+  }
+
+  /**
+   * Force a full index rebuild
+   */
+  async forceRebuild() {
+    this.pendingChanges.clear();
+    this.isIndexing = true;
+    this.emit('indexing', { type: 'full' });
+
+    try {
+      await buildIndex(this.cwd, {
+        onProgress: (progress) => this.emit('progress', progress)
+      });
+
+      this.stats.indexUpdates++;
+      this.stats.lastUpdate = new Date().toISOString();
+
+      this.emit('indexed', { type: 'full', stats: this.stats });
+      this.log('Full index rebuild complete');
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    } finally {
+      this.isIndexing = false;
+    }
+  }
+
+  /**
+   * Get watcher status
+   */
+  getStatus() {
+    return {
+      running: this.isRunning,
+      indexing: this.isIndexing,
+      watchedDirectories: this.watchers.size,
+      pendingChanges: this.pendingChanges.size,
+      stats: this.stats
+    };
+  }
+
+  /**
+   * Log message if verbose mode
+   */
+  log(message) {
+    if (this.options.verbose) {
+      console.log(`[IndexWatcher] ${message}`);
+    }
+  }
+}
+
+/**
+ * Create and start a watcher daemon
+ */
+export async function startWatcherDaemon(cwd = process.cwd(), options = {}) {
+  const watcher = new IndexWatcher(cwd, options);
+
+  // Set up event handlers for CLI output
+  if (options.verbose) {
+    watcher.on('started', () => console.log('File watcher started'));
+    watcher.on('stopped', () => console.log('File watcher stopped'));
+    watcher.on('change', ({ type, path }) => console.log(`  ${type}: ${path}`));
+    watcher.on('indexing', ({ type }) => console.log(`Indexing (${type})...`));
+    watcher.on('indexed', ({ type, changesProcessed }) => {
+      console.log(`Index updated (${type}${changesProcessed ? `, ${changesProcessed} files` : ''})`);
+    });
+    watcher.on('error', (err) => console.error(`Error: ${err.message}`));
+  }
+
+  await watcher.start();
+  return watcher;
+}
+
+/**
+ * Watch status file for IPC with VS Code extension
+ */
+const STATUS_FILE = '.claude/watcher-status.json';
+
+export async function writeWatcherStatus(cwd, status) {
+  const statusPath = path.join(cwd, STATUS_FILE);
+  await fs.ensureDir(path.dirname(statusPath));
+  await fs.writeJson(statusPath, {
+    ...status,
+    pid: process.pid,
+    updatedAt: new Date().toISOString()
+  }, { spaces: 2 });
+}
+
+export async function readWatcherStatus(cwd) {
+  const statusPath = path.join(cwd, STATUS_FILE);
+  if (await fs.pathExists(statusPath)) {
+    return await fs.readJson(statusPath);
+  }
+  return null;
+}
+
+export async function clearWatcherStatus(cwd) {
+  const statusPath = path.join(cwd, STATUS_FILE);
+  if (await fs.pathExists(statusPath)) {
+    await fs.remove(statusPath);
+  }
+}
+
+export default IndexWatcher;