@pcircle/memesh 2.9.2 → 2.9.3

package/scripts/hooks/__tests__/session-start-recall.test.js

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import { buildSessionRecallQuery, formatRecallOutput } from '../session-start-recall-utils.js';
+
+describe('buildSessionRecallQuery', () => {
+  it('combines project name and commits', () => {
+    const result = buildSessionRecallQuery('my-project', ['add login page', 'fix header bug']);
+    expect(result).toBe('my-project add login page fix header bug');
+  });
+
+  it('handles empty commits array', () => {
+    const result = buildSessionRecallQuery('my-project', []);
+    expect(result).toBe('my-project');
+  });
+
+  it('handles undefined commits', () => {
+    const result = buildSessionRecallQuery('my-project');
+    expect(result).toBe('my-project');
+  });
+
+  it('strips conventional commit prefixes', () => {
+    const commits = [
+      'fix: resolve null pointer',
+      'feat(auth): add OAuth support',
+      'chore(deps): update dependencies',
+      'refactor: simplify logic',
+    ];
+    const result = buildSessionRecallQuery('app', commits);
+    expect(result).toBe('app resolve null pointer add OAuth support update dependencies simplify logic');
+  });
+
+  it('filters out empty strings after stripping prefixes', () => {
+    const commits = ['fix:', 'feat(scope): '];
+    const result = buildSessionRecallQuery('app', commits);
+    expect(result).toBe('app');
+  });
+});
+
+describe('formatRecallOutput', () => {
+  it('formats results with similarity percentage', () => {
+    const results = [
+      { name: 'Entity1', observations: ['obs1', 'obs2'], similarity: 0.85 },
+    ];
+    const output = formatRecallOutput(results);
+    expect(output).toBe('  - Entity1 (85%): obs1; obs2');
+  });
+
+  it('returns empty string for empty results', () => {
+    expect(formatRecallOutput([])).toBe('');
+  });
+
+  it('returns empty string for null results', () => {
+    expect(formatRecallOutput(null)).toBe('');
+  });
+
+  it('returns empty string for undefined results', () => {
+    expect(formatRecallOutput(undefined)).toBe('');
+  });
+
+  it('limits observations to 2', () => {
+    const results = [
+      { name: 'Entity1', observations: ['obs1', 'obs2', 'obs3', 'obs4'], similarity: 0.7 },
+    ];
+    const output = formatRecallOutput(results);
+    expect(output).toBe('  - Entity1 (70%): obs1; obs2');
+  });
+
+  it('formats multiple results on separate lines', () => {
+    const results = [
+      { name: 'A', observations: ['a1'], similarity: 0.9 },
+      { name: 'B', observations: ['b1', 'b2'], similarity: 0.6 },
+    ];
+    const output = formatRecallOutput(results);
+    const lines = output.split('\n');
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toBe('  - A (90%): a1');
+    expect(lines[1]).toBe('  - B (60%): b1; b2');
+  });
+
+  it('rounds similarity percentage', () => {
+    const results = [
+      { name: 'X', observations: ['x1'], similarity: 0.456 },
+    ];
+    const output = formatRecallOutput(results);
+    expect(output).toBe('  - X (46%): x1');
+  });
+});

package/scripts/hooks/post-tool-use-recall-utils.js

@@ -0,0 +1,74 @@
+/**
+ * Post-Tool-Use Recall Utilities
+ *
+ * Pure functions for detecting test failures and errors in tool output,
+ * used by the proactive recall system in post-tool-use.js.
+ */
+
+const TEST_PATTERNS = [
+  /vitest\s*(run|watch)?/i,
+  /jest\b/i,
+  /npm\s+test/i,
+  /npm\s+run\s+test/i,
+  /npx\s+vitest/i,
+  /npx\s+jest/i,
+  /pytest\b/i,
+  /bun\s+test/i,
+  /mocha\b/i,
+];
+
+/**
+ * Check if a command string is a test runner invocation.
+ * @param {string} command - Shell command to check
+ * @returns {boolean}
+ */
+export function isTestCommand(command) {
+  if (!command) return false;
+  return TEST_PATTERNS.some(p => p.test(command));
+}
+
+/**
+ * Extract test failure context (test name + error message) from test output.
+ * Returns null if no failure is detected.
+ * @param {string} output - Test runner stdout/stderr
+ * @returns {{ testName: string, errorMessage: string } | null}
+ */
+export function extractTestFailureContext(output) {
+  if (!output) return null;
+  const hasFailure = /FAIL|failed|failing|\u2715|\u2717|error/i.test(output);
+  if (!hasFailure) return null;
+
+  const fileMatch = output.match(/FAIL\s+(\S+\.(?:test|spec)\.\S+)/i)
+    || output.match(/(\S+\.(?:test|spec)\.\S+)/i);
+  const testName = fileMatch ? fileMatch[1] : 'unknown test';
+
+  const errorMatch = output.match(/(?:Error|AssertionError|AssertError|expect).*$/m)
+    || output.match(/(?:\u2715|\u2717)\s*(.+)$/m);
+  const errorMessage = errorMatch ? errorMatch[0].trim() : 'test failed';
+
+  return { testName, errorMessage };
+}
+
+/**
+ * Build a search query from a test failure context.
+ * Strips path and test/spec suffix from the test file name.
+ * @param {string} testName - Test file name or path
+ * @param {string} errorMessage - Error message
+ * @returns {string}
+ */
+export function buildTestFailureQuery(testName, errorMessage) {
+  const shortName = testName.replace(/^.*[/\\]/, '').replace(/\.(test|spec)\.\w+$/, '');
+  return `${shortName} ${errorMessage}`.trim();
+}
+
+/**
+ * Build a search query from an error type and message.
+ * Uses only the first line of the error message.
+ * @param {string} errorType - Error class name (e.g. "TypeError")
+ * @param {string} errorMessage - Error message (may be multiline)
+ * @returns {string}
+ */
+export function buildErrorQuery(errorType, errorMessage) {
+  const firstLine = (errorMessage || '').split('\n')[0].trim();
+  return `${errorType || 'Error'} ${firstLine}`.trim();
+}

package/scripts/hooks/post-tool-use.js

@@ -34,6 +34,7 @@ import {
   updateEntityMetadata,
   addObservation,
 } from './hook-utils.js';
+import { isTestCommand, extractTestFailureContext, buildTestFailureQuery, buildErrorQuery } from './post-tool-use-recall-utils.js';
 import fs from 'fs';
 import path from 'path';
 
@@ -729,6 +730,81 @@ function detectPlanFile(toolData) {
   }
 }
 
+// ============================================================================
+// Proactive Recall on Test Failure / Error Detection
+// ============================================================================
+
+/**
+ * Trigger proactive recall on test failure or error detection.
+ * Writes results to proactive-recall.json for HookToolHandler.
+ * @param {Object} toolData - Normalized tool data
+ */
+function triggerProactiveRecall(toolData) {
+  try {
+    const recallFile = path.join(STATE_DIR, 'proactive-recall.json');
+    let query = null;
+    let trigger = null;
+
+    // Test failure detection
+    if (toolData.toolName === 'Bash' && toolData.arguments?.command) {
+      if (isTestCommand(toolData.arguments.command) && !toolData.success) {
+        const ctx = extractTestFailureContext(toolData._raw?.output || '');
+        if (ctx) {
+          query = buildTestFailureQuery(ctx.testName, ctx.errorMessage);
+          trigger = 'test-failure';
+        }
+      }
+    }
+
+    // Error detection (non-test failures)
+    if (!trigger && !toolData.success && toolData._raw?.output) {
+      const errorMatch = toolData._raw.output.match(/(\w*Error):\s*(.+)/);
+      if (errorMatch) {
+        query = buildErrorQuery(errorMatch[1], errorMatch[2]);
+        trigger = 'error-detection';
+      }
+    }
+
+    if (!query || !trigger) return;
+
+    // Build FTS5 query
+    const ftsTokens = query.split(/\s+/)
+      .filter(t => t.length > 2)
+      .slice(0, 8)
+      .map(t => `"${t.replace(/"/g, '""')}"*`)
+      .join(' OR ');
+
+    if (!ftsTokens) return;
+
+    const sql = `
+      SELECT e.name,
+        (SELECT json_group_array(content) FROM observations o WHERE o.entity_id = e.id) as observations_json
+      FROM entities e
+      JOIN entities_fts ON entities_fts.rowid = e.id
+      WHERE entities_fts MATCH ?
+      ORDER BY bm25(entities_fts, 10.0, 5.0)
+      LIMIT 3
+    `;
+
+    const result = sqliteQueryJSON(MEMESH_DB_PATH, sql, [ftsTokens]);
+    if (!result || result.length === 0) return;
+
+    const recallData = {
+      trigger,
+      query,
+      timestamp: Date.now(),
+      results: result.map(r => ({
+        name: r.name,
+        observations: JSON.parse(r.observations_json || '[]').filter(Boolean).slice(0, 2),
+      })),
+    };
+
+    writeJSONFile(recallFile, recallData);
+  } catch (error) {
+    logError('proactive-recall-trigger', error);
+  }
+}
+
 // ============================================================================
 // Main PostToolUse Logic
 // ============================================================================
@@ -778,6 +854,9 @@ async function postToolUse() {
     // Detect anomalies
     const anomalies = detectAnomalies(toolData, sessionContext);
 
+    // Trigger proactive recall on test failure or error
+    triggerProactiveRecall(toolData);
+
     // Fire async writes in parallel
     const pendingWrites = [contextWritePromise];
 

package/scripts/hooks/session-start-recall-utils.js

@@ -0,0 +1,40 @@
+/**
+ * Session-Start Recall Utilities
+ *
+ * Utility functions for proactive memory recall during session start.
+ * Builds search queries from project context and formats recall results.
+ */
+
+/**
+ * Build FTS5 search query from project name and recent commits.
+ * Strips conventional commit prefixes (fix:, feat(scope):, etc.)
+ * @param {string} projectName
+ * @param {string[]} recentCommits
+ * @returns {string}
+ */
+export function buildSessionRecallQuery(projectName, recentCommits = []) {
+  const parts = [projectName];
+  if (recentCommits.length > 0) {
+    const cleaned = recentCommits
+      .map(msg => msg.replace(/^(fix|feat|chore|refactor|perf|docs|test|style|ci)\(?[^)]*\)?:\s*/i, '').trim())
+      .filter(msg => msg.length > 0);
+    parts.push(...cleaned);
+  }
+  return parts.join(' ').trim();
+}
+
+/**
+ * Format recall results for hook output display.
+ * Shows max 2 observations per entity.
+ * @param {Array<{name: string, observations: string[], similarity: number}>} results
+ * @returns {string} Formatted output (empty string if no results)
+ */
+export function formatRecallOutput(results) {
+  if (!results || results.length === 0) return '';
+  const lines = results.map(r => {
+    const pct = Math.round(r.similarity * 100);
+    const obs = r.observations.slice(0, 2).join('; ');
+    return `  - ${r.name} (${pct}%): ${obs}`;
+  });
+  return lines.join('\n');
+}

package/scripts/hooks/session-start.js

@@ -27,8 +27,10 @@ import {
   queryActivePlans,
   renderTimelineCompact,
 } from './hook-utils.js';
+import { buildSessionRecallQuery, formatRecallOutput } from './session-start-recall-utils.js';
 import fs from 'fs';
 import path from 'path';
+import { execFileSync } from 'child_process';
 
 // ============================================================================
 // File Paths
@@ -444,6 +446,67 @@ function displayActivePlans() {
   }
 }
 
+/**
+ * Proactive memory recall — queries KG for memories related to current project.
+ * Uses project name + last 3 git commits as search query.
+ */
+function recallProactiveMemories() {
+  try {
+    const projectName = path.basename(process.cwd());
+
+    let recentCommits = [];
+    try {
+      const gitOutput = execFileSync('git', ['log', '--oneline', '-3', '--format=%s'], {
+        timeout: 3000,
+        encoding: 'utf-8',
+        cwd: process.cwd(),
+      });
+      recentCommits = gitOutput.trim().split('\n').filter(Boolean);
+    } catch {
+      // Not a git repo or no commits
+    }
+
+    const query = buildSessionRecallQuery(projectName, recentCommits);
+    if (!query) return;
+
+    // Build FTS5 tokens
+    const ftsTokens = query.split(/\s+/)
+      .filter(t => t.length > 2)
+      .slice(0, 10)
+      .map(t => `"${t.replace(/"/g, '""')}"*`)
+      .join(' OR ');
+
+    if (!ftsTokens) return;
+
+    const sql = `
+      SELECT e.name, e.type,
+        (SELECT json_group_array(content) FROM observations o WHERE o.entity_id = e.id) as observations_json
+      FROM entities e
+      JOIN entities_fts ON entities_fts.rowid = e.id
+      WHERE entities_fts MATCH ?
+      ORDER BY bm25(entities_fts, 10.0, 5.0)
+      LIMIT 5
+    `;
+
+    const result = sqliteQueryJSON(MEMESH_DB_PATH, sql, [ftsTokens]);
+    if (!result || result.length === 0) return;
+
+    const formatted = result.map(r => ({
+      name: r.name,
+      observations: JSON.parse(r.observations_json || '[]').filter(Boolean).slice(0, 3),
+      similarity: 0.5,
+    }));
+
+    const output = formatRecallOutput(formatted);
+    if (output) {
+      console.log('\n  Proactive Memory Recall:');
+      console.log(output);
+    }
+  } catch (error) {
+    logError('proactive-recall', error);
+  }
+}
+
 function sessionStart() {
   console.log('\n🚀 Smart-Agents Session Started\n');
 
@@ -458,6 +521,9 @@ function sessionStart() {
   const recalledMemory = recallRecentKeyPoints();
   displayRecalledMemory(recalledMemory);
 
+  // Proactive memory recall (project context + recent commits)
+  recallProactiveMemories();
+
   // Display active plans (beta)
   displayActivePlans();
 

package/scripts/hooks/templates/planning-template.md

@@ -0,0 +1,46 @@
+## Required Plan Sections
+
+Your plan MUST include all of the following sections. Incomplete plans will be rejected.
+
+### 1. System Design Description (SDD)
+- Component architecture and responsibilities
+- Data flow between components
+- Interface contracts (input/output types)
+- Dependencies and integration points
+
+### 2. Behavior-Driven Design (BDD)
+For EACH feature, write Gherkin scenarios:
+
+```gherkin
+Scenario: [descriptive name]
+  Given [precondition]
+  When [action]
+  Then [expected outcome]
+```
+
+Cover: happy path, error path, edge cases.
+
+### 3. Edge Case Handling
+
+| Edge Case | How Handled | Test Coverage |
+|-----------|------------|---------------|
+| [case] | [strategy] | [yes/no] |
+
+Include at minimum: empty input, null/undefined, boundary values, concurrent access, timeout, large data.
+
+### 4. Dry-Run Test Plan
+Before dispatching heavy tasks, verify:
+- [ ] Core function compiles (`tsc --noEmit` or `node --check`)
+- [ ] Unit test for critical path passes
+- [ ] Integration point verified with real call
+- [ ] No regressions in existing tests
+
+### 5. Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| [risk] | High/Med/Low | High/Med/Low | [strategy] |
+
+---
+
+**IMPORTANT**: After completing this plan, present it to the user and wait for explicit approval before proceeding to implementation. Do NOT auto-execute.