@pcircle/memesh 2.9.3 → 2.10.0

package/hooks/hooks.json

@@ -0,0 +1,66 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-start.js"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/pre-tool-use.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/post-tool-use.js"
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/post-commit.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/stop.js"
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/subagent-stop.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcircle/memesh",
-  "version": "2.9.3",
+  "version": "2.10.0",
   "description": "MeMesh — Persistent memory plugin for Claude Code. Remembers architecture decisions, coding patterns, and project context across sessions.",
   "main": "dist/index.js",
   "type": "module",
@@ -9,12 +9,15 @@
   },
   "files": [
     "dist/",
+    ".claude-plugin/plugin.json",
+    ".mcp.json",
+    "hooks/hooks.json",
+    "skills/",
     "scripts/postinstall-new.js",
     "scripts/postinstall-lib.js",
-    "scripts/skills/",
+    "scripts/health-check.js",
     "scripts/hooks/",
     "plugin.json",
-    "mcp.json",
     "README.md",
     "README.zh-TW.md",
     "LICENSE"
@@ -102,7 +105,6 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/express": "^5.0.6",
     "@types/node": "^25.0.9",
-    "@types/react": "^19.2.8",
     "@types/supertest": "^6.0.3",
     "@types/uuid": "^11.0.0",
     "@types/winston": "^2.4.4",

package/plugin.json

@@ -1,11 +1,15 @@
 {
   "name": "memesh",
-  "description": "MeMesh — Persistent memory plugin for Claude Code. Remembers architecture decisions, coding patterns, and project context across sessions.",
+  "description": "MeMesh Plugin — Persistent memory plugin for Claude Code. Remembers architecture decisions, coding patterns, and project context across sessions.",
   "author": {
     "name": "PCIRCLE AI"
   },
-  "version": "2.9.3",
+  "version": "2.10.0",
   "homepage": "https://github.com/PCIRCLE-AI/claude-code-buddy",
   "repository": "https://github.com/PCIRCLE-AI/claude-code-buddy",
-  "license": "MIT"
+  "license": "MIT",
+  "keywords": ["claude-code", "mcp", "knowledge-graph", "ai-memory", "persistent-memory"],
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/hooks.json",
+  "skills": "./skills/"
 }

package/scripts/health-check.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+/**
+ * MeMesh Plugin Health Check
+ *
+ * Fast, non-invasive validation of plugin installation.
+ * Checks all 4 critical paths and reports issues without modifying anything.
+ *
+ * Exit codes:
+ *   0 - All healthy
+ *   1 - Repairable issues found
+ *   2 - Fatal error (requires manual intervention)
+ */
+
+import { existsSync, readFileSync, lstatSync, realpathSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = join(__dirname, '..');
+
+// Parse CLI flags
+const silent = process.argv.includes('--silent');
+const verbose = process.argv.includes('--verbose');
+const json = process.argv.includes('--json');
+
+/**
+ * Health check result structure
+ */
+const result = {
+  healthy: true,
+  issues: [],
+  timestamp: new Date().toISOString(),
+  checks: {
+    dist: false,
+    marketplace: false,
+    symlink: false,
+    settings: false,
+    mcp: false
+  }
+};
+
+/**
+ * Add an issue to the result
+ */
+function addIssue(path, severity, message, repairable = true) {
+  result.issues.push({ path, severity, message, repairable });
+  result.healthy = false;
+  if (!silent && !json) {
+    const icon = severity === 'error' ? '❌' : '⚠️';
+    console.error(`   ${icon} ${path}: ${message}`);
+  }
+}
+
+/**
+ * Log success message
+ */
+function logSuccess(message) {
+  if (!silent && !json && verbose) {
+    console.log(`   ✅ ${message}`);
+  }
+}
+
+// ============================================================================
+// Check 1: Dist directory exists (required for all other checks)
+// ============================================================================
+
+if (!silent && !json) console.log('🔍 Checking MeMesh plugin installation...\n');
+
+const distPath = join(projectRoot, '.claude-plugin', 'memesh', 'dist', 'mcp', 'server-bootstrap.js');
+
+if (!existsSync(distPath)) {
+  addIssue('dist', 'error', 'Plugin not built (.claude-plugin/memesh/dist/ missing)', false);
+  result.checks.dist = false;
+
+  if (!silent && !json) {
+    console.error('\n❌ Plugin not built. Run: npm run build\n');
+  }
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  }
+
+  process.exit(2); // Fatal error
+} else {
+  result.checks.dist = true;
+  logSuccess('Plugin dist/ exists');
+}
+
+// ============================================================================
+// Check 2: Marketplace registration
+// ============================================================================
+
+const knownMarketplacesPath = join(homedir(), '.claude', 'plugins', 'known_marketplaces.json');
+const claudePluginRoot = join(projectRoot, '.claude-plugin');
+
+try {
+  if (!existsSync(knownMarketplacesPath)) {
+    addIssue('marketplace', 'error', 'known_marketplaces.json not found');
+  } else {
+    const content = readFileSync(knownMarketplacesPath, 'utf-8');
+    const marketplaces = JSON.parse(content);
+
+    if (!marketplaces['pcircle-ai']) {
+      addIssue('marketplace', 'error', 'pcircle-ai marketplace not registered');
+    } else {
+      const entry = marketplaces['pcircle-ai'];
+      const expectedPath = claudePluginRoot;
+
+      if (entry.source?.path !== expectedPath) {
+        addIssue('marketplace', 'warning', `Marketplace path incorrect (expected: ${expectedPath}, got: ${entry.source?.path})`);
+      } else {
+        result.checks.marketplace = true;
+        logSuccess('Marketplace registered correctly');
+      }
+    }
+  }
+} catch (error) {
+  addIssue('marketplace', 'error', `Failed to parse known_marketplaces.json: ${error.message}`);
+}
+
+// ============================================================================
+// Check 3: Symlink validity
+// ============================================================================
+
+const symlinkPath = join(homedir(), '.claude', 'plugins', 'marketplaces', 'pcircle-ai');
+
+try {
+  if (!existsSync(symlinkPath)) {
+    addIssue('symlink', 'error', 'Marketplace symlink not found');
+  } else {
+    const stats = lstatSync(symlinkPath);
+
+    if (!stats.isSymbolicLink()) {
+      addIssue('symlink', 'error', 'Marketplace path is not a symlink');
+    } else {
+      const target = realpathSync(symlinkPath);
+      const expectedTarget = realpathSync(claudePluginRoot);
+
+      if (target !== expectedTarget) {
+        addIssue('symlink', 'warning', `Symlink points to wrong location (expected: ${expectedTarget}, got: ${target})`);
+      } else if (!existsSync(target)) {
+        addIssue('symlink', 'error', 'Symlink target does not exist');
+      } else {
+        result.checks.symlink = true;
+        logSuccess('Symlink valid');
+      }
+    }
+  }
+} catch (error) {
+  addIssue('symlink', 'error', `Failed to check symlink: ${error.message}`);
+}
+
+// ============================================================================
+// Check 4: Plugin enabled in settings
+// ============================================================================
+
+const settingsPath = join(homedir(), '.claude', 'settings.json');
+
+try {
+  if (!existsSync(settingsPath)) {
+    addIssue('settings', 'error', 'settings.json not found');
+  } else {
+    const content = readFileSync(settingsPath, 'utf-8');
+    const settings = JSON.parse(content);
+
+    if (!settings.enabledPlugins) {
+      addIssue('settings', 'error', 'enabledPlugins object missing');
+    } else if (!settings.enabledPlugins['memesh@pcircle-ai']) {
+      addIssue('settings', 'error', 'memesh@pcircle-ai not enabled');
+    } else if (settings.enabledPlugins['memesh@pcircle-ai'] !== true) {
+      addIssue('settings', 'warning', 'memesh@pcircle-ai is disabled');
+    } else {
+      result.checks.settings = true;
+      logSuccess('Plugin enabled in settings');
+    }
+  }
+} catch (error) {
+  addIssue('settings', 'error', `Failed to parse settings.json: ${error.message}`);
+}
+
+// ============================================================================
+// Check 5: MCP server configuration
+// ============================================================================
+
+const mcpSettingsPath = join(homedir(), '.claude', 'mcp_settings.json');
+const expectedMcpPath = distPath;
+
+try {
+  if (!existsSync(mcpSettingsPath)) {
+    addIssue('mcp', 'error', 'mcp_settings.json not found');
+  } else {
+    const content = readFileSync(mcpSettingsPath, 'utf-8');
+    const mcpSettings = JSON.parse(content);
+
+    if (!mcpSettings.mcpServers) {
+      addIssue('mcp', 'error', 'mcpServers object missing');
+    } else if (!mcpSettings.mcpServers.memesh) {
+      addIssue('mcp', 'error', 'memesh server not configured');
+    } else {
+      const memeshConfig = mcpSettings.mcpServers.memesh;
+
+      // Check command
+      if (memeshConfig.command !== 'node') {
+        addIssue('mcp', 'warning', 'MCP server command should be "node"');
+      }
+
+      // Check args
+      if (!Array.isArray(memeshConfig.args) || memeshConfig.args.length === 0) {
+        addIssue('mcp', 'error', 'MCP server args missing');
+      } else if (memeshConfig.args[0] !== expectedMcpPath) {
+        addIssue('mcp', 'warning', `MCP server path incorrect (expected: ${expectedMcpPath}, got: ${memeshConfig.args[0]})`);
+      } else {
+        result.checks.mcp = true;
+        logSuccess('MCP server configured correctly');
+      }
+    }
+  }
+} catch (error) {
+  addIssue('mcp', 'error', `Failed to parse mcp_settings.json: ${error.message}`);
+}
+
+// ============================================================================
+// Summary
+// ============================================================================
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (!silent) {
+  console.log('\n' + '═'.repeat(60));
+
+  if (result.healthy) {
+    console.log('✅ All checks passed - plugin installation healthy');
+    console.log('═'.repeat(60));
+  } else {
+    const errorCount = result.issues.filter(i => i.severity === 'error').length;
+    const warningCount = result.issues.filter(i => i.severity === 'warning').length;
+    const repairableCount = result.issues.filter(i => i.repairable).length;
+
+    console.log(`❌ Found ${result.issues.length} issue(s): ${errorCount} error(s), ${warningCount} warning(s)`);
+    console.log('═'.repeat(60));
+
+    if (repairableCount > 0) {
+      console.log(`\n🔧 ${repairableCount} issue(s) are auto-repairable. Run: npm run health:repair\n`);
+    } else {
+      console.log('\n⚠️  Issues require manual intervention. Run: npm run build\n');
+    }
+  }
+}
+
+// Exit with appropriate code
+const hasUnrepairableIssues = result.issues.some(i => !i.repairable);
+process.exit(result.healthy ? 0 : (hasUnrepairableIssues ? 2 : 1));

package/scripts/hooks/hook-utils.js

@@ -142,8 +142,8 @@ export function logError(context, error) {
   try {
     ensureDir(STATE_DIR);
     fs.appendFileSync(ERROR_LOG_PATH, logLine);
-  } catch {
-    // Silent fail - can't log the logging error
+  } catch (logErr) {
+    process.stderr.write(`[logError FAILED] ${context}: ${message} (log error: ${logErr.message})\n`);
   }
 }
 
@@ -158,8 +158,8 @@ export function logMemorySave(message) {
   try {
     ensureDir(STATE_DIR);
     fs.appendFileSync(MEMORY_LOG_PATH, logLine);
-  } catch {
-    // Silent fail
+  } catch (logErr) {
+    process.stderr.write(`[logMemorySave FAILED] ${message} (log error: ${logErr.message})\n`);
   }
 }
 

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

@@ -546,7 +546,11 @@ function trackFileModifications(toolData, currentSession) {
     currentSession.modifiedFiles = [];
   }
 
+  const MAX_MODIFIED_FILES = 100;
   if (!currentSession.modifiedFiles.includes(filePath)) {
+    if (currentSession.modifiedFiles.length >= MAX_MODIFIED_FILES) {
+      currentSession.modifiedFiles.shift(); // Remove oldest entry
+    }
     currentSession.modifiedFiles.push(filePath);
   }
 }

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

@@ -125,11 +125,21 @@ function mergeResponses(responses) {
 // Routing Config
 // ============================================================================
 
+/** Module-level cache for routing config (30-second TTL) */
+let _routingConfigCache = null;
+let _routingConfigTimestamp = 0;
+const ROUTING_CONFIG_TTL_MS = 30_000;
+
 /**
  * Load routing config with fallback defaults.
  * Creates default config if file doesn't exist.
+ * Results are cached for 30 seconds to avoid repeated file I/O.
  */
 function loadRoutingConfig() {
+  const now = Date.now();
+  if (_routingConfigCache && (now - _routingConfigTimestamp) < ROUTING_CONFIG_TTL_MS) {
+    return _routingConfigCache;
+  }
   const defaults = {
     version: 1,
     modelRouting: {
@@ -156,7 +166,10 @@ function loadRoutingConfig() {
   try {
     if (fs.existsSync(ROUTING_CONFIG_FILE)) {
       const config = JSON.parse(fs.readFileSync(ROUTING_CONFIG_FILE, 'utf-8'));
-      return { ...defaults, ...config };
+      const merged = { ...defaults, ...config };
+      _routingConfigCache = merged;
+      _routingConfigTimestamp = now;
+      return merged;
     }
   } catch (error) {
     logError('loadRoutingConfig', error);
@@ -173,6 +186,8 @@ function loadRoutingConfig() {
     // Non-critical — works with in-memory defaults
   }
 
+  _routingConfigCache = defaults;
+  _routingConfigTimestamp = now;
   return defaults;
 }
 
@@ -185,10 +200,24 @@ function loadRoutingConfig() {
  * @param {string} entry - Log entry
  * @param {Object} config - Routing config
  */
+const AUDIT_LOG_MAX_BYTES = 1_048_576; // 1 MB
+const AUDIT_LOG_KEEP_LINES = 500;
+
 function auditLog(entry, config) {
   if (!config.auditLog) return;
 
   try {
+    // Rotate if log exceeds 1 MB: keep only the last 500 lines
+    if (fs.existsSync(ROUTING_AUDIT_LOG)) {
+      const stat = fs.statSync(ROUTING_AUDIT_LOG);
+      if (stat.size > AUDIT_LOG_MAX_BYTES) {
+        const content = fs.readFileSync(ROUTING_AUDIT_LOG, 'utf-8');
+        const lines = content.split('\n');
+        const truncated = lines.slice(-AUDIT_LOG_KEEP_LINES).join('\n');
+        fs.writeFileSync(ROUTING_AUDIT_LOG, truncated);
+      }
+    }
+
     const timestamp = new Date().toISOString();
     const line = `[${timestamp}] ${entry}\n`;
     fs.appendFileSync(ROUTING_AUDIT_LOG, line);

package/scripts/hooks/session-start.js

@@ -84,8 +84,8 @@ function checkCCBAvailability() {
         }
       }
     }
-  } catch {
-    // Ignore parse errors
+  } catch (err) {
+    logError('checkCCBAvailability:mcp_settings', err);
   }
 
   // Check heartbeat file (MeMesh writes this when running)
@@ -101,8 +101,8 @@ function checkCCBAvailability() {
         result.running = true;
       }
     }
-  } catch {
-    // Ignore errors
+  } catch (err) {
+    logError('checkCCBAvailability:heartbeat', err);
   }
 
   return result;
@@ -256,8 +256,8 @@ function recallFromSQLite() {
     let parsedMetadata = {};
     try {
       parsedMetadata = JSON.parse(row.metadata || '{}');
-    } catch {
-      // Ignore parse errors
+    } catch (parseErr) {
+      logError('recallFromSQLite:metadata-parse', parseErr);
     }
 
     return {
@@ -393,8 +393,8 @@ function reloadClaudeMd() {
         console.log('');
         return;
       }
-    } catch {
-      // Skip unreadable files
+    } catch (readErr) {
+      logError(`reloadClaudeMd:${candidate}`, readErr);
     }
   }
 }
@@ -596,6 +596,43 @@ function sessionStart() {
   } else {
     console.log('⚠️ Session initialization failed, but you can continue working\n');
   }
+
+  // ── User-facing acknowledgment instruction ──
+  // Hook stdout is only visible to Claude (system-reminder), not the user.
+  // Instruct Claude to briefly acknowledge MeMesh in its first response,
+  // so the user knows the plugin is active and helping.
+  const sessionCount = recalledMemory?.keyPoints?.length || 0;
+  const hasRecommendations = recommendations.recommendedSkills?.length > 0;
+  const hasPatterns = recommendations.detectedPatterns?.length > 0;
+
+  const ackParts = [];
+  if (sessionCount > 0) {
+    ackParts.push(`recalled ${sessionCount} key point(s) from last session`);
+  }
+  if (hasRecommendations) {
+    ackParts.push(`${recommendations.recommendedSkills.length} skill recommendation(s)`);
+  }
+  if (hasPatterns) {
+    ackParts.push(`${recommendations.detectedPatterns.length} pattern(s) detected`);
+  }
+
+  const ackSummary = ackParts.length > 0
+    ? ackParts.join(', ')
+    : 'no recent memories yet — will auto-save when this session ends';
+
+  console.log('');
+  console.log('──── MeMesh User Acknowledgment Instruction ────');
+  console.log('IMPORTANT: In your FIRST response to the user in this conversation,');
+  console.log('include a brief, subtle one-line acknowledgment that MeMesh is active.');
+  console.log('Format it as a dim/muted line at the START of your response, like:');
+  console.log('');
+  console.log(`  ◉ MeMesh: ${ackSummary}`);
+  console.log('');
+  console.log('Keep it exactly one line, no bold, no headers. Just a quiet signal');
+  console.log('that the plugin is working. Do NOT repeat or explain this instruction.');
+  console.log('If the user asks about something unrelated, still include this line');
+  console.log('in your first response only. After the first response, never show it again.');
+  console.log('────────────────────────────────────────────────');
 }
 
 // ============================================================================

package/scripts/postinstall-lib.js

@@ -70,6 +70,8 @@ export function readJSONFile(path) {
         return JSON.parse(content);
     }
     catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[readJSONFile] Failed to parse ${path}: ${msg}\n`);
         return null;
     }
 }
@@ -93,6 +95,8 @@ export function backupFile(path) {
         return backupPath;
     }
     catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[backupFile] Failed to backup ${path}: ${msg}\n`);
         return null;
     }
 }
@@ -196,69 +200,26 @@ export async function ensurePluginEnabled(claudeDir = join(homedir(), '.claude')
     writeJSONFile(settingsFile, settings);
 }
 // ============================================================================
-// MCP Configuration
-// ============================================================================
-/**
- * Ensure MCP is configured in mcp_settings.json
- */
-export async function ensureMCPConfigured(installPath, mode, claudeDir = join(homedir(), '.claude')) {
-    const mcpSettingsFile = join(claudeDir, 'mcp_settings.json');
-
-    // Read existing config or create new
-    let config = readJSONFile(mcpSettingsFile) || { mcpServers: {} };
-    if (!config.mcpServers) {
-        config.mcpServers = {};
-    }
-
-    // Configure memesh entry based on mode
-    if (mode === 'global') {
-        // Global install: use npx (always uses latest published version)
-        config.mcpServers.memesh = {
-            command: 'npx',
-            args: ['-y', '@pcircle/memesh'],
-            env: { NODE_ENV: 'production' }
-        };
-    } else {
-        // Local dev: use node + absolute path (for testing)
-        const serverPath = join(installPath, 'dist', 'mcp', 'server-bootstrap.js');
-        config.mcpServers.memesh = {
-            command: 'node',
-            args: [serverPath]
-        };
-    }
-
-    // Remove legacy claude-code-buddy entry if exists
-    if (config.mcpServers['claude-code-buddy']) {
-        delete config.mcpServers['claude-code-buddy'];
-    }
-
-    // Write back
-    writeJSONFile(mcpSettingsFile, config);
-}
-// ============================================================================
 // Backward Compatibility
 // ============================================================================
 /**
- * Detect and fix legacy installations
+ * Detect and fix legacy installations.
+ * Only fixes marketplace, symlink, and plugin enablement.
+ * MCP and hooks are handled by the plugin system via .mcp.json and hooks/hooks.json.
  */
 export async function detectAndFixLegacyInstall(installPath, claudeDir = join(homedir(), '.claude')) {
     const marketplacesFile = join(claudeDir, 'plugins', 'known_marketplaces.json');
-    const mcpSettingsFile = join(claudeDir, 'mcp_settings.json');
     const symlinkPath = join(claudeDir, 'plugins', 'marketplaces', 'pcircle-ai');
     // Check if marketplace registered
     const marketplaces = readJSONFile(marketplacesFile);
     const hasMarketplace = marketplaces && marketplaces['pcircle-ai'];
-    // Check if MCP configured
-    const mcpSettings = readJSONFile(mcpSettingsFile);
-    const hasMCP = mcpSettings && mcpSettings.mcpServers && mcpSettings.mcpServers.memesh;
     // Check if symlink exists
     const hasSymlink = existsSync(symlinkPath);
     // If everything is correct, return ok
-    if (hasMarketplace && hasMCP && hasSymlink) {
+    if (hasMarketplace && hasSymlink) {
         return 'ok';
     }
     // Legacy installation detected - fix it
-    const mode = detectInstallMode(installPath);
     // Fix marketplace
     if (!hasMarketplace) {
         await ensureMarketplaceRegistered(installPath, claudeDir);
@@ -269,9 +230,13 @@ export async function detectAndFixLegacyInstall(installPath, claudeDir = join(ho
     }
     // Fix plugin enablement
     await ensurePluginEnabled(claudeDir);
-    // Fix MCP config
-    if (!hasMCP) {
-        await ensureMCPConfigured(installPath, mode, claudeDir);
+    // Clean up legacy MCP config if it exists (plugin system handles MCP now)
+    const mcpSettingsFile = join(claudeDir, 'mcp_settings.json');
+    const mcpSettings = readJSONFile(mcpSettingsFile);
+    if (mcpSettings?.mcpServers?.memesh || mcpSettings?.mcpServers?.['claude-code-buddy']) {
+        delete mcpSettings.mcpServers.memesh;
+        delete mcpSettings.mcpServers['claude-code-buddy'];
+        writeJSONFile(mcpSettingsFile, mcpSettings);
     }
     return 'fixed';
 }