tlc-claude-code 1.2.26 → 1.2.28

package/server/lib/memory-hooks.js

@@ -0,0 +1,127 @@
+/**
+ * Memory Hooks - Hook memory system into TLC command lifecycle
+ */
+
+const { buildSessionContext } = require('./context-builder.js');
+const { observeAndRemember, processExchange } = require('./memory-observer.js');
+const { generateSessionSummary, formatSummary } = require('./session-summary.js');
+const { appendSessionLog } = require('./memory-writer.js');
+
+/**
+ * MemoryHooks class for stateful hook management
+ */
+class MemoryHooks {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.sessionStartTime = null;
+    this.responseCount = 0;
+  }
+
+  /**
+   * Called when session starts - returns context for injection
+   * @returns {Promise<{context: string}>}
+   */
+  async onSessionStart() {
+    this.sessionStartTime = Date.now();
+    this.responseCount = 0;
+
+    const context = await buildSessionContext(this.projectRoot);
+
+    return { context };
+  }
+
+  /**
+   * Called after each response - observes for patterns
+   * @param {string} response - The response text
+   * @returns {Promise<{detected: boolean}>}
+   */
+  async onResponse(response) {
+    this.responseCount++;
+
+    // Create exchange object from response
+    const exchange = { assistant: response };
+
+    // Process the exchange for patterns (synchronous detection)
+    const classified = await processExchange(exchange);
+
+    // Fire and forget the storage (non-blocking)
+    observeAndRemember(this.projectRoot, exchange);
+
+    const detected = classified.decisions.length > 0 ||
+      classified.preferences.length > 0 ||
+      classified.gotchas.length > 0 ||
+      classified.reasoning.length > 0;
+
+    return { detected };
+  }
+
+  /**
+   * Called when session ends - returns summary
+   * @returns {Promise<{summary: string}>}
+   */
+  async onSessionEnd() {
+    const summaryData = await generateSessionSummary(this.projectRoot);
+    const summary = formatSummary(summaryData);
+
+    // Log session end
+    await appendSessionLog(this.projectRoot, {
+      type: 'session_end',
+      responseCount: this.responseCount,
+      duration: Date.now() - this.sessionStartTime,
+    });
+
+    return { summary };
+  }
+
+  /**
+   * Called before a command runs
+   * @param {string} command - Command name
+   * @returns {Promise<{command: string}>}
+   */
+  async beforeCommand(command) {
+    await appendSessionLog(this.projectRoot, {
+      type: 'command_start',
+      command,
+    });
+
+    return { command };
+  }
+
+  /**
+   * Called after a command runs
+   * @param {string} command - Command name
+   * @param {Object} result - Command result
+   * @returns {Promise<{logged: boolean}>}
+   */
+  async afterCommand(command, result) {
+    await appendSessionLog(this.projectRoot, {
+      type: 'command_end',
+      command,
+      success: result?.success,
+    });
+
+    return { logged: true };
+  }
+}
+
+/**
+ * Create memory hooks for a project
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Hook functions
+ */
+function createMemoryHooks(projectRoot) {
+  const hooks = new MemoryHooks(projectRoot);
+
+  return {
+    onSessionStart: () => hooks.onSessionStart(),
+    onResponse: (response) => hooks.onResponse(response),
+    onSessionEnd: () => hooks.onSessionEnd(),
+    beforeCommand: (command) => hooks.beforeCommand(command),
+    afterCommand: (command, result) => hooks.afterCommand(command, result),
+  };
+}
+
+module.exports = {
+  createMemoryHooks,
+  MemoryHooks,
+};

package/server/lib/memory-hooks.test.js

@@ -0,0 +1,136 @@
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { createMemoryHooks, MemoryHooks } from './memory-hooks.js';
+import { initMemoryStructure } from './memory-storage.js';
+
+describe('memory-hooks', () => {
+  let testDir;
+
+  beforeEach(async () => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-hooks-test-'));
+    await initMemoryStructure(testDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  describe('createMemoryHooks', () => {
+    it('returns hooks object', () => {
+      const hooks = createMemoryHooks(testDir);
+
+      expect(hooks).toHaveProperty('onSessionStart');
+      expect(hooks).toHaveProperty('onResponse');
+      expect(hooks).toHaveProperty('onSessionEnd');
+      expect(hooks).toHaveProperty('beforeCommand');
+      expect(hooks).toHaveProperty('afterCommand');
+    });
+
+    it('hooks are callable functions', () => {
+      const hooks = createMemoryHooks(testDir);
+
+      expect(typeof hooks.onSessionStart).toBe('function');
+      expect(typeof hooks.onResponse).toBe('function');
+      expect(typeof hooks.onSessionEnd).toBe('function');
+    });
+  });
+
+  describe('onSessionStart', () => {
+    it('returns context for injection', async () => {
+      const hooks = createMemoryHooks(testDir);
+      const context = await hooks.onSessionStart();
+
+      expect(context).toHaveProperty('context');
+    });
+
+    it('returns empty context for new project', async () => {
+      const hooks = createMemoryHooks(testDir);
+      const result = await hooks.onSessionStart();
+
+      // New project has no memory, so context should be empty
+      expect(result.context).toBe('');
+    });
+  });
+
+  describe('onResponse', () => {
+    it('observes response for patterns', async () => {
+      const hooks = createMemoryHooks(testDir);
+
+      // Should not throw
+      await expect(hooks.onResponse('let\'s use PostgreSQL instead of MySQL')).resolves.not.toThrow();
+    });
+
+    it('returns detection results', async () => {
+      const hooks = createMemoryHooks(testDir);
+      const result = await hooks.onResponse('let\'s use PostgreSQL instead of MySQL');
+
+      expect(result).toHaveProperty('detected');
+    });
+  });
+
+  describe('onSessionEnd', () => {
+    it('returns session summary', async () => {
+      const hooks = createMemoryHooks(testDir);
+      const summary = await hooks.onSessionEnd();
+
+      expect(summary).toHaveProperty('summary');
+    });
+
+    it('includes formatted summary text', async () => {
+      const hooks = createMemoryHooks(testDir);
+      const result = await hooks.onSessionEnd();
+
+      expect(typeof result.summary).toBe('string');
+    });
+  });
+
+  describe('beforeCommand', () => {
+    it('runs without error', async () => {
+      const hooks = createMemoryHooks(testDir);
+
+      await expect(hooks.beforeCommand('build')).resolves.not.toThrow();
+    });
+
+    it('returns command context', async () => {
+      const hooks = createMemoryHooks(testDir);
+      const result = await hooks.beforeCommand('build');
+
+      expect(result).toHaveProperty('command');
+      expect(result.command).toBe('build');
+    });
+  });
+
+  describe('afterCommand', () => {
+    it('runs without error', async () => {
+      const hooks = createMemoryHooks(testDir);
+
+      await expect(hooks.afterCommand('build', { success: true })).resolves.not.toThrow();
+    });
+
+    it('logs command result', async () => {
+      const hooks = createMemoryHooks(testDir);
+      const result = await hooks.afterCommand('build', { success: true });
+
+      expect(result).toHaveProperty('logged');
+    });
+  });
+
+  describe('MemoryHooks class', () => {
+    it('can be instantiated', () => {
+      const hooks = new MemoryHooks(testDir);
+      expect(hooks).toBeInstanceOf(MemoryHooks);
+    });
+
+    it('shares state across calls', async () => {
+      const hooks = new MemoryHooks(testDir);
+
+      await hooks.onSessionStart();
+      await hooks.onResponse('test response');
+      const result = await hooks.onSessionEnd();
+
+      expect(result).toBeTruthy();
+    });
+  });
+});

package/server/lib/memory-init.js

@@ -0,0 +1,104 @@
+/**
+ * Memory Init - Initialize memory system directories
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Directory structure for memory system
+ */
+const MEMORY_STRUCTURE = {
+  team: ['decisions', 'gotchas'],
+  local: ['preferences', 'sessions'],
+};
+
+/**
+ * Initialize the memory system directories
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<{created: boolean, directories: string[]}>}
+ */
+async function initMemorySystem(projectRoot) {
+  const memoryRoot = path.join(projectRoot, '.tlc', 'memory');
+  const created = [];
+
+  // Create team directories
+  for (const subdir of MEMORY_STRUCTURE.team) {
+    const dirPath = path.join(memoryRoot, 'team', subdir);
+    try {
+      await fs.mkdir(dirPath, { recursive: true });
+      created.push(dirPath);
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+    }
+  }
+
+  // Create local directories
+  for (const subdir of MEMORY_STRUCTURE.local) {
+    const dirPath = path.join(memoryRoot, '.local', subdir);
+    try {
+      await fs.mkdir(dirPath, { recursive: true });
+      created.push(dirPath);
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+    }
+  }
+
+  // Ensure .gitignore has .local entry
+  const gitignorePath = path.join(memoryRoot, '.gitignore');
+  let gitignoreContent = '';
+  try {
+    gitignoreContent = await fs.readFile(gitignorePath, 'utf-8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  if (!gitignoreContent.includes('.local')) {
+    const newContent = gitignoreContent
+      ? gitignoreContent.trim() + '\n.local\n'
+      : '.local\n';
+    await fs.writeFile(gitignorePath, newContent, 'utf-8');
+  }
+
+  return {
+    created: created.length > 0,
+    directories: created,
+  };
+}
+
+/**
+ * Check if memory system is initialized
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<boolean>}
+ */
+async function isMemoryInitialized(projectRoot) {
+  const memoryRoot = path.join(projectRoot, '.tlc', 'memory');
+
+  // Check team directories
+  for (const subdir of MEMORY_STRUCTURE.team) {
+    const dirPath = path.join(memoryRoot, 'team', subdir);
+    try {
+      await fs.access(dirPath);
+    } catch {
+      return false;
+    }
+  }
+
+  // Check local directories
+  for (const subdir of MEMORY_STRUCTURE.local) {
+    const dirPath = path.join(memoryRoot, '.local', subdir);
+    try {
+      await fs.access(dirPath);
+    } catch {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+module.exports = {
+  initMemorySystem,
+  isMemoryInitialized,
+  MEMORY_STRUCTURE,
+};

package/server/lib/memory-init.test.js

@@ -0,0 +1,119 @@
+import { describe, it, beforeEach, afterEach, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { initMemorySystem, isMemoryInitialized } from './memory-init.js';
+
+describe('memory-init', () => {
+  let testDir;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-memory-init-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  describe('initMemorySystem', () => {
+    it('creates .tlc/memory/team directory', async () => {
+      await initMemorySystem(testDir);
+
+      const teamDir = path.join(testDir, '.tlc', 'memory', 'team');
+      expect(fs.existsSync(teamDir)).toBe(true);
+    });
+
+    it('creates .tlc/memory/.local directory', async () => {
+      await initMemorySystem(testDir);
+
+      const localDir = path.join(testDir, '.tlc', 'memory', '.local');
+      expect(fs.existsSync(localDir)).toBe(true);
+    });
+
+    it('creates subdirectories in team', async () => {
+      await initMemorySystem(testDir);
+
+      const decisionsDir = path.join(testDir, '.tlc', 'memory', 'team', 'decisions');
+      const gotchasDir = path.join(testDir, '.tlc', 'memory', 'team', 'gotchas');
+      expect(fs.existsSync(decisionsDir)).toBe(true);
+      expect(fs.existsSync(gotchasDir)).toBe(true);
+    });
+
+    it('creates subdirectories in .local', async () => {
+      await initMemorySystem(testDir);
+
+      const preferencesDir = path.join(testDir, '.tlc', 'memory', '.local', 'preferences');
+      const sessionsDir = path.join(testDir, '.tlc', 'memory', '.local', 'sessions');
+      expect(fs.existsSync(preferencesDir)).toBe(true);
+      expect(fs.existsSync(sessionsDir)).toBe(true);
+    });
+
+    it('adds .local to .gitignore if not present', async () => {
+      await initMemorySystem(testDir);
+
+      const gitignorePath = path.join(testDir, '.tlc', 'memory', '.gitignore');
+      expect(fs.existsSync(gitignorePath)).toBe(true);
+      const content = fs.readFileSync(gitignorePath, 'utf-8');
+      expect(content).toContain('.local');
+    });
+
+    it('does not duplicate .local in .gitignore', async () => {
+      const gitignorePath = path.join(testDir, '.tlc', 'memory', '.gitignore');
+      fs.mkdirSync(path.dirname(gitignorePath), { recursive: true });
+      fs.writeFileSync(gitignorePath, '.local\n');
+
+      await initMemorySystem(testDir);
+
+      const content = fs.readFileSync(gitignorePath, 'utf-8');
+      const matches = content.match(/\.local/g);
+      expect(matches.length).toBe(1);
+    });
+
+    it('skips creation if already exists', async () => {
+      const teamDir = path.join(testDir, '.tlc', 'memory', 'team', 'decisions');
+      fs.mkdirSync(teamDir, { recursive: true });
+      fs.writeFileSync(path.join(teamDir, 'test.json'), '{"test": true}');
+
+      await initMemorySystem(testDir);
+
+      // File should still exist
+      expect(fs.existsSync(path.join(teamDir, 'test.json'))).toBe(true);
+    });
+
+    it('returns initialization status', async () => {
+      const result = await initMemorySystem(testDir);
+
+      expect(result).toHaveProperty('created');
+      expect(result).toHaveProperty('directories');
+    });
+
+    it('handles missing .tlc directory', async () => {
+      // Should create .tlc directory if not present
+      await initMemorySystem(testDir);
+
+      expect(fs.existsSync(path.join(testDir, '.tlc'))).toBe(true);
+    });
+  });
+
+  describe('isMemoryInitialized', () => {
+    it('returns false for empty directory', async () => {
+      const result = await isMemoryInitialized(testDir);
+      expect(result).toBe(false);
+    });
+
+    it('returns true after initialization', async () => {
+      await initMemorySystem(testDir);
+
+      const result = await isMemoryInitialized(testDir);
+      expect(result).toBe(true);
+    });
+
+    it('returns false for partial initialization', async () => {
+      // Only create team dir, not local
+      fs.mkdirSync(path.join(testDir, '.tlc', 'memory', 'team'), { recursive: true });
+
+      const result = await isMemoryInitialized(testDir);
+      expect(result).toBe(false);
+    });
+  });
+});

package/server/lib/memory-observer.js

@@ -0,0 +1,149 @@
+/**
+ * Memory Observer - Non-blocking capture of memorable patterns from exchanges
+ */
+
+const { detectPatterns } = require('./pattern-detector.js');
+const { classifyMemory, CLASSIFICATION } = require('./memory-classifier.js');
+const { writeTeamDecision, writeTeamGotcha, writePersonalPreference, appendSessionLog } = require('./memory-writer.js');
+
+/**
+ * Process an exchange and extract patterns with classification
+ * @param {Object} exchange - Conversation exchange
+ * @returns {Object} Extracted patterns with classification
+ */
+async function processExchange(exchange) {
+  const patterns = detectPatterns(exchange);
+
+  // Add classification to each pattern
+  const classified = {
+    decisions: patterns.decisions.map(d => ({
+      ...d,
+      classification: classifyMemory(d),
+    })),
+    preferences: patterns.preferences.map(p => ({
+      ...p,
+      classification: classifyMemory(p),
+    })),
+    gotchas: patterns.gotchas.map(g => ({
+      ...g,
+      classification: classifyMemory(g),
+    })),
+    reasoning: patterns.reasoning.map(r => ({
+      ...r,
+      classification: classifyMemory(r),
+    })),
+  };
+
+  return classified;
+}
+
+/**
+ * Store extracted patterns to appropriate storage
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} classified - Classified patterns
+ */
+async function storePatterns(projectRoot, classified) {
+  // Store team decisions
+  for (const decision of classified.decisions) {
+    if (decision.classification === CLASSIFICATION.TEAM) {
+      try {
+        await writeTeamDecision(projectRoot, {
+          title: decision.choice || 'Decision',
+          reasoning: decision.reasoning || decision.raw || '',
+          context: decision.over ? `Chosen over ${decision.over}` : undefined,
+        });
+      } catch (e) {
+        console.error('Failed to write team decision:', e.message);
+      }
+    }
+  }
+
+  // Store team gotchas
+  for (const gotcha of classified.gotchas) {
+    if (gotcha.classification === CLASSIFICATION.TEAM) {
+      try {
+        await writeTeamGotcha(projectRoot, {
+          title: gotcha.subject || 'Gotcha',
+          issue: gotcha.issue || gotcha.raw || '',
+          severity: 'medium',
+        });
+      } catch (e) {
+        console.error('Failed to write team gotcha:', e.message);
+      }
+    }
+  }
+
+  // Store personal preferences
+  for (const pref of classified.preferences) {
+    if (pref.classification === CLASSIFICATION.PERSONAL) {
+      try {
+        const key = pref.category || 'learned';
+        await writePersonalPreference(projectRoot, key, {
+          preference: pref.preference,
+          antiPreference: pref.antiPreference,
+          raw: pref.raw,
+        });
+      } catch (e) {
+        console.error('Failed to write personal preference:', e.message);
+      }
+    }
+  }
+}
+
+/**
+ * Log the exchange to session log
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} classified - Classified patterns
+ */
+async function logToSession(projectRoot, classified) {
+  const hasContent =
+    classified.decisions.length > 0 ||
+    classified.preferences.length > 0 ||
+    classified.gotchas.length > 0 ||
+    classified.reasoning.length > 0;
+
+  if (!hasContent) return;
+
+  try {
+    await appendSessionLog(projectRoot, {
+      type: 'memory_capture',
+      decisions: classified.decisions.length,
+      preferences: classified.preferences.length,
+      gotchas: classified.gotchas.length,
+      reasoning: classified.reasoning.length,
+    });
+  } catch (e) {
+    console.error('Failed to log to session:', e.message);
+  }
+}
+
+/**
+ * Observe an exchange and remember memorable patterns
+ * Fire-and-forget async - does not block
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} exchange - Conversation exchange
+ */
+async function observeAndRemember(projectRoot, exchange) {
+  // Fire and forget - don't await the full processing
+  setImmediate(async () => {
+    try {
+      const classified = await processExchange(exchange);
+
+      // Store patterns (errors are caught inside)
+      await storePatterns(projectRoot, classified);
+
+      // Log to session
+      await logToSession(projectRoot, classified);
+    } catch (e) {
+      // Silently fail - memory is nice-to-have, not critical
+      console.error('Memory observation failed:', e.message);
+    }
+  });
+}
+
+module.exports = {
+  observeAndRemember,
+  processExchange,
+  storePatterns,
+  logToSession,
+};