@pcircle/memesh 4.8.3 → 4.8.5

package/scripts/hooks/_shared.js

@@ -585,6 +585,11 @@ export function captureEntity(db, { name, type, observations = [], tags = [], ti
   // retried, because the callers dedupe on the entity NAME existing —
   // `INSERT OR IGNORE` reports "already there" on the next run and the
   // half-written state is permanent.
+  //
+  // Returns `{ id, isNew, observationsWritten }`, or null when the entity row
+  // could not be resolved. `observationsWritten` may be lower than
+  // `observations.length`: an observation whose exact content is already on
+  // the entity is not stored again (see the dedupe in captureEntityInner).
   return db.transaction(() => captureEntityInner(db, { name, type, observations, tags, title, metadata }))();
 }
 
@@ -655,8 +660,47 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
   // BY + the one join rule), via the generated fts-index copy.
   const prevObsText = isNew ? undefined : indexedObservationText(db, id);
 
+  // Never store the same sentence twice on one entity (#240, widened).
+  //
+  // #240 was fixed in session-summary.js alone, with an EXISTENCE guard: "if
+  // this session already has an entity, bail". Its two siblings never got one
+  // and wrote 2,202 duplicate rows on the maintainer's graph —
+  // `pre-compact-<sessionId>` 2,188 of them (worst entity: 220 observations,
+  // 2 distinct), `commit-<sha>` 14.
+  //
+  // The guard belongs HERE, on CONTENT, not there, on existence, because a
+  // pre-compact entity is per-session and a session legitimately compacts
+  // more than once: entity 1947's 110 captures span four days. An existence
+  // guard would have dropped a second, genuinely different compaction
+  // ("Tool calls: 47", "Files edited: …") along with the identical ones. A
+  // content guard drops only rows that add nothing — a re-write of a sentence
+  // already stored carries no information, whatever produced it.
+  //
+  // Unconditional rather than opt-in: every caller of this function is an
+  // auto-capture hook writing machine-derived facts, and none of them has a
+  // case where re-storing an identical string means something. A flag two of
+  // three callers pass would be one more proxy for the question.
+  //
+  // Filtered ONCE, up front, because `allObsText` below composes the FTS text
+  // from this list rather than re-reading the rows. Filtering only at the
+  // insert loop would index text for rows that do not exist, and
+  // `entities_fts` is contentless: the next delete would not match, which is
+  // the "database disk image is malformed" failure this file warns about
+  // above. The `seen` set also collapses repeats WITHIN one call.
+  const seen = new Set(
+    isNew
+      ? []
+      : db.prepare('SELECT content FROM observations WHERE entity_id = ?').all(id).map((r) => r.content),
+  );
+  const freshObservations = [];
+  for (const obs of observations) {
+    if (seen.has(obs)) continue;
+    seen.add(obs);
+    freshObservations.push(obs);
+  }
+
   const insertObs = db.prepare('INSERT INTO observations (entity_id, content) VALUES (?, ?)');
-  for (const obs of observations) insertObs.run(id, obs);
+  for (const obs of freshObservations) insertObs.run(id, obs);
   const insertTag = db.prepare('INSERT OR IGNORE INTO tags (entity_id, tag) VALUES (?, ?)');
   for (const tag of tags) insertTag.run(id, tag);
 
@@ -673,7 +717,7 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
   // upserted entity's accumulated observation count.
   const obsParts = [];
   if (prevObsText) obsParts.push(prevObsText);
-  if (observations.length) obsParts.push(joinIndexedObservations(observations));
+  if (freshObservations.length) obsParts.push(joinIndexedObservations(freshObservations));
   const allObsText = joinIndexedObservations(obsParts);
   // Current title is fully determined by the branches above — no re-read.
   const currentTitle = isNew
@@ -681,7 +725,11 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
     : ((title !== undefined && title !== previousTitle) ? title : previousTitle);
   insertFtsRow(db, id, name, allObsText, currentTitle);
 
-  return { id, isNew };
+  // `observationsWritten` is what actually landed, which is no longer the same
+  // as `observations.length` once the dedupe above can drop rows. A caller
+  // that reports a count to the user must read this one — pre-compact.js
+  // printed "Saved 2 observations" on a run that stored none.
+  return { id, isNew, observationsWritten: freshObservations.length };
 }
 
 const PRIVATE_DIR_MODE = 0o700;

package/scripts/hooks/decision-nudge.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+// Decision Nudge — PostToolUse hook for ExitPlanMode and AskUserQuestion (#277).
+//
+// MeMesh's read side is automatic (SessionStart, PreToolUse Edit/Write inject
+// memories), but the write side had no in-flow trigger: an agent could make
+// several decisions in a session and store none of them until the user said
+// "remember this". `ExitPlanMode` (a plan just got approved) and
+// `AskUserQuestion` (the user just chose between options) are the two tool
+// calls where a decision is most likely to have just been made, so this hook
+// fires there and reminds the model — once per tool per session — to use
+// `remember` if the decision is worth keeping.
+//
+// Contract, in order of importance:
+//   1. NEVER block or slow the tool call: every failure path is a silent
+//      pass (with a stderr trace for anything that looks like schema
+//      drift), and this hook only ever emits additionalContext — exit code
+//      stays 0 no matter what.
+//   2. NEVER open the database. Unlike the capture hooks (post-commit,
+//      session-summary, pre-compact), this hook writes nothing to MeMesh
+//      itself — it only reminds the model to. Nothing here needs a
+//      knowledge-graph handle, so nothing opens one; that keeps the hook
+//      fast (well under its 5s budget) and removes an entire class of
+//      failure (lock contention, migration, corrupt schema) from a hook
+//      whose only job is a one-line reminder.
+//   3. Rate-limited to at most once per tool per session, or a plan-heavy
+//      session would see the same line after every ExitPlanMode call. A
+//      per-(session, tool) flag file under MEMESH_DIR is the mechanism —
+//      see claimNudge() for why, and why it is a NEW mechanism rather than
+//      a revived one.
+
+import { openSync, closeSync, writeSync, constants as fsConstants } from 'fs';
+import { join } from 'path';
+import { ensurePrivateDir, getMemeshDirFromDbPath } from './_shared.js';
+
+// The only two tools this hook is wired to in hooks/hooks.json — kept as an
+// explicit allowlist (not "any PostToolUse call") so a future matcher typo
+// or a Claude Code tool rename fails closed (no nudge) rather than nudging
+// on every tool call.
+const TARGET_TOOLS = new Set(['ExitPlanMode', 'AskUserQuestion']);
+
+// Real Claude Code session ids are UUIDs; test fixtures use short slugs like
+// `contract-8`. Restricting to this set is what makes the id safe to embed
+// directly in a filename below — anything that fails this (including a
+// missing/non-string id) exits quietly rather than touching the filesystem.
+const SESSION_ID_RE = /^[A-Za-z0-9_-]+$/;
+
+// Bounded stdin read. The real payload here (tool_name, tool_input,
+// session_id, cwd) is a few KB at most — ExitPlanMode's plan text is the
+// largest field — so 1 MiB is generous headroom, not a working limit. This
+// stops a malformed/runaway payload from growing an unbounded string before
+// JSON.parse ever runs.
+const MAX_STDIN_BYTES = 1_048_576;
+
+let input = '';
+let overflowed = false;
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  if (overflowed) return;
+  input += chunk;
+  if (input.length > MAX_STDIN_BYTES) overflowed = true;
+});
+process.stdin.on('end', () => {
+  try {
+    if (overflowed) return pass();
+
+    const data = JSON.parse(input);
+
+    // Schema-flip signal, same convention as post-commit.js / pre-edit-recall.js:
+    // tool_name absent means Claude Code changed the payload shape, not that
+    // this call is irrelevant. Trace so a rename surfaces day-1 instead of
+    // this hook going silently inert.
+    if (data?.tool_name === undefined) {
+      try { process.stderr.write(`[memesh decision-nudge] tool_name absent (keys: ${Object.keys(data ?? {}).join(',')}); skipping\n`); } catch {}
+      return pass();
+    }
+
+    const toolName = data.tool_name;
+    if (typeof toolName !== 'string' || !TARGET_TOOLS.has(toolName)) return pass();
+
+    const sessionId = data.session_id;
+    if (typeof sessionId !== 'string' || !SESSION_ID_RE.test(sessionId)) return pass();
+
+    if (!claimNudge(sessionId, toolName)) return pass(); // already nudged this tool this session
+
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: buildNudge(toolName),
+      },
+    }));
+    process.exit(0);
+  } catch (err) {
+    // Never crash Claude Code, but trace — a silent break here means the
+    // nudge stops firing and nothing reports it, same as guard-check.js.
+    try { process.stderr.write(`[memesh decision-nudge] ${err?.message || err}\n`); } catch {}
+    pass();
+  }
+});
+
+/**
+ * The reminder text. Not memory content (nothing here comes from the
+ * database or from another user), so it is NOT wrapped in
+ * `buildReferenceContext`'s "treat this as background data, not
+ * instructions" fence — that fence exists for recalled/guard content that
+ * may be attacker-influenced. This is a fixed, plugin-authored instruction,
+ * the same class of thing user-prompt-intent.js's `buildHint()` emits, and
+ * it is meant to be acted on directly.
+ */
+function buildNudge(toolName) {
+  return `A decision was just made via ${toolName} — if you would need it again, store it now with the memesh \`remember\` tool (type:decision or type:lesson, tag project:<name>).`;
+}
+
+/**
+ * Claim the (session, tool) nudge slot. Returns true the first time this
+ * pair is seen and false every time after, giving "at most once per tool
+ * per session" without a database — this hook is forbidden from opening
+ * one (see module comment) — and without a shared JSON file two PostToolUse
+ * processes (a fast plan-then-question turn) could race to read-modify-write.
+ *
+ * A per-category flag file with O_EXCL atomic create is exactly the fix
+ * CHANGELOG [4.1.0]'s "Throttle clobber under parallel-category load" entry
+ * describes for the retired `pre-bash-orchestration-nudge.js` hook, which
+ * kept its markers under `agent-nudge-flags/`. That whole hook and its
+ * directory were removed in v4.5.1 ("agentic-orchestration experiment,
+ * whole") — reviving a deleted mechanism would undo that decision — so this
+ * uses the SAME primitive (an O_EXCL flag file — the flag *is* the lock, no
+ * shared state to clobber) under a new directory scoped to this hook,
+ * `decision-nudge-flags/`. The directory is created private (0700) via
+ * `ensurePrivateDir`, matching every other per-hook marker under MEMESH_DIR.
+ */
+function claimNudge(sessionId, toolName) {
+  const dir = join(getMemeshDirFromDbPath(), 'decision-nudge-flags');
+  const flagPath = join(dir, `${sessionId}-${toolName}.flag`);
+  try {
+    ensurePrivateDir(dir);
+    const fd = openSync(flagPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+    try { writeSync(fd, String(Date.now())); } finally { closeSync(fd); }
+    return true;
+  } catch (err) {
+    if (err?.code === 'EEXIST') return false; // already nudged this session/tool
+    // Any other failure (disk full, permission denied) must not block the
+    // tool call, and the safe default for a hint is silence rather than a
+    // duplicate-nudge storm — so this counts as "already claimed".
+    try { process.stderr.write(`[memesh decision-nudge] could not claim ${flagPath}: ${err?.message || err}\n`); } catch {}
+    return false;
+  }
+}
+
+function pass() {
+  process.exit(0);
+}

package/scripts/hooks/post-commit.js

@@ -168,6 +168,17 @@ process.stdin.on('end', () => {
       // TYPE, which a hand-typed `memesh learn` satisfied all by itself.
       // The commit subject IS the title — git authors already wrote a
       // one-line human summary; nothing to synthesize.
+      //
+      // Re-capture of an already-stored commit is expected and harmless: this
+      // hook runs on PostToolUse, so any later Bash call while HEAD is
+      // unchanged rebuilds the same `commit-<sha>` payload. It used to APPEND
+      // it — three commit entities on the maintainer's graph reached 6
+      // observations / 3 distinct, one triple re-written 107 seconds after the
+      // first. captureEntity now refuses to store an observation whose exact
+      // content is already on the entity (#240, widened), which is the right
+      // guard here rather than "skip if the entity exists": a sha is immutable,
+      // so any line that DOES differ on a later run (diff stats that failed the
+      // first time and succeeded now) is new information and must still land.
       const written = captureEntity(db, {
         name: entityName,
         type: 'commit',

package/scripts/hooks/pre-compact.js

@@ -159,12 +159,20 @@ process.stdin.on('end', () => {
     // it announced a save that may not have happened, with a number that never
     // matched the one entity and handful of observations actually written.
     //
-    // `obsLines.length` is the honest count on the success branch:
-    // `captureEntity` inserts every observation or throws, so a non-null return
-    // means all of them landed.
+    // `written.observationsWritten` is the honest count, NOT `obsLines.length`:
+    // a session compacts more than once, and the second compaction's lines are
+    // usually word-for-word the first's ("Compaction reason: auto", "Tool
+    // calls: 0"), which captureEntity now declines to store twice. Reporting
+    // the built count would announce "Saved 2 observations" on a run that
+    // stored none — the same success-shaped lie this comment block exists to
+    // stop. Zero written is still a successful run: the memory is already
+    // there.
+    const stored = written ? written.observationsWritten : 0;
     const hookOutput = {
       systemMessage: written
-        ? `Saved ${obsLines.length} observations to MeMesh before compaction`
+        ? (stored > 0
+          ? `Saved ${stored} observations to MeMesh before compaction`
+          : 'MeMesh: this compaction added nothing new (already captured)')
         : 'MeMesh: could not save pre-compaction insights (see stderr)',
     };
     console.log(JSON.stringify(hookOutput));

package/scripts/hooks/session-start.js

@@ -334,11 +334,24 @@ function detectInstallChannelHook(pluginRoot) {
  * Claude Code wording rather than suppressing the hint entirely — the
  * banner is more useful naming the majority host than naming none.
  */
+/**
+ * Which plugin host is this install under — or `'unknown'` when we could not
+ * ask.
+ *
+ * `null` is a real answer from `detectPluginHost`: "this path is not under any
+ * plugin cache". So `detectPluginHost?.(root) ?? null` inside a bare catch,
+ * which is what this was, gave a module that failed to load and a detector
+ * that threw the SAME value as a confident "not Codex" — and
+ * `pluginUpgradeLine` then handed every Codex user the Claude Code command.
+ * `getCurrentInstallChannel` above already returns `'unknown'` for exactly
+ * this state; this now matches it.
+ */
 function pluginHostOf(pluginRoot) {
+  if (typeof _installChannelMod?.detectPluginHost !== 'function') return 'unknown';
   try {
-    return _installChannelMod?.detectPluginHost?.(pluginRoot) ?? null;
+    return _installChannelMod.detectPluginHost(pluginRoot);
   } catch {
-    return null;
+    return 'unknown';
   }
 }
 
@@ -354,9 +367,17 @@ function pluginHostOf(pluginRoot) {
  * happened. One owner, so it cannot happen again.
  */
 function pluginUpgradeLine(pluginRoot) {
-  if (pluginHostOf(pluginRoot) === 'codex') {
+  const host = pluginHostOf(pluginRoot);
+  if (host === 'codex') {
     return `    Run: codex plugin marketplace upgrade pcircle-memesh && codex plugin add memesh@pcircle-memesh`;
   }
+  if (host === 'unknown') {
+    // Naming one host's command here would be a guess presented as an
+    // instruction. Rare — it needs `dist/core/install-channel.js` to be
+    // missing or unloadable — but that is a broken install, which is exactly
+    // when wrong upgrade advice costs the most.
+    return `    Run: memesh upgrade-plugin   (on Codex: codex plugin marketplace upgrade pcircle-memesh && codex plugin add memesh@pcircle-memesh)`;
+  }
   return `    Run: memesh upgrade-plugin   (no CLI? npx @pcircle/memesh upgrade-plugin — or reinstall from /plugin UI)`;
 }
 

package/scripts/upgrade-plugin.sh

@@ -30,6 +30,54 @@
 
 set -uo pipefail
 
+# D9: removes every OTHER stale version directory under $root, not just the
+# one an upgrade just swapped out. Before the atomic-swap rename elsewhere in
+# this script, an interrupted or pre-this-mechanism upgrade could leave a
+# version directory behind with nothing left to remove it later — measured
+# on a real machine: 9 old version directories, 1.2 GB, accumulated with no
+# bound. Only entries whose full name is exactly `<major>.<minor>.<patch>`
+# are touched, so a `.staging-*`/`.previous-*` marker from a genuinely
+# concurrent run (should be impossible under $LOCK_DIR, but this check does
+# not rely on that) or anything else unexpected under $root is left alone.
+# $keep_version is always excluded; an optional $also_keep protects a second
+# name — the registry's OWN recorded install path (however it is spelled),
+# so the noncanonical-path repair in section 2 below can keep leaving that
+# one directory alone for a human to clean up, exactly as it already did
+# before this function existed.
+#
+# Defined this early, and callable on its own, so
+# `tests/upgrade-plugin-cache-sweep.test.ts` can source this file with
+# MEMESH_UPGRADE_PLUGIN_SOURCE_ONLY=1 (below) and call it directly against a
+# throwaway root — testing the shipped function, not a hand-copied
+# reimplementation of it — without running the rest of this script, which
+# talks to a real Claude Code marketplace checkout.
+sweep_stale_cache_versions() {
+  local root="$1" keep_version="$2" also_keep="${3:-}" entry name
+  [ -d "$root" ] || return 0
+  for entry in "$root"/*; do
+    [ -d "$entry" ] || continue
+    name="$(basename "$entry")"
+    [ "$name" = "$keep_version" ] && continue
+    [ -n "$also_keep" ] && [ "$name" = "$also_keep" ] && continue
+    if printf '%s' "$name" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+      rm -rf "$entry" 2>/dev/null
+      if [ -e "$entry" ]; then
+        echo "WARNING: could not remove stale cached version at $entry — remove it manually." >&2
+      fi
+    fi
+  done
+}
+
+# Test-only escape hatch: source this file with this variable set to load
+# `sweep_stale_cache_versions` (and any other function defined above this
+# guard) without running the rest of the script. `return` exits a sourced
+# file without killing the parent shell; `|| exit 0` is the fallback for the
+# (unsupported, but harmless to guard) case of someone executing the script
+# directly with the variable set.
+if [ "${MEMESH_UPGRADE_PLUGIN_SOURCE_ONLY:-0}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
 if [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then
   CLAUDE_CONFIG_ROOT="$CLAUDE_CONFIG_DIR"
 elif [ -n "${HOME:-}" ]; then
@@ -282,12 +330,28 @@ ENTRY_SNAPSHOT="$(INSTALL_REGISTRY="$INSTALL_REGISTRY" CACHE_ROOT="$CACHE_ROOT"
     && path.resolve(entry.installPath) === expectedPath
     ? 'canonical'
     : 'noncanonical';
-  process.stdout.write(['selected', index, version, sha, registrySha256, installPathState, String(opened.dev), String(opened.ino)].join('\\t'));
+  // D9's cache sweep must never remove a directory the registry ITSELF
+  // still points to, canonical or not — this is the one directory the
+  // 'noncanonical … repairing it' path above (section 2) deliberately
+  // leaves in place. Reported as a bare basename, and only when that
+  // basename resolves back under this same cache root with no '..'
+  // segment, so a crafted absolute installPath from a tampered registry
+  // cannot smuggle an arbitrary path into the sweep's exclusion list.
+  const rootDir = path.resolve(process.env.CACHE_ROOT);
+  let recordedBasename = '';
+  if (typeof entry.installPath === 'string' && path.isAbsolute(entry.installPath)) {
+    const resolved = path.resolve(entry.installPath);
+    const base = path.basename(resolved);
+    if (path.join(rootDir, base) === resolved && !/[\\r\\n\\t]/.test(base)) {
+      recordedBasename = base;
+    }
+  }
+  process.stdout.write(['selected', index, version, sha, registrySha256, installPathState, String(opened.dev), String(opened.ino), recordedBasename].join('\\t'));
 ")" || {
   echo "ERROR: could not read the installed memesh entries from $INSTALL_REGISTRY" >&2
   exit 1
 }
-IFS=$'\t' read -r ENTRY_STATE ENTRY_INDEX CURRENT_VERSION INSTALLED_SHA ORIGINAL_REGISTRY_SHA256 INSTALL_PATH_STATE ORIGINAL_REGISTRY_DEV ORIGINAL_REGISTRY_INO <<< "$ENTRY_SNAPSHOT"
+IFS=$'\t' read -r ENTRY_STATE ENTRY_INDEX CURRENT_VERSION INSTALLED_SHA ORIGINAL_REGISTRY_SHA256 INSTALL_PATH_STATE ORIGINAL_REGISTRY_DEV ORIGINAL_REGISTRY_INO RECORDED_INSTALL_BASENAME <<< "$ENTRY_SNAPSHOT"
 case "$ENTRY_STATE" in
   identity-changed)
     echo "ERROR: installed_plugins.json changed file identity while this upgrade was reading it — refusing to continue." >&2
@@ -620,6 +684,11 @@ if [ -e "$PREVIOUS_PATH" ] || [ -L "$PREVIOUS_PATH" ]; then
   echo "         Remove it manually when no Claude Code process is using it: rm -rf \"$PREVIOUS_PATH\"" >&2
 fi
 
+# D9: sweep every OTHER stale version directory under $CACHE_ROOT, not just
+# the one this run just swapped out — see `sweep_stale_cache_versions`'s own
+# definition near the top of this file for why.
+sweep_stale_cache_versions "$CACHE_ROOT" "$NEW_VERSION" "$RECORDED_INSTALL_BASENAME"
+
 # ─── 7. Done ─────────────────────────────────────────────────────────────
 echo ""
 echo "✓ MeMesh upgraded: $CURRENT_VERSION (${INSTALLED_SHA:0:8}) -> $NEW_VERSION (${MARKETPLACE_SHA:0:8})"

package/skills/memesh/SKILL.md

@@ -100,7 +100,10 @@ they have no recipient identity. If you already know the exact logical
 recipient, pass `recipient` with `project` (MCP) or use
 `memesh briefing --project <name> --recipient <id>`. The scoped line names the
 project and recipient and directs you to `message poll` first, then `message
-fetch` each returned `message_id`; fetching does not acknowledge.
+fetch` each returned `message_id`; fetching does not acknowledge. At zero
+unread it also says so explicitly if that exact recipient id has never been
+seen in this project at all — treat that as a probable typo in `--recipient`,
+not as an empty, healthy inbox.
 Exception: under Claude Code the session-start hook has ALREADY injected this
 exact block — do not call it again (see "What's Already Automatic").
 
@@ -145,6 +148,7 @@ If MeMesh is installed as a Claude Code plugin, these happen **without any actio
 | **PreToolUse (Edit/Write)** | Before editing files | Injects memories related to the file or project |
 | **UserPromptSubmit** | When you submit a prompt | Detects "remember this" intent (5 languages) and reminds Claude to use memesh |
 | **PostToolUse (Bash)** | After `git commit` | Auto-tracks the commit with diff stats as a memory entity |
+| **PostToolUse (ExitPlanMode/AskUserQuestion)** | A plan is approved or you answer a question | Reminds Claude to `remember` the decision if it's worth keeping — once per tool per session |
 | **Stop** | Session ends | Auto-captures session knowledge + runs LLM failure analysis → lessons |
 | **PreCompact** | Before context compaction | Saves important knowledge before history is compressed |
 | **PreToolUse (Bash)** | Before a command runs | Fires accepted lesson-guards — warns when a recorded mistake is about to repeat |