@pcircle/memesh 4.1.2 → 4.1.4

package/scripts/hooks/session-summary.js

@@ -7,12 +7,58 @@
 import { createRequire } from 'module';
 import { join, basename } from 'path';
 import { existsSync, readFileSync } from 'fs';
-import { getMemeshDir, isAutoCaptureEnabled, openHookDb, resolvePluginRoot } from './_shared.js';
+import { pathToFileURL } from 'url';
+import {
+  decideAutoUpdateHook,
+  getMemeshDir,
+  isAutoCaptureEnabled,
+  openHookDb,
+  readUpdateCheckCache,
+  resolveAutoUpdatePolicy,
+  resolvePluginRoot,
+  spawnAutoUpdate,
+} from './_shared.js';
 
 const require = createRequire(import.meta.url);
 
+// Pre-load dist/core/install-channel.js for auto-update channel detection.
+// Same pattern as session-start.js: async ESM import at process init,
+// falls back to null if dist is missing (source checkout pre-build).
+let _installChannelMod = null;
+try {
+  const _pluginRootForInit = resolvePluginRoot(import.meta.url);
+  const _modPath = join(_pluginRootForInit, 'dist/core/install-channel.js');
+  if (existsSync(_modPath)) {
+    _installChannelMod = await import(pathToFileURL(_modPath).href);
+  }
+} catch { /* best-effort */ }
+
+/**
+ * Run auto-update at Stop hook: reads cache, evaluates policy, and spawns
+ * npm install -g if warranted. Runs after all session work completes,
+ * avoiding the TOCTOU race where install would overwrite dist/ mid-session.
+ */
+async function runAutoUpdateAtStop() {
+  try {
+    const pluginRoot = resolvePluginRoot(import.meta.url);
+    const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
+    const installedVersion = typeof pkg.version === 'string' ? pkg.version : null;
+    if (!installedVersion) return;
+
+    const cache = readUpdateCheckCache(installedVersion);
+    const policy = resolveAutoUpdatePolicy(process.env);
+    const decision = decideAutoUpdateHook(installedVersion, cache, policy);
+    if (decision.run) {
+      spawnAutoUpdate(decision.latest, decision.deprecationOverride, _installChannelMod);
+    }
+  } catch {
+    // Best-effort — never crash the hook.
+  }
+}
+
 // Parse a JSONL transcript file.
-// Mirrors logic in src/core/extractor.ts parseTranscript().
+// Handles the current Claude Code transcript format where tool_use/tool_result
+// are nested inside assistant/user message entries, not top-level entries.
 // Defensive: never throws — malformed lines are silently skipped.
 function parseTranscript(transcriptPath) {
   const filesEdited = new Set();
@@ -26,30 +72,67 @@ function parseTranscript(transcriptPath) {
       try {
         const entry = JSON.parse(line);
 
-        // Count tool calls
-        if (entry.type === 'tool_use' || entry.tool_name) toolCallCount++;
+        // Current format: assistant entries contain tool_use blocks in message.content
+        if (entry.type === 'assistant' && Array.isArray(entry.message?.content)) {
+          for (const block of entry.message.content) {
+            if (block.type !== 'tool_use') continue;
+            toolCallCount++;
 
-        // Track file edits (Write, Edit tools)
-        if (entry.tool_name === 'Write' || entry.tool_name === 'Edit') {
-          const inp = entry.tool_input ?? {};
-          const fp = (inp.file_path ?? inp.path);
-          if (fp && typeof fp === 'string') filesEdited.add(basename(fp));
+            if (block.name === 'Write' || block.name === 'Edit') {
+              const fp = block.input?.file_path ?? block.input?.path;
+              if (fp && typeof fp === 'string') filesEdited.add(basename(fp));
+            }
+            if (block.name === 'Bash') {
+              const cmd = block.input?.command ?? '';
+              if (typeof cmd === 'string' && cmd.length > 10 && !cmd.startsWith('ls') && !cmd.startsWith('cd')) {
+                bashCommands.push(cmd.slice(0, 100));
+              }
+            }
+          }
         }
 
-        // Track meaningful bash commands
-        if (entry.tool_name === 'Bash') {
-          const cmd = (entry.tool_input?.command) ?? '';
-          if (typeof cmd === 'string' && cmd.length > 10 && !cmd.startsWith('ls') && !cmd.startsWith('cd')) {
-            bashCommands.push(cmd.slice(0, 100));
+        // Current format: user entries contain tool_result blocks in message.content.
+        //
+        // Use the explicit `is_error` flag the transcript records on each
+        // tool_result instead of substring-matching the result text. The
+        // earlier substring approach treated any Read/Bash output that
+        // happened to contain the word "Error" (READMEs documenting errors,
+        // CHANGELOG entries, source files mentioning "Error", grep over docs)
+        // as a real error, drowning analyzeFailure() in noise — a 47MB
+        // transcript reported 315 "errors" against ~28 real ones. The flag
+        // is the canonical signal Claude Code itself uses to mark a tool as
+        // having failed.
+        if (entry.type === 'user' && Array.isArray(entry.message?.content)) {
+          for (const block of entry.message.content) {
+            if (block.type !== 'tool_result') continue;
+            if (block.is_error !== true) continue;
+            const text = typeof block.content === 'string'
+              ? block.content
+              : JSON.stringify(block.content);
+            errorsEncountered.push(text.slice(0, 200));
           }
         }
 
-        // Track errors from tool results
+        // Legacy format (older Claude Code versions): top-level tool_use/tool_result
+        if (entry.type === 'tool_use' || entry.tool_name) {
+          toolCallCount++;
+          if (entry.tool_name === 'Write' || entry.tool_name === 'Edit') {
+            const fp = (entry.tool_input?.file_path ?? entry.tool_input?.path);
+            if (fp && typeof fp === 'string') filesEdited.add(basename(fp));
+          }
+          if (entry.tool_name === 'Bash') {
+            const cmd = entry.tool_input?.command ?? '';
+            if (typeof cmd === 'string' && cmd.length > 10 && !cmd.startsWith('ls') && !cmd.startsWith('cd')) {
+              bashCommands.push(cmd.slice(0, 100));
+            }
+          }
+        }
         if (entry.type === 'tool_result' && entry.content != null) {
-          const text = typeof entry.content === 'string'
-            ? entry.content
-            : JSON.stringify(entry.content);
-          if (text.includes('Error') || text.includes('FAIL') || text.includes('error:')) {
+          // Same fix as the current-format branch: trust the flag, not text.
+          if (entry.is_error !== true) {
+            // empty
+          } else {
+            const text = typeof entry.content === 'string' ? entry.content : JSON.stringify(entry.content);
             errorsEncountered.push(text.slice(0, 200));
           }
         }
@@ -99,6 +182,14 @@ process.stdin.on('end', async () => {
     // Skip sessions with too little activity
     if (toolCallCount < 3) return exit0();
 
+    // Hoisted to outer-try scope so the LLM failure-analysis block
+    // below (which runs AFTER db.close()) can reference it. Earlier
+    // version defined projectName inside the inner try-finally and the
+    // LLM path threw `projectName is not defined` silently — caught by
+    // the LLM try/catch but logged to stderr. Result: lesson_learned
+    // creation never actually happened in production.
+    const projectName = basename(cwd);
+
     // Open DB via shared helper — applies SCHEMA_SQL + status migration.
     // sqlite-vec is loaded separately because only this hook needs it
     // (for embedding-aware recall-effectiveness tracking).
@@ -107,14 +198,19 @@ process.stdin.on('end', async () => {
     try {
       sqliteVec.load(db);
 
-      // Duplicate detection: if we already captured this session, bail
-      const shortId = sessionId.slice(0, 8);
-      const alreadyCaptured = db.prepare("SELECT id FROM entities WHERE name = ?").get(`session-${shortId}-files`);
+      // Duplicate detection: if we already captured this session, bail.
+      //
+      // Use the FULL session_id rather than the first 8 chars: real
+      // Claude Code UUIDs collide on 8 chars only with cosmically small
+      // probability, but artificial test IDs (verify-fix-001 vs -002)
+      // share the prefix and silently skipped the second session
+      // entirely. The contract is one stored capture per distinct
+      // session_id, so the dedup key has to be the full id.
+      const alreadyCaptured = db.prepare("SELECT id FROM entities WHERE name = ?").get(`session-${sessionId}-files`);
       if (alreadyCaptured) return exit0();
 
       // Build and store session memories
-      const projectName = basename(cwd);
-      const baseTags = ['source:auto-capture', `session:${shortId}`, `project:${projectName}`];
+      const baseTags = ['source:auto-capture', `session:${sessionId}`, `project:${projectName}`];
 
       const insertEntity = db.prepare('INSERT OR IGNORE INTO entities (name, type) VALUES (?, ?)');
       const selectEntity = db.prepare('SELECT id FROM entities WHERE name = ?');
@@ -132,7 +228,7 @@ process.stdin.on('end', async () => {
       // Rule 1: File editing session summary
       if (filesEdited.length > 0) {
         storeMemory(
-          `session-${shortId}-files`,
+          `session-${sessionId}-files`,
           'session-insight',
           [
             `Session edited ${filesEdited.length} file(s): ${filesEdited.join(', ')}`,
@@ -145,7 +241,7 @@ process.stdin.on('end', async () => {
       // Rule 2: Error -> Fix pattern detection
       if (errorsEncountered.length > 0 && filesEdited.length > 0) {
         storeMemory(
-          `session-${shortId}-fixes`,
+          `session-${sessionId}-fixes`,
           'session-insight',
           [
             `Fixed ${errorsEncountered.length} error(s) by editing ${filesEdited.join(', ')}`,
@@ -158,7 +254,7 @@ process.stdin.on('end', async () => {
       // Rule 3: Heavy session summary (20+ tool calls = significant work)
       if (toolCallCount >= 20) {
         storeMemory(
-          `session-${shortId}-summary`,
+          `session-${sessionId}-summary`,
           'session-insight',
           [
             `Significant session: ${toolCallCount} tool calls, ${filesEdited.length} files edited`,
@@ -277,8 +373,10 @@ process.stdin.on('end', async () => {
             closeDatabase();
           }
         }
-      } catch {
-        // LLM analysis failed — rule-based extraction already captured the session
+      } catch (llmErr) {
+        // LLM analysis failed — rule-based extraction already captured the session.
+        // Log to stderr so config issues (e.g. invalid API key) are visible.
+        try { process.stderr.write(`[memesh] LLM failure analysis skipped: ${llmErr?.message || llmErr}\n`); } catch {}
       }
     }
   } catch (err) {
@@ -286,6 +384,10 @@ process.stdin.on('end', async () => {
     try { process.stderr.write(`[memesh session-summary] ${err?.message || err}\n`); } catch {}
   }
 
+  // Spawn auto-update if policy + cache permit. Runs after all session work
+  // so npm install -g doesn't overwrite dist/ while peer hooks are reading it.
+  await runAutoUpdateAtStop();
+
   // Silent output — don't clutter Claude's response
   console.log(JSON.stringify({ suppressOutput: true }));
   exit0();

package/scripts/hooks/user-prompt-intent.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+// User Prompt Intent — UserPromptSubmit hook
+//
+// Detects when the user explicitly asks Claude to remember / save / memorize
+// content from the current session, and injects a context hint reminding Claude
+// to use `mcp__memesh__remember` for cross-project recall.
+//
+// Why a hint instead of autonomous capture? The user's intent is clear, but
+// "what to remember" usually depends on the surrounding conversation —
+// extracting that requires an LLM round and policy decisions (name, type,
+// observations, namespace). A polite reminder keeps the calling agent in the
+// loop with full conversation context, while still preventing the
+// "I forgot to use memesh" failure mode that motivated this hook.
+//
+// Defensive: never blocks user prompts, even on hook failure. Errors are
+// surfaced to stderr (visible in Claude Code debug logs) rather than
+// swallowed — stderr does not affect prompt submission.
+// Gated by `autoCapture` flag (same as other memesh write hooks).
+
+import { pathToFileURL } from 'url';
+import { isAutoCaptureEnabled } from './_shared.js';
+
+// Patterns compiled at module load — invalid regex MUST fail loudly. Do
+// NOT move into a try block "for safety": a regex compile error is a
+// programmer error, not a runtime condition, and silencing it would hide
+// real bugs.
+//
+// Design principle: when in doubt between matching and not matching, do
+// NOT match — a missed hint is recoverable (user repeats themselves), but
+// a false hint pollutes context and pressures the LLM into a wrong action.
+//
+// Disambiguation policy:
+//   - All imperatives anchored to sentence start (^ or after .!?\n) to skip
+//     interrogatives ("do you remember X?", "What does save to memesh do?").
+//   - For save-class verbs, "memesh" suffix required to avoid false positives
+//     on generic "save this" (could mean clipboard, file, bookmark, etc.).
+//   - Supported languages: English, Spanish, French, Portuguese, Traditional Chinese.
+//     Additional languages welcome via PR (provide native-speaker validation).
+export const INTENT_PATTERNS = [
+  // English: "Remember/memorize this|that"
+  /(?:^|[.!?\n]\s*)(?:please\s+)?(?:remember|memorize)\s+(?:this|that)\b/im,
+  // English: "save/add/store to memesh"
+  /(?:^|[.!?\n]\s*)(?:please\s+)?(?:save|add|put|store|write)\s+(?:(?:this|that|it)\s+)?(?:to|in|into)\s+memesh\b/im,
+
+  // Spanish: "Recordar/memorizar esto|eso"
+  /(?:^|[.!?\n]\s*)(?:por favor\s+)?(?:recordar|memorizar)\s+(?:esto|eso)\b/im,
+  // Spanish: "guardar en memesh"
+  /(?:^|[.!?\n]\s*)(?:por favor\s+)?(?:guardar|añadir|almacenar)\s+(?:(?:esto|eso)\s+)?(?:en|a)\s+memesh\b/im,
+
+  // French: "Rappeler/mémoriser ceci|cela"
+  /(?:^|[.!?\n]\s*)(?:s'il vous plaît\s+)?(?:rappeler|mémoriser)\s+(?:ceci|cela|ça)\b/im,
+  // French: "sauvegarder dans memesh"
+  /(?:^|[.!?\n]\s*)(?:s'il vous plaît\s+)?(?:sauvegarder|enregistrer|ajouter)\s+(?:(?:ceci|cela|ça)\s+)?(?:dans|à)\s+memesh\b/im,
+
+  // Portuguese: "Lembrar/memorizar isto|isso"
+  /(?:^|[.!?\n]\s*)(?:por favor\s+)?(?:lembrar|memorizar)\s+(?:isto|isso)\b/im,
+  // Portuguese: "salvar em memesh"
+  /(?:^|[.!?\n]\s*)(?:por favor\s+)?(?:salvar|guardar|adicionar|armazenar)\s+(?:(?:isto|isso)\s+)?(?:em|no)\s+memesh\b/im,
+
+  // Traditional Chinese: 記下來, 記到/存到/寫進/存進 memesh|記憶
+  /記下來|記到\s*(?:memesh|記憶)|存到\s*(?:memesh|記憶)|寫進\s*(?:memesh|記憶)|存進\s*(?:memesh|記憶)/,
+];
+
+export function detectRememberIntent(prompt) {
+  if (!prompt || typeof prompt !== 'string') return false;
+  for (const re of INTENT_PATTERNS) {
+    if (re.test(prompt)) return true;
+  }
+  return false;
+}
+
+// The returned string is consumed BY THE LLM as additionalContext, NOT by
+// configuration or by Claude Code itself. Edits here change LLM behavior,
+// not hook behavior.
+export function buildHint() {
+  return [
+    '<memesh-remember-intent>',
+    'The user just asked you to save / remember content. Use memesh for cross-project recall:',
+    '',
+    '1. Decide WHAT to remember from the conversation context. Be specific — pick observations',
+    '   that will be useful in *future* sessions, not session-local state.',
+    '',
+    '2. Decide the SCOPE (this drives namespace + tags):',
+    '   • Machine-level / cross-project / preferences  → memesh namespace=personal',
+    '   • Project-internal decision / pattern / lesson → memesh + project tag (e.g. tag:project:memesh)',
+    '   • Universal / public best practice             → memesh namespace=global (rare)',
+    '',
+    '3. Call `mcp__memesh__remember` with:',
+    '   • name: descriptive entity name (e.g., "aws-cdk-stack-pattern")',
+    '   • type: one of (decision, pattern, lesson_learned, bug, process, preference, etc.)',
+    '   • observations: array of specific facts / steps / rationale',
+    '   • tags: relevant tags (programming language, framework, domain)',
+    '   • namespace: personal (default) | team | global',
+    '',
+    '4. Confirm to the user with: entity name + memesh ID returned by the tool.',
+    '</memesh-remember-intent>',
+  ].join('\n');
+}
+
+function logError(scope, msg) {
+  // Hooks may write to stderr without blocking prompt submission. Use this
+  // to surface failures in Claude Code debug logs instead of swallowing.
+  try {
+    process.stderr.write(`[memesh:${scope}] ${msg}\n`);
+  } catch {
+    // stderr itself failing is unrecoverable; stay silent.
+  }
+}
+
+// Only run the stdin pipeline when invoked directly as a script — not when
+// imported by the test suite for in-process unit testing. On Windows,
+// `file://${process.argv[1]}` produces an invalid URL because the path uses
+// backslashes; pathToFileURL() correctly normalizes to a file:// URL on
+// every platform, so the comparison is portable.
+const isMainModule = import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      if (!isAutoCaptureEnabled(process.env)) return process.exit(0);
+
+      // Distinguish empty stdin (legitimate degenerate event) from malformed
+      // input (protocol drift). Both stay non-blocking, but only malformed
+      // input is logged — empty is normal, garbage indicates a real bug.
+      let data = {};
+      const trimmed = input.trim();
+      if (trimmed) {
+        try {
+          data = JSON.parse(trimmed);
+        } catch (parseErr) {
+          logError('user-prompt-intent', `malformed stdin JSON (len=${input.length}): ${parseErr.message}`);
+          return process.exit(0);
+        }
+      }
+
+      // Claude Code sends `prompt`. The `user_prompt` fallback is defensive:
+      // Claude Code's transcript format changed once before (2026-05-07), so
+      // we accept either name to survive a similar rename. If both are absent
+      // or non-string, detectRememberIntent's type guard returns false safely.
+      const prompt = data.prompt ?? data.user_prompt ?? '';
+      if (!detectRememberIntent(prompt)) return process.exit(0);
+
+      const out = {
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: buildHint(),
+        },
+      };
+      process.stdout.write(JSON.stringify(out));
+      process.exit(0);
+    } catch (err) {
+      logError('user-prompt-intent', err?.message || err);
+      process.exit(0);
+    }
+  });
+}

package/skills/memesh/SKILL.md

@@ -29,15 +29,19 @@ If MeMesh is installed as a Claude Code plugin, these happen **without any actio
 
 | Hook | When | What it does |
 |------|------|-------------|
-| **SessionStart** | Every session begins | Auto-recalls top memories for current project + surfaces lesson warnings |
-| **PostToolUse** | After `git commit` | Auto-tracks commit with diff stats as a memory entity |
+| **SessionStart** | Every session begins | Auto-recalls top memories for current project + surfaces lesson warnings + (opt-in) agentic-orchestration banner |
+| **PreToolUse (Edit)** | Before editing files | Injects memories related to the file or project |
+| **PreToolUse (Bash)** | Before bash commands | (Opt-in) Nudges Claude to dispatch high-verifiability commands as background agents |
+| **UserPromptSubmit** | When you submit a prompt | Detects "remember this" intent (5 languages: en, es, fr, pt, zh-TW) and reminds Claude to use memesh |
+| **PostToolUse (Commit)** | After `git commit` | Auto-tracks commit with diff stats as a memory entity |
 | **Stop** | Session ends | Auto-captures session knowledge + runs LLM failure analysis → lessons |
 | **PreCompact** | Before context compaction | Saves important knowledge before conversation history is compressed |
 
 **You do NOT need to manually:**
-- Recall at session start (hook does it)
-- Remember commits (hook does it)
-- Summarize sessions (hook does it)
+- Recall at session start (SessionStart hook does it)
+- Remember commits (PostToolUse hook does it)
+- Summarize sessions (Stop hook does it)
+- Remember when you say "記下來" / "remember this" (UserPromptSubmit hook reminds Claude)
 
 **You DO need to manually** use the commands below for intentional knowledge management.
 

package/skills/memesh-review/SKILL.md

@@ -89,9 +89,33 @@ memesh remember --name "missing-knowledge" --type decision --obs "..."
 memesh recall --limit 5 --json    # confirm changes took effect
 ```
 
+## Documentation & Code Quality Checks
+
+**For comprehensive documentation synchronization and lint checks**, use:
+```bash
+@sa:comprehensive-code-review
+```
+
+This skill includes:
+- **Dim 17: Documentation Synchronization** — version consistency, API docs, architecture docs, feature docs, deprecated terms, breaking changes
+- **Dim 18: Code Style & Lint** — lint errors/warnings, security rules, disabled rules, style consistency
+
+**MeMesh-specific automation**:
+```bash
+# Quick verification (memesh-specific checks)
+./scripts/verify-docs-sync.sh
+# Exit code 0 = all checks pass
+
+# Lint check
+npm run lint  # 0 errors expected, ~83 warnings (technical debt)
+```
+
+---
+
 ## Tips
 
 - Run every 1-2 weeks to keep memory healthy
 - Health score < 50 → too many stale or low-quality memories
 - Noise > 80% → encourage deliberate `memesh remember` for decisions
 - Dashboard available at: http://localhost:3737/dashboard (run `memesh serve` first)
+- **Before merge**: Run documentation sync checklist above to prevent drift