claude-mem-lite 2.31.2 → 2.32.2

package/hook-shared.mjs

@@ -8,6 +8,10 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from '
 import { inferProject, debugCatch } from './utils.mjs';
 import { ensureDb, DB_DIR } from './schema.mjs';
 import { getClaudePath as getClaudePathShared, resolveModel as resolveModelShared } from './haiku-client.mjs';
+// Phase D: invited-memory sentinel detection. memdir.mjs only pulls in fs/path/os/crypto;
+// adopt-content.mjs is pure strings. No circular deps — memdir doesn't import hook-shared.
+import { memdirPath as _memdirPath, isAdopted as _isAdopted } from './memdir.mjs';
+import { PLUGIN_SLUG as _PLUGIN_SLUG } from './adopt-content.mjs';
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -24,6 +28,33 @@ export const DEDUP_WINDOW_MS = 5 * 60 * 1000;            // 5 min (title dedup)
 export const RELATED_OBS_WINDOW_MS = 7 * 86400000;       // 7 days
 export const FALLBACK_OBS_WINDOW_MS = RELATED_OBS_WINDOW_MS; // same window
 
+// Phase A (v2.31.3+): MEM_QUIET_HOOKS=1 drops descriptive hook/MCP-instruction
+// bodies (File Lessons / Key Context headers, MCP WHEN-TO-USE & decision rules,
+// related-memory lesson suffix). Intended for users who adopted invited-memory
+// (MEMORY.md sentinel) or who otherwise want minimal hook noise. Function form
+// (not const) so modules importing at load time still respect later env sets
+// in-process, and tests can toggle per-call. See docs/plans/2026-04-16-invited-memory-pattern.md.
+export function isQuietHooks() {
+  return process.env.MEM_QUIET_HOOKS === '1';
+}
+
+// Phase D (v2.32.1+): if the current project has adopted our invited-memory
+// sentinel, MEMORY.md already carries the triggers at system-prompt authority
+// — so hook + MCP-instruction output can also go quiet. isQuietHooks (env)
+// remains an independent, stronger override.
+export function isAdoptedHere(cwd) {
+  try {
+    const resolved = cwd || process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
+    return _isAdopted(_memdirPath(resolved), _PLUGIN_SLUG);
+  } catch {
+    return false;
+  }
+}
+
+export function effectiveQuiet(cwd) {
+  return isQuietHooks() || isAdoptedHere(cwd);
+}
+
 // Handoff system constants
 export const HANDOFF_EXPIRY_CLEAR = 6 * 3600000;                // 6 hours (covers lunch/meeting breaks)
 export const HANDOFF_EXPIRY_EXIT = 7 * 24 * 60 * 60 * 1000;   // 7 days

package/install.mjs

@@ -224,6 +224,10 @@ async function install() {
     'lib/plan-reader.mjs',
     'lib/git-state.mjs',
     'lib/startup-dashboard.mjs',
+    // v2.32 (invited-memory): memdir primitives + adopt/unadopt CLI.
+    'memdir.mjs',
+    'adopt-content.mjs',
+    'adopt-cli.mjs',
   ];
 
   if (IS_DEV) {
@@ -807,6 +811,25 @@ async function install() {
     log('No existing database — will be created on first use');
   }
 
+  // 7b. Dogfood auto-adopt (invited-memory, Phase C T13).
+  // Only fires when install.mjs is running from the claude-mem-lite source repo
+  // itself (detected via git remote match). In npm/npx flows PROJECT_DIR is a
+  // cache dir with no git metadata, so this is a no-op for end users.
+  // --no-adopt override respected.
+  if (!flags.has('--no-adopt')) {
+    try {
+      const remote = execFileSync('git', ['-C', PROJECT_DIR, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: 'pipe' }).trim();
+      const isDogfood = /github\.com[:/]sdsrss\/claude-mem-lite(\.git)?$/i.test(remote);
+      if (isDogfood) {
+        const { cmdAdopt } = await import('./adopt-cli.mjs');
+        cmdAdopt([]);
+        ok('Invited-memory: auto-adopt for claude-mem-lite dogfood repo');
+      }
+    } catch {
+      // Not a git repo, or git missing — silent skip (this is the normal npm path).
+    }
+  }
+
   // 8. Disable old claude-mem plugin
   if (settings.enabledPlugins?.['claude-mem@thedotmack'] !== undefined) {
     settings.enabledPlugins['claude-mem@thedotmack'] = false;
@@ -851,6 +874,10 @@ async function uninstall() {
   const settings = readSettings();
   cleanupMemHooksFromSettings(settings);
 
+  // 2b. Uninstall does NOT auto-unadopt — an adopted project may be in active use
+  // by the user in other Claude Code sessions. Tell them the command instead.
+  log('Invited-memory: adopt state preserved. Run `claude-mem-lite unadopt --all` to remove sentinel sections.');
+
   // 3. Clean plugin registry entries conservatively (avoid deleting other plugins
   // from the same marketplace publisher)
   const pluginsDir = join(homedir(), '.claude', 'plugins');

package/lib/activity.mjs

@@ -0,0 +1,114 @@
+// lib/activity.mjs — activity namespace data layer (T7 v2.31)
+// Pure functions over the events table. No I/O beyond the passed-in db handle.
+//
+// Activity events are NOT memdir-compatible types; they live here precisely
+// so they don't pollute the L1 system-prompt memory section.
+
+import { sanitizeFtsQuery } from '../utils.mjs';
+
+/**
+ * Canonical event_type enum — mirrors the events.event_type CHECK constraint.
+ * Single source of truth for CLI validation, hook-llm (future T9), and any
+ * other caller that needs to guard against invalid types before INSERT.
+ * Order matches the DDL; frozen to prevent accidental mutation.
+ */
+export const EVENT_TYPES = Object.freeze([
+  'bugfix',
+  'lesson',
+  'bug',
+  'discovery',
+  'refactor',
+  'feature',
+  'observation',
+  'decision',
+]);
+
+/**
+ * Insert one event. Returns the new id (Number cast from BigInt).
+ *
+ * @param {object} db better-sqlite3 handle
+ * @param {object} params
+ * @param {string} params.project
+ * @param {string} params.event_type  one of the CHECK-constrained enum values
+ * @param {string} params.title
+ * @param {string|null} [params.body]
+ * @param {string[]|null} [params.file_paths]  stored as JSON array
+ * @param {string|null} [params.git_sha]
+ * @param {number} [params.importance=1]
+ * @param {number} [params.created_at_epoch=Date.now()]
+ * @returns {number} lastInsertRowid
+ */
+export function saveEvent(db, {
+  project,
+  event_type,
+  title,
+  body = null,
+  file_paths = null,
+  git_sha = null,
+  importance = 1,
+  created_at_epoch = Date.now(),
+}) {
+  const info = db.prepare(`
+    INSERT INTO events (project, event_type, title, body, file_paths, git_sha, importance, created_at_epoch)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    project,
+    event_type,
+    title,
+    body,
+    file_paths ? JSON.stringify(file_paths) : null,
+    git_sha,
+    importance,
+    created_at_epoch,
+  );
+  return Number(info.lastInsertRowid);
+}
+
+/**
+ * Fetch one event by id, bumping accessed_count + last_accessed_epoch.
+ * Returns the row (access bump already applied) or undefined.
+ */
+export function getEvent(db, id) {
+  db.prepare(`UPDATE events SET accessed_count = accessed_count + 1, last_accessed_epoch = ? WHERE id = ?`)
+    .run(Date.now(), id);
+  return db.prepare(`SELECT * FROM events WHERE id = ?`).get(id);
+}
+
+/**
+ * FTS5 search filtered by project (and optionally event_type).
+ * Excludes superseded events. Returns up to `limit` rows ordered by FTS rank.
+ */
+export function searchEvents(db, query, { project, type = null, limit = 10 } = {}) {
+  const q = sanitizeFtsQuery(query);
+  if (!q) return [];
+  const typeClause = type ? 'AND e.event_type = ?' : '';
+  const sql = `
+    SELECT e.*
+    FROM events_fts
+    JOIN events e ON e.id = events_fts.rowid
+    WHERE events_fts MATCH ?
+      AND e.project = ?
+      AND e.superseded_at_epoch IS NULL
+      ${typeClause}
+    ORDER BY events_fts.rank
+    LIMIT ?
+  `;
+  const params = type ? [q, project, type, limit] : [q, project, limit];
+  return db.prepare(sql).all(...params);
+}
+
+/**
+ * Most recent N events for a project (excluding superseded).
+ * Uses idx_events_project_created (T6.1) — index-only sort, no temp B-tree.
+ */
+export function recentEvents(db, { project, type = null, limit = 20 } = {}) {
+  const typeClause = type ? 'AND event_type = ?' : '';
+  const sql = `
+    SELECT * FROM events
+    WHERE project = ? AND superseded_at_epoch IS NULL ${typeClause}
+    ORDER BY created_at_epoch DESC
+    LIMIT ?
+  `;
+  const params = type ? [project, type, limit] : [project, limit];
+  return db.prepare(sql).all(...params);
+}

package/lib/doctor-benchmark.mjs

@@ -0,0 +1,153 @@
+// Baseline benchmark capture for v2.31 MVP.
+// Measures (bounded scope):
+//   - L2 MCP instructions byte count (cost-per-turn source).
+//   - Count of registered MCP tool schemas.
+//   - Hook execution latency p50/p99 by replaying a prompt fixture.
+//   - Hook injection rate (fraction of prompts that would inject non-empty output).
+//
+// This is a *static* analyzer plus a DB-driven simulator — it does not spawn
+// the MCP server or the hook process. See docs/plans/2026-04-14-mem-v2.31-mvp.md
+// (Task 1). Out of scope: prompt cache hit/miss.
+
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { sanitizeFtsQuery, OBS_BM25 } from '../utils.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SERVER_PATH = join(__dirname, '..', 'server.mjs');
+const SERVER_INTERNALS_PATH = join(__dirname, '..', 'server-internals.mjs');
+const BENCHMARK_VERSION = '1';
+
+function extractStringArrayBody(body) {
+  const parts = [];
+  const re = /(['"])((?:\\.|(?!\1).)*)\1/g;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    const unescaped = m[2]
+      .replace(/\\n/g, '\n')
+      .replace(/\\'/g, "'")
+      .replace(/\\"/g, '"')
+      .replace(/\\\\/g, '\\');
+    parts.push(unescaped);
+  }
+  return parts;
+}
+
+/**
+ * Extract the string body of the MCP `instructions:` field.
+ * Supports three forms:
+ *   1. template literal in server.mjs:  instructions: `...`
+ *   2. array-join in server.mjs:        instructions: [ '...', '...' ].join('\n')
+ *   3. (v2.31.3+) builder call in server.mjs referencing INSTRUCTIONS_BASE +
+ *      INSTRUCTIONS_VERBOSE arrays in server-internals.mjs. Measured at the
+ *      verbose form — this is the cost-per-turn baseline the benchmark tracks.
+ * Returns '' if no shape matches (caller treats byte count as 0).
+ */
+function readMcpInstructions() {
+  const src = readFileSync(SERVER_PATH, 'utf8');
+
+  // Form 1: template literal
+  const tmpl = src.match(/instructions:\s*`([\s\S]*?)`/);
+  if (tmpl) return tmpl[1];
+
+  // Form 2: string array + .join(...)
+  const arr = src.match(/instructions:\s*\[([\s\S]*?)\]\s*\.join\(/);
+  if (arr) return extractStringArrayBody(arr[1]).join('\n');
+
+  // Form 3: buildServerInstructions() — reconstruct verbose form from
+  // server-internals.mjs INSTRUCTIONS_BASE + INSTRUCTIONS_VERBOSE arrays.
+  if (/instructions:\s*buildServerInstructions\(/.test(src)) {
+    let internals;
+    try { internals = readFileSync(SERVER_INTERNALS_PATH, 'utf8'); } catch { return ''; }
+    const base = internals.match(/INSTRUCTIONS_BASE\s*=\s*\[([\s\S]*?)\];/);
+    const verbose = internals.match(/INSTRUCTIONS_VERBOSE\s*=\s*\[([\s\S]*?)\];/);
+    const parts = [];
+    if (base) parts.push(...extractStringArrayBody(base[1]));
+    if (verbose) parts.push(...extractStringArrayBody(verbose[1]));
+    return parts.join('\n');
+  }
+
+  return '';
+}
+
+function countMcpTools() {
+  const src = readFileSync(SERVER_PATH, 'utf8');
+  return (src.match(/server\.registerTool\(/g) || []).length;
+}
+
+function percentile(sortedAsc, p) {
+  if (sortedAsc.length === 0) return null;
+  const idx = Math.min(sortedAsc.length - 1, Math.floor(sortedAsc.length * p));
+  return sortedAsc[idx];
+}
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {{prompts?: string[], project?: string, skipHookLatency?: boolean}} options
+ */
+export function runBenchmark(db, { prompts = [], project = 'mem', skipHookLatency = false } = {}) {
+  const instructions = readMcpInstructions();
+  const mcp_instructions_bytes = Buffer.byteLength(instructions, 'utf8');
+  const mcp_tool_count = countMcpTools();
+
+  // Prepare the injection probe once; reused across the rate loop and the
+  // latency loop. Re-preparing per iteration would inflate p50/p99 by the
+  // prepare-overhead, masking real hook latency.
+  const injectionStmt = db.prepare(`
+    SELECT ${OBS_BM25} AS score
+    FROM observations_fts
+    JOIN observations o ON o.id = observations_fts.rowid
+    WHERE observations_fts MATCH ? AND o.project = ?
+    ORDER BY score LIMIT 1
+  `);
+
+  /**
+   * Simulate the memory-inject hook for one prompt:
+   *   - trim-and-length guard (mirrors hook-memory.mjs minimum-length heuristic)
+   *   - sanitize as FTS query
+   *   - BM25-ranked lookup over observations_fts, filtered by project
+   * Returns true iff the simulator would produce a non-empty injection.
+   */
+  const runInjection = (promptText) => {
+    if (!promptText || promptText.trim().length < 15) return false;
+    const q = sanitizeFtsQuery(promptText);
+    if (!q) return false;
+    try {
+      return !!injectionStmt.get(q, project);
+    } catch {
+      // Malformed query slipped past sanitize → treat as no injection.
+      return false;
+    }
+  };
+
+  let injected = 0;
+  for (const p of prompts) {
+    if (runInjection(p)) injected++;
+  }
+  const injection_rate = prompts.length > 0 ? injected / prompts.length : 0;
+
+  let hook_p50_ms = null;
+  let hook_p99_ms = null;
+  if (!skipHookLatency && prompts.length > 0) {
+    const latencies = [];
+    for (const p of prompts) {
+      const t0 = performance.now();
+      runInjection(p);
+      latencies.push(performance.now() - t0);
+    }
+    latencies.sort((a, b) => a - b);
+    hook_p50_ms = percentile(latencies, 0.5);
+    hook_p99_ms = percentile(latencies, 0.99);
+  }
+
+  return {
+    version: BENCHMARK_VERSION,
+    mcp_tool_count,
+    mcp_instructions_bytes,
+    prompt_count: prompts.length,
+    injection_rate,
+    hook_p50_ms,
+    hook_p99_ms,
+  };
+}

package/lib/git-state.mjs

@@ -0,0 +1,38 @@
+// lib/git-state.mjs — thin wrapper around git status/stash/HEAD sha (T10b).
+// Used by startup-dashboard (T10c) and continuation-anchor detection (T10d).
+// All calls are timeout-bounded; any failure yields empty fields, never throws.
+
+import { execFileSync } from 'child_process';
+
+const GIT_TIMEOUT_MS = 1500;
+
+function run(cmd, args, { cwd } = {}) {
+  try {
+    return execFileSync(cmd, args, {
+      cwd,
+      encoding: 'utf8',
+      timeout: GIT_TIMEOUT_MS,
+      // Suppress git's own stderr noise (e.g. "fatal: not a git repository").
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Return a compact snapshot of git state. Safe on non-git directories.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd=process.cwd()]
+ * @returns {{changed: string[], stashes: string[], branch: string|null, headSha: string|null}}
+ */
+export function readGitState({ cwd = process.cwd() } = {}) {
+  const statusOut = run('git', ['status', '--porcelain'], { cwd });
+  const changed = statusOut ? statusOut.split('\n').filter(Boolean) : [];
+  const stashOut = run('git', ['stash', 'list'], { cwd });
+  const stashes = stashOut ? stashOut.split('\n').filter(Boolean) : [];
+  const branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd }) || null;
+  const headSha = run('git', ['rev-parse', 'HEAD'], { cwd }) || null;
+  return { changed, stashes, branch, headSha };
+}

package/lib/plan-reader.mjs

@@ -0,0 +1,43 @@
+// lib/plan-reader.mjs — list recent plan files under ~/.claude/plans/ (T10b).
+// For startup-dashboard (T10c); pure function; silent on I/O errors.
+//
+// Real schema observed in Claude Code ~/.claude/plans/ (2026-04):
+//   Flat directory of *.md files at root level. No nesting by project.
+//   Example: `imperative-baking-hamster.md`, `zippy-frolicking-liskov.md`.
+
+import { readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const DEFAULT_PLANS_ROOT = join(homedir(), '.claude', 'plans');
+
+/**
+ * Return up to `limit` most recently modified .md plan files.
+ *
+ * @param {object} [options]
+ * @param {string} [options.plansRoot=~/.claude/plans] - Override root (testing).
+ * @param {number} [options.limit=5]
+ * @returns {Array<{name:string, path:string, mtime:number}>} name is the basename without .md
+ */
+export function recentPlans({ plansRoot = DEFAULT_PLANS_ROOT, limit = 5 } = {}) {
+  let files;
+  try {
+    files = readdirSync(plansRoot);
+  } catch {
+    return [];
+  }
+  return files
+    .filter(f => f.endsWith('.md'))
+    .map(f => {
+      let mtime = 0;
+      try {
+        mtime = statSync(join(plansRoot, f)).mtimeMs;
+      } catch {
+        // Race: file vanished between readdir and stat. Keep entry with mtime=0
+        // so it sorts last; caller sees a stable name at worst.
+      }
+      return { name: f.replace(/\.md$/, ''), path: join(plansRoot, f), mtime };
+    })
+    .sort((a, b) => b.mtime - a.mtime)
+    .slice(0, limit);
+}

package/lib/startup-dashboard.mjs

@@ -0,0 +1,113 @@
+// lib/startup-dashboard.mjs — aggregates git/tasks/plans/handoff/events stats
+// into a single SessionStart injection line (T10c v2.31).
+//
+// Pure function (with injectable stubs for test determinism). Never throws:
+// every external reader is try/catch'd so a broken git repo, missing tasks dir,
+// or absent events table cannot break SessionStart.
+
+import { readGitState } from './git-state.mjs';
+import { readProjectTasks } from './task-reader.mjs';
+import { recentPlans } from './plan-reader.mjs';
+import { isAdoptedHere } from '../hook-shared.mjs';
+
+function ageStr(ms) {
+  const diff = Date.now() - ms;
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  return `${Math.floor(hrs / 24)}d ago`;
+}
+
+function readRecentHandoff(db, project) {
+  try {
+    return db.prepare(`
+      SELECT created_at_epoch, working_on FROM session_handoffs
+      WHERE project = ? AND type = 'exit'
+      ORDER BY created_at_epoch DESC LIMIT 1
+    `).get(project);
+  } catch { return null; }
+}
+
+/**
+ * Build the dashboard injection string, or empty string when all sources empty.
+ *
+ * @param {object} options
+ * @param {object} options.db - better-sqlite3 handle. May be null.
+ * @param {string} options.project - project identifier used for handoff/events queries.
+ * @param {string} [options.projectPath=process.cwd()] - filesystem root for git + tasks.
+ * @param {object} [options.stubs] - per-field test injectors:
+ *        {git?, tasks?, plans?, handoff?}. handoff: pass explicit null to skip;
+ *        omit to fall through to DB query.
+ * @returns {string} rendered dashboard or '' if no content.
+ */
+export function buildDashboard({ db, project, projectPath = process.cwd(), stubs = null } = {}) {
+  const git     = stubs?.git     ?? readGitState({ cwd: projectPath });
+  const tasks   = stubs?.tasks   ?? readProjectTasks({ projectPath });
+  const plans   = stubs?.plans   ?? recentPlans({ limit: 3 });
+  // stubs.handoff === null means "test asserted no handoff"; undefined means "query DB".
+  const handoff = stubs && 'handoff' in stubs ? stubs.handoff : readRecentHandoff(db, project);
+
+  let eventCount = 0;
+  try {
+    eventCount = db?.prepare(`SELECT COUNT(*) c FROM events WHERE project = ?`).get(project)?.c ?? 0;
+  } catch { /* events table may not exist on very old DBs */ }
+
+  const parts = [];
+
+  if ((git?.changed?.length ?? 0) > 0 || (git?.stashes?.length ?? 0) > 0) {
+    parts.push('📊 Git:');
+    if (git.changed.length > 0) {
+      parts.push(`  - ${git.changed.length} uncommitted file(s) on ${git.branch || 'HEAD'}`);
+    }
+    if (git.stashes.length > 0) {
+      parts.push(`  - ${git.stashes.length} stash(es)`);
+    }
+  }
+
+  if (tasks.length > 0) {
+    parts.push('📋 Active tasks:');
+    for (const t of tasks.slice(0, 3)) {
+      parts.push(`  - [${t.status}] ${t.title}`);
+    }
+    if (tasks.length > 3) parts.push(`  - (… +${tasks.length - 3} more)`);
+  }
+
+  if (plans.length > 0) {
+    parts.push('📝 Recent plans:');
+    for (const p of plans.slice(0, 2)) {
+      parts.push(`  - ${p.name} (${ageStr(p.mtime)})`);
+    }
+  }
+
+  if (handoff) {
+    parts.push(`🔄 Continuation (/exit ${ageStr(handoff.created_at_epoch)}):`);
+    if (handoff.working_on) {
+      parts.push(`  - Working on: ${handoff.working_on.slice(0, 160)}`);
+    }
+  }
+
+  if (eventCount > 0) {
+    parts.push(`💡 mem events: ${eventCount} entries (\`claude-mem-lite activity recent\`)`);
+  }
+
+  // Invited-memory hint (Phase F): persists every SessionStart until the user
+  // adopts. Self-clearing — once the sentinel exists, isAdoptedHere() flips to
+  // true and this line silently drops. MEM_NO_ADOPT_HINT=1 opts out permanently
+  // for users who prefer the verbose hook layer.
+  const adoptHint = buildAdoptHint({ projectPath, stubs });
+  if (adoptHint) parts.push(adoptHint);
+
+  if (parts.length === 0) return '';
+  return `[mem] Startup dashboard:\n${parts.join('\n')}`;
+}
+
+function buildAdoptHint({ projectPath, stubs }) {
+  if (process.env.MEM_NO_ADOPT_HINT === '1') return null;
+  if (process.env.MEM_QUIET_HOOKS === '1') return null;
+  // stubs.adopted === true/false lets tests assert both branches without touching FS.
+  const adopted = stubs && 'adopted' in stubs ? stubs.adopted : isAdoptedHere(projectPath);
+  if (adopted) return null;
+  return '🧷 Invited-memory 未启用：`claude-mem-lite adopt` 注入 MEMORY.md → 上下文省 ~40%，MCP 调用率提升；静音 `MEM_NO_ADOPT_HINT=1`';
+}