@pcircle/memesh 4.8.5 → 4.9.0

package/scripts/hooks/session-summary.js

@@ -4,26 +4,9 @@
 // Extracts knowledge from completed Claude Code sessions
 // and stores as session-insight entities in MeMesh.
 //
-// THIS HOOK STAYS, and that was an open question rather than an assumption.
-// `dream run --from-transcripts` reads the same sessions from their raw JSONL
-// and does not depend on this hook having fired, so the obvious next step was
-// to retire the hook as redundant. Measured first, on a real graph
-// (2026-08-09, 214 active entities, ollama nomic-embed-text, L2 over the same
-// `name + observations` text the runtime embeds):
-//
-//   every transcript-mined memory -> its nearest hook-captured entity
-//     min 0.784   p25 0.821   p50 0.865   max 0.946
-//     within 0.55: 0 of 47.   within 0.70: 0 of 47.
-//
-// Nothing the transcript miner produced came within 0.78 of anything this hook
-// recorded. They are not two views of the same material: this hook records what
-// HAPPENED (files touched, commands run, commits), the miner extracts what was
-// DECIDED and what was LEARNED. Retiring either one loses a whole category.
-
 import { createRequire } from 'module';
 import { basename, join } from 'path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'fs';
-import { spawn } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
 import { pathToFileURL } from 'url';
 import {
   AUTO_CAPTURE_TAG,
@@ -32,7 +15,6 @@ import {
   extractCitedMemoryIds,
   getMemeshDirFromDbPath,
   getProjectName,
-  importFromPluginRoot,
   isAutoCaptureEnabled,
   openHookDb,
   readUpdateCheckCache,
@@ -47,24 +29,17 @@ import {
 
 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;
+let installChannel = 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);
+  const pluginRoot = resolvePluginRoot(import.meta.url);
+  const modulePath = join(pluginRoot, 'dist/core/install-channel.js');
+  if (existsSync(modulePath)) {
+    installChannel = await import(pathToFileURL(modulePath).href);
   }
-} catch { /* best-effort */ }
+} catch {
+  // Best-effort: source checkouts may not have built dist output yet.
+}
 
-/**
- * Run auto-update at Stop hook: reads cache, evaluates policy, and dispatches
- * the detached updater runner 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);
@@ -75,11 +50,9 @@ async function runAutoUpdateAtStop() {
     const cache = readUpdateCheckCache(installedVersion);
     const policy = resolveAutoUpdatePolicy(process.env);
     const decision = decideAutoUpdateHook(installedVersion, cache, policy);
-    if (decision.run) {
-      await spawnAutoUpdate(decision.latest, _installChannelMod);
-    }
+    if (decision.run) await spawnAutoUpdate(decision.latest, installChannel);
   } catch {
-    // Best-effort — never crash the hook.
+    // Best-effort: update failures must never break session capture.
   }
 }
 
@@ -183,13 +156,9 @@ function parseTranscript(transcriptPath) {
             const text = typeof block.content === 'string'
               ? block.content
               : JSON.stringify(block.content);
-            // Same reason as the bash branch, and one more: this array is
-            // ALSO the payload `analyzeFailure` sends to the configured LLM
-            // provider. A failed request that echoes its own Authorization
-            // header — the ordinary shape of an auth error — would be stored
-            // and then transmitted off the machine. Redacted once here, at
-            // the point the text enters the process, so every downstream use
-            // inherits it.
+            // Same reason as the bash branch: a failed request may echo its
+            // own Authorization header. Redact once, where text enters the
+            // process, so every downstream use inherits it.
             errorsEncountered.push(redactSecrets(text).slice(0, 200));
           }
         }
@@ -338,33 +307,12 @@ process.stdin.on('end', async () => {
     // healthy exit, so it MUST stamp (see stampHookRunOnly).
     if (toolCallCount < 3) { stampHookRunOnly(process.env, 'session-summary'); 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 = getProjectName(cwd);
 
     // Open DB via shared helper — applies SCHEMA_SQL + status migration.
     // { fts: true } guarantees the entities_fts table exists so captureEntity()
     // can keep it in sync — session-insight memories must be FTS-recallable.
     //
-    // sqlite-vec is NOT loaded here, and used to be. The comment said it was
-    // needed "for embedding-aware recall-effectiveness tracking" — but this
-    // hook runs exactly two statements, `PRAGMA table_info(entities)` and
-    // `SELECT id FROM entities WHERE name = ?`, and `captureEntity` in
-    // _shared.js touches no vectors either. Nothing here has ever used the
-    // extension.
-    //
-    // It was not free. sqlite-vec ships its engine as a per-platform file
-    // through optionalDependencies, and on a platform it does not publish the
-    // load threw — past the `require` guard, which never fired because the JS
-    // wrapper resolves fine and the throw happens later inside
-    // `sqliteVec.load()`. Measured with the platform binary hidden: the whole
-    // Stop capture vanished (0 entities against a control run's 1) and the
-    // user got a `Require stack:` dump on stderr. An extension nobody calls
-    // was silently costing every session on those platforms its memory.
     const { db } = openHookDb(process.env, { fts: true });
     let writeFailed = false;
     try {
@@ -628,68 +576,17 @@ process.stdin.on('end', async () => {
       db.close();
     }
 
-    // ── LLM-powered failure analysis (Level 1 only) ──────────────────────
-    // Runs AFTER the hook's own DB is closed.
-    // Uses the core module's DB singleton (openDatabase/closeDatabase).
-    // Wrapped in its own try/catch — never blocks rule-based extraction.
-    if (errorsEncountered.length > 0 && filesEdited.length > 0) {
-      try {
-        // F5: derive pluginRoot strictly from this file's location.
-        // See `resolvePluginRoot` for the full reasoning.
-        const pluginRoot = resolvePluginRoot(import.meta.url);
-        const configMod = await importFromPluginRoot(pluginRoot, 'dist/core/config.js');
-        const config = configMod.readConfig();
-
-        if (config.llm) {
-          const { openDatabase, closeDatabase } = await importFromPluginRoot(pluginRoot, 'dist/db.js');
-          const { analyzeFailure } = await importFromPluginRoot(pluginRoot, 'dist/core/failure-analyzer.js');
-          const { createLesson } = await importFromPluginRoot(pluginRoot, 'dist/core/lesson-engine.js');
-
-          openDatabase();
-          try {
-            // Pass cross-provider failover chain so a stale Anthropic key
-            // doesn't silently disable Stop-hook lesson generation.
-            const lesson = await analyzeFailure(errorsEncountered, filesEdited, config.llm, { fallbacks: config.llmFallbacks });
-            if (lesson) {
-              createLesson(lesson, projectName);
-            }
-          } finally {
-            closeDatabase();
-          }
-        }
-      } 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 {}
-      }
-    }
-
-    // Auto-trigger dream — solves the "Insights tab is empty for users
-    // who don't know `memesh dream run` exists" problem. Throttled to
-    // once per project per 24h, gated by minimum activity threshold.
-    // Background-detached spawn so the hook exits immediately even if
-    // the LLM call takes 30-60s. See `maybeTriggerDream` for the gate
-    // logic and dream-history.json schema.
-    try {
-      const pluginRoot = resolvePluginRoot(import.meta.url);
-      const configMod = await importFromPluginRoot(pluginRoot, 'dist/core/config.js');
-      const config = configMod.readConfig();
-      maybeTriggerDream(projectName, config, pluginRoot);
-    } catch (dreamErr) {
-      try { process.stderr.write(`[memesh] dream auto-trigger skipped: ${dreamErr?.message || dreamErr}\n`); } catch {}
-    }
   } catch (err) {
     // Never crash Claude Code — leave a trace for debugging.
     //
-    // Every error is traced now. There used to be a suppression branch for a
-    // `skip-session-capture:` sentinel, thrown when sqlite-vec was missing —
-    // an extension this hook never used. The thrower is gone, so the branch
-    // could only ever hide a real error from here on.
+    // Every error is traced. A retired suppression sentinel once hid setup
+    // failures from this hook; with that branch gone, real capture errors stay
+    // visible without crashing the host session.
     try { process.stderr.write(`[memesh session-summary] ${err?.message || err}\n`); } catch {}
   }
 
-  // Dispatch auto-update if policy + cache permit. Runs after all session work
-  // so the runner cannot overwrite dist/ while peer hooks are reading it.
+  // Update only after all session work so installed files cannot change while
+  // this hook is still reading them.
   await runAutoUpdateAtStop();
 
   // Emit NOTHING on success — not `{"suppressOutput": true}`.
@@ -711,173 +608,6 @@ process.stdin.on('end', async () => {
 function exit0() {
   process.exit(0);
 }
-
-// =============================================================================
-// Dream auto-trigger (Phase 2 / Phase 3 background runner)
-// =============================================================================
-//
-// Without an automated trigger, `memesh dream` only runs when the user
-// types it into a terminal — and most users never read the docs that
-// far. Result: Insights tab stays empty and the KG accumulates 89.7%
-// orphan rate (the maintainer's own observation on this DB).
-//
-// This trigger fires at the END of every Stop hook (after rule-based
-// session capture + optional LLM failure analysis). It:
-//   1. Loads ~/.memesh/dream-history.json — a per-project record of
-//      the last dream run timestamp + outcome.
-//   2. Throttles: skip if < THROTTLE_HOURS since the project's last
-//      run, even if the previous run produced zero proposals.
-//   3. Activity gate: skip if the project has < MIN_EPISODIC episodic
-//      entities to draw from in the last WINDOW_DAYS days.
-//   4. LLM gate: skip if no LLM provider configured (Phase 2 needs
-//      Smart Mode — Phase 3 patterns same).
-//   5. Spawns `node <pluginRoot>/dist/transports/cli/cli.js dream run
-//      --project <name> --max-llm-calls 2 --window-days 14` as a
-//      detached child process. Stdout/stderr go to a per-project log
-//      under ~/.memesh/dream-runs/ so the user can `tail -f` to see
-//      progress without the hook blocking.
-//   6. Records the run start in dream-history.json BEFORE spawning so
-//      a long-running spawn doesn't get re-triggered on the next
-//      Stop within the same window.
-//
-// The spawned process inherits config from disk, including the
-// `llmFallbacks` chain wired in commit 883abd4d, so a primary
-// outage falls through to Ollama automatically.
-
-const DREAM_THROTTLE_HOURS = 24;
-const DREAM_MIN_EPISODIC = 10;
-const DREAM_WINDOW_DAYS = 14;
-const DREAM_MAX_LLM_CALLS = 2;
-const DREAM_HISTORY_BASENAME = 'dream-history.json';
-const DREAM_LOG_DIRNAME = 'dream-runs';
-
-const DREAM_EPISODIC_TYPES = [
-  'commit',
-  'session_keypoint',
-  'session-insight',
-  'workflow_checkpoint',
-  'weekly-summary',
-  'weekly_summary',
-];
-
-// Debug-trace gate. Set MEMESH_DREAM_TRIGGER_DEBUG=1 to emit a stderr
-// breadcrumb at every gate decision in maybeTriggerDream. Contract:
-//   [memesh dream-trigger] <stage>=<value>...
-// Matches one line per stage (resolve, llm-gate, throttle-gate,
-// activity-gate, history-write, spawn). Stable across releases — if
-// you rename a stage, update the matching test fixture too.
-function dreamTrigTrace(stage, fields) {
-  if (process.env.MEMESH_DREAM_TRIGGER_DEBUG !== '1') return;
-  try {
-    const parts = Object.entries(fields || {}).map(([k, v]) => {
-      if (v === undefined) return `${k}=<undef>`;
-      if (v === null) return `${k}=<null>`;
-      return `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`;
-    });
-    process.stderr.write(`[memesh dream-trigger] ${stage} ${parts.join(' ')}\n`);
-  } catch {}
-}
-
-function dreamHistoryPath() {
-  // Test isolation: tests set MEMESH_DB_PATH to a tmp file, expecting
-  // sibling state (history, logs) to land beside it. Without honouring
-  // that, real-home `~/.memesh/dream-history.json` would be polluted
-  // by every test run. Same precedence as memesh's other state files —
-  // see `getMemeshDirFromDbPath` in `_shared.js`.
-  //
-  // Windows note: on Windows under execFileSync, env vars propagate as
-  // plain strings (no canonicalisation). If a caller passed MEMESH_DIR
-  // with mixed separators (e.g. `C:/Users/.../tmp/.memesh`), join() will
-  // happily mix `/` and `\`. Node fs accepts either — the only divergence
-  // is in pure string comparisons, which we don't do here. The trace
-  // below shows the resolved value verbatim so a Windows diagnosis run
-  // can confirm what actually arrived.
-  // The helper IS the precedence (MEMESH_DB_PATH > MEMESH_DIR > home).
-  // A hand-rolled version here inverted it (MEMESH_DIR won over
-  // MEMESH_DB_PATH), so with both set, dream history landed in a different
-  // directory than every sibling state file — plus a dead home-fallback
-  // branch, since the helper always returns a string.
-  const dir = getMemeshDirFromDbPath();
-  dreamTrigTrace('resolve', {
-    src: process.env.MEMESH_DB_PATH ? 'db-path' : (process.env.MEMESH_DIR ? 'env' : 'home'),
-    MEMESH_DIR: process.env.MEMESH_DIR,
-    MEMESH_DB_PATH: process.env.MEMESH_DB_PATH,
-    dir,
-    platform: process.platform,
-  });
-  return { dir, historyFile: join(dir, DREAM_HISTORY_BASENAME), logDir: join(dir, DREAM_LOG_DIRNAME) };
-}
-
-function readDreamHistory() {
-  try {
-    const { historyFile } = dreamHistoryPath();
-    if (!existsSync(historyFile)) return {};
-    const raw = readFileSync(historyFile, 'utf8');
-    const parsed = JSON.parse(raw);
-    return (parsed && typeof parsed === 'object') ? parsed : {};
-  } catch { return {}; }
-}
-
-function writeDreamHistory(history) {
-  try {
-    const { dir, historyFile } = dreamHistoryPath();
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(historyFile, JSON.stringify(history, null, 2));
-    dreamTrigTrace('history-write', { historyFile, ok: true, projects: Object.keys(history) });
-  } catch (err) {
-    dreamTrigTrace('history-write', { ok: false, err: err?.message || String(err) });
-    try { process.stderr.write(`[memesh dream-history write] ${err?.message || err}\n`); } catch {}
-  }
-}
-
-/**
- * Count episodic entities for the given project over the configured
- * window. Only issues a SELECT, but the handle is openHookDb's ordinary
- * read-write one (it runs the schema/migration chain) — there is no
- * read-only variant on the hook side, and this call site must not stamp
- * the heartbeat (recordHookRun is per-hook-exit, never per-open).
- */
-function countEpisodicEntities(projectName) {
-  let handle;
-  try {
-    handle = openHookDb();
-    // { db, dbPath } — don't call db.prepare() on the wrapper itself (an
-    // earlier version did, and silently skipped the gate, defeating the
-    // trigger's whole purpose).
-    const db = handle.db;
-    const since = new Date(Date.now() - DREAM_WINDOW_DAYS * 86400000).toISOString();
-    const types = DREAM_EPISODIC_TYPES.map(() => '?').join(',');
-    // Project-membership is determined by the `project:<name>` tag only.
-    // The previous implementation also OR'd on `e.name LIKE 'project-%'`
-    // as a fallback for legacy entities, but that branch over-counts when
-    // two projects share a name prefix (e.g. counting `memesh` would
-    // sweep in `memesh-cloud-keypoint-*` entities). Post-v3.0 episodic
-    // entities all carry the project tag — the auto-tagger writes it on
-    // every session_keypoint / commit / session_insight / session_lesson
-    // / failure_pattern / decision_anchor — so the tag-only path is the
-    // accurate signal. See v4.2.1 CHANGELOG known-limitations note.
-    const sql = `SELECT COUNT(DISTINCT e.id) AS n
-                 FROM entities e
-                 INNER JOIN tags t ON t.entity_id = e.id AND t.tag = ?
-                 WHERE e.status = 'active'
-                   AND e.type IN (${types})
-                   AND e.created_at >= ?`;
-    const projectTag = `project:${projectName}`;
-    const row = db.prepare(sql).get(projectTag, ...DREAM_EPISODIC_TYPES, since);
-    return row?.n ?? 0;
-  } catch (err) {
-    try { process.stderr.write(`[memesh dream-trigger count] ${err?.message || err}\n`); } catch {}
-    return 0;
-  } finally {
-    try { handle?.db?.close(); } catch {}
-  }
-}
-
-/**
- * Decide whether to fire dream for `projectName` and, if so, spawn
- * the detached background runner. Pure side effect — no return value
- * used by callers.
- */
 /**
  * Attachment record types Claude Code uses to persist a hook's own output
  * into the transcript. Anything memesh injected reaches the transcript
@@ -927,88 +657,3 @@ export function stripHookEchoes(rawTranscript) {
   }
   return kept.join('\n');
 }
-
-export function maybeTriggerDream(projectName, config, pluginRoot) {
-  dreamTrigTrace('enter', { projectName, hasLlm: Boolean(config?.llm) });
-  if (!projectName || projectName === 'unknown') {
-    dreamTrigTrace('exit', { reason: 'no-project-name', projectName });
-    return;
-  }
-
-  // Phase 2 & 3 both need a configured LLM. Without it the dreamer's
-  // first action is to push `{reason: 'no LLM configured'}` into
-  // skipped[] and exit, which would still bump our throttle clock
-  // for no value — so gate here.
-  if (!config?.llm) {
-    dreamTrigTrace('exit', { reason: 'llm-gate-fail' });
-    return;
-  }
-  dreamTrigTrace('llm-gate', { ok: true });
-
-  const history = readDreamHistory();
-  const last = history[projectName];
-  if (last?.last_run_iso) {
-    const ageMs = Date.now() - new Date(last.last_run_iso).getTime();
-    if (Number.isFinite(ageMs) && ageMs < DREAM_THROTTLE_HOURS * 3600 * 1000) {
-      dreamTrigTrace('exit', { reason: 'throttle-gate-fail', ageMs, last_run_iso: last.last_run_iso });
-      return; // throttled
-    }
-  }
-  dreamTrigTrace('throttle-gate', { ok: true, prior_last_run_iso: last?.last_run_iso });
-
-  const episodicCount = countEpisodicEntities(projectName);
-  if (episodicCount < DREAM_MIN_EPISODIC) {
-    dreamTrigTrace('exit', { reason: 'activity-gate-fail', episodicCount, threshold: DREAM_MIN_EPISODIC });
-    return;
-  }
-  dreamTrigTrace('activity-gate', { ok: true, episodicCount });
-
-  // Activity gate passed — record start BEFORE spawning so we don't
-  // re-trigger on any subsequent Stop within the window even if the
-  // child takes 30-60s.
-  history[projectName] = {
-    last_run_iso: new Date().toISOString(),
-    last_episodic_count: episodicCount,
-    last_window_days: DREAM_WINDOW_DAYS,
-  };
-  writeDreamHistory(history);
-
-  // Spawn detached so the hook exits immediately. Stdio routes to a
-  // per-project log file so the user can inspect dream output without
-  // the hook blocking on the LLM call.
-  try {
-    const { dir, logDir } = dreamHistoryPath();
-    mkdirSync(logDir, { recursive: true });
-    const safeProj = projectName.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64);
-    const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    const logFile = join(logDir, `${safeProj}-${ts}.log`);
-
-    // Append a header so a tail -f shows context for the run.
-    appendFileSync(logFile, `[memesh dream] ${new Date().toISOString()} project=${projectName} episodic_count=${episodicCount} window=${DREAM_WINDOW_DAYS}d max_llm_calls=${DREAM_MAX_LLM_CALLS}\n`);
-
-    const cliPath = join(pluginRoot, 'dist/transports/cli/cli.js');
-    if (!existsSync(cliPath)) {
-      appendFileSync(logFile, `[memesh dream] cli.js missing at ${cliPath}, skipping\n`);
-      return;
-    }
-
-    const args = [
-      cliPath, 'dream', 'run',
-      '--project', projectName,
-      '--max-llm-calls', String(DREAM_MAX_LLM_CALLS),
-      '--window-days', String(DREAM_WINDOW_DAYS),
-    ];
-
-    const logFd = require('fs').openSync(logFile, 'a');
-    const child = spawn(process.execPath, args, {
-      detached: true,
-      stdio: ['ignore', logFd, logFd],
-      env: { ...process.env, MEMESH_DIR: dir },
-    });
-    child.unref();
-    dreamTrigTrace('spawn', { ok: true, pid: child.pid, logFile, MEMESH_DIR: dir });
-  } catch (err) {
-    dreamTrigTrace('spawn', { ok: false, err: err?.message || String(err) });
-    try { process.stderr.write(`[memesh dream-trigger spawn] ${err?.message || err}\n`); } catch {}
-  }
-}

package/skills/memesh/SKILL.md

@@ -23,10 +23,11 @@ Persistent memory for AI agents. The point is continuity: the next session start
 
 All examples below use CLI. MCP tools accept the same parameters as JSON objects.
 
-## All 11 MCP tools
+## All 12 MCP tools
 
 | Tool | Purpose |
 |---|---|
+| `work_package` | Prepare one bounded untrusted `digest` (calendar cluster) or `transcript` package from the newest Claude Code session under the client's single matching MCP workspace root; submit exactly one strict result or defer. Submit only stages pending human review and retains bounded redacted source turns for comparison; agents cannot apply or reject. No hidden reasoning, raw transcript, transcript path, API key, LLM, embedding, or vector data is exposed or used; hashes identify freshness and workspace scope rather than authentication. |
 | `remember` | Store knowledge as an entity with observations, tags, and relations |
 | `recall` | Search stored knowledge; empty query lists recent memories |
 | `forget` | Archive an entity or remove one exact observation |
@@ -86,7 +87,12 @@ Use the routing and identity fields returned by `fetch`. A reply has this shape
 }
 ```
 
-An active compatible managed host can receive a native push, which removes polling for that live delivery. One-time provider enablement and a MeMesh-managed Codex app-server or Claude Channel may be required; ordinary unattached sessions are presence-only/inbound-unavailable. The bundled Gemini ACP adapter is experimental protocol-development code, not a release-gated native-wakeup provider. Adapter imports and a live router socket do not prove host registration or `host_accept`. Do not promise that a stopped, missing, or replaced session will wake up: it is not resumed or silently rerouted. Use the stable principal for logical routing, and an exact session/generation only when delivery must not move to a replacement connection. Local owns durable storage and host-native delivery; Cloud relay, A2A, SSE, discovery, or fetch is not host delivery.
+For a compatible managed host, native delivery removes polling from the inbound path only after exact live-host acceptance. On macOS and Linux, an ordinary Codex CLI session with the MeMesh plugin registers automatically at SessionStart. SessionEnd retains a bounded 45-second idle queue window; a message accepted there becomes model-visible when the same thread resumes, resume replaces the prior exact generation, and expiry removes the registration. This does not wake a stopped UI. Codex Desktop and unattached tasks are not presumed registered unless the exact running session appears in `message discover`. Separate managed Codex app-server and Claude Channel paths may require one-time owner setup. The bundled Gemini ACP adapter is experimental protocol-development code, not a release-gated native-wakeup provider. Adapter imports and a live router socket do not prove host registration or `host_accept`. Do not promise that a stopped, missing, or replaced session will wake up: it is not resumed or silently rerouted, and a failed exact-session native delivery is not replayed automatically. Use the stable principal for logical routing, and an exact session/generation only when delivery must not move to a replacement connection. Local owns durable storage and host-native delivery; Cloud relay, A2A, SSE, discovery, or fetch is not host delivery.
+
+When pairing Claude Channel with an automatically registered Codex session, use
+the complete `project` field from `memesh briefing --json` for Claude setup. Do
+not replace it with the repository basename; different project strings are
+different discovery and native-routing scopes.
 
 Durable audit does not mean unbounded silent growth. Owners can inspect it with `memesh message storage report --cutoff <ISO timestamp>`, preview bounded terminal-payload tombstones with `memesh message storage prune --cutoff <ISO timestamp>`, and explicitly add `--apply`. Never prune unresolved/offline-pending work. `MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES` is an optional owner policy; there is no default quota or automatic pruning.
 
@@ -134,13 +140,12 @@ fabricate a memory or cite a `[mem:id]` that was not actually returned.
 Recall is bounded by `limit` — a small hit count is not a graph-wide count,
 and an empty result is not proof nothing was stored: vary the wording or
 narrow by tag before concluding. Every recall answer includes a `retrieval`
-block — `truncated: true` means the window filled (more may exist);
-`degraded: true` means semantic search could not run and these are
-keyword-only results right now (`memesh doctor` explains why).
+block — `truncated: true` means the window filled (more may exist). Retrieval
+uses the local FTS5 keyword index; it does not call a model or vector service.
 
-## What's Already Automatic (Claude Code Plugin Hooks)
+## What's Already Automatic (Plugin Hooks)
 
-If MeMesh is installed as a Claude Code plugin, these happen **without any action from you**:
+With the Claude Code plugin, the first eight rows happen **without any action from you**. The final row is the separate Codex plugin SessionStart/SessionEnd companion lifecycle:
 
 | Hook | When | What it does |
 |------|------|-------------|
@@ -149,10 +154,10 @@ If MeMesh is installed as a Claude Code plugin, these happen **without any actio
 | **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 |
+| **Stop** | Session ends | Auto-captures session knowledge and applies the configured update policy |
 | **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 |
-| **SessionStart (Codex, async)** | A configured Codex session starts or resumes | Registers that exact live thread for bounded full-message native delivery; exits without registering outside the configured workspace |
+| **SessionStart/SessionEnd (Codex)** | An ordinary Codex CLI plugin session starts, resumes, or ends | Launches the detached exact-thread companion, replaces its generation on resume, and retires it after the bounded idle queue window; a matching owner-private config may override its project/principal |
 
 Because of the SessionStart hook: **in Claude Code, do NOT call `briefing` at
 session start — it is already in your context.** Call it only mid-session
@@ -226,16 +231,16 @@ memesh forget --name "old-auth-approach"                       # archive the who
 Both are soft (recoverable) — nothing is permanently removed.
 
 ### Memories are getting verbose or stale
-Use the **memesh-review** skill: it analyzes health, finds stale, conflicting
-and redundant memories, and proposes cleanup (including `memesh dream`, the
-reviewed digest pipeline). Do not hand-compress memories yourself.
+Use the **memesh-review** skill: it prepares bounded `work_package` evidence
+for an already-running local agent, then leaves every proposal pending for
+human review. Do not hand-compress memories yourself.
 
 ### Backup, share, health
 ```bash
 memesh export --tag "project:myapp" > memories.json
 memesh import memories.json --merge skip     # skip | overwrite | append
-memesh status                                # version, search level, embeddings
-memesh reindex                               # rebuild embeddings after provider change
+memesh status                                # version, install channel, update state
+memesh reindex --fts                         # rebuild the local keyword index
 ```
 
 ## Memory hygiene

package/skills/memesh-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memesh-review
-description: Review and optimize the MeMesh memory database. Analyzes health score, finds stale/conflicting/redundant memories, shows work patterns, and suggests cleanup actions. Use when asked to "review memories", "check memory health", "clean up knowledge", or "what's in my memory".
+description: Review and optimize the MeMesh memory database. Analyzes health score, finds stale or noisy memories, shows work patterns, and suggests human-reviewed cleanup actions. Use when asked to "review memories", "check memory health", "clean up knowledge", or "what's in my memory".
 user-invocable: true
 ---
 
@@ -59,11 +59,12 @@ From the recalled data, compute and present:
 
 **Verbose (5+ observations)**
 - "entity-name" (N observations) — note it; there is no one-entity compression
-  command any more. If the noise is spread across many episodic entries,
-  suggest `memesh dream run` instead.
+  command. If useful knowledge is spread across episodic entries, an already
+  running agent can prepare one MCP `work_package` for human review.
 
 **Potential conflicts**
-- "entity-A" vs "entity-B" — contradicting decisions
+- "entity-A" vs "entity-B" — inspect the text and recommend an explicit
+  `contradicts` or `supersedes` relation; MeMesh does not judge it automatically
 
 **Noise ratio**
 - N% auto-tracked (session_keypoint, commit) vs N% intentional knowledge
@@ -71,7 +72,7 @@ From the recalled data, compute and present:
 
 ### Recommended Actions
 1. `memesh forget --name "old-design"` (superseded)
-2. `memesh dream run --project myapp` (propose digests for the noisy clusters, then review)
+2. Ask the current agent to prepare one MCP `work_package`; then review the staged proposal
 3. `memesh remember ...` (knowledge gap in [area])
 ```
 
@@ -81,7 +82,7 @@ Present the report first. Ask which actions to execute. Then run the commands:
 
 ```bash
 memesh forget --name "outdated-entity"
-memesh dream run                  # then: memesh dream list / accept <id> / reject <id>
+# MCP work_package submits one proposal; then use dream show / accept / reject
 memesh remember --name "missing-knowledge" --type decision --obs "..."
 ```
 

package/dist/core/auto-tagger.d.ts

@@ -1,10 +0,0 @@
-import type { LLMConfig } from './config.js';
-import { type LLMAttempt } from './llm-client.js';
-export interface AutoTagOptions {
-    fallbacks?: LLMConfig[];
-    onAttempt?: (attempts: LLMAttempt[]) => void;
-}
-export declare function autoTag(name: string, type: string, observations: string[], llmConfig: LLMConfig, opts?: AutoTagOptions): Promise<string[]>;
-export declare function autoTagAndApply(entityId: number, name: string, type: string, observations: string[], llmConfig: LLMConfig, opts?: AutoTagOptions): Promise<void>;
-export declare function parseTags(text: string): string[];
-//# sourceMappingURL=auto-tagger.d.ts.map

package/dist/core/auto-tagger.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"auto-tagger.d.ts","sourceRoot":"","sources":["../../src/core/auto-tagger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAM3D,MAAM,WAAW,cAAc;IAE7B,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;IAExB,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,IAAI,CAAC;CAC9C;AAOD,wBAAsB,OAAO,CAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EAAE,EACtB,SAAS,EAAE,SAAS,EACpB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgCnB;AAMD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EAAE,EACtB,SAAS,EAAE,SAAS,EACpB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAehD"}