claude-mem-lite 2.31.2 → 2.32.2

package/lib/task-reader.mjs

@@ -0,0 +1,149 @@
+// lib/task-reader.mjs — parse ~/.claude/tasks/<taskListId>/*.json for startup dashboard (T10a).
+//
+// Pure function over the filesystem. Filters to pending + in_progress tasks for a given project.
+// Never throws — hooks must not break Claude Code. All I/O errors (ENOENT, permission denied,
+// malformed JSON, races between readdir/stat) are silently skipped.
+//
+// Real schema observed in Claude Code ~/.claude/tasks/ (2026-04):
+//   - No `meta.json` files exist. Task dirs contain only `<taskId>.json` + hidden
+//     `.lock` / `.highwatermark` files.
+//   - Tasks use fields: `id`, `subject`, `activeForm`, `description`, `status`,
+//     `blocks`, `blockedBy`. Statuses: pending | in_progress | completed.
+//   - Project → taskListId mapping lives at `~/.claude/projects/<mangled>/<taskListId>/`
+//     where mangling = replace `/` with `-`.
+//
+// The v2.31 plan's fixture assumed a `meta.json`-based shape that is not how Claude Code
+// actually organises tasks. This reader supports BOTH shapes so tests (which use meta.json
+// per the plan) and runtime (which uses projectsRoot probing) both work:
+//
+//   Priority 1 — fixture / future-proof: if `<dir>/meta.json` exists and contains
+//                `projectPath`, use it for project filtering.
+//   Priority 2 — real Claude Code: if `projectsRoot/<mangled>/<taskListId>/` exists,
+//                the task list belongs to `projectPath`.
+//   Priority 3 — no `projectPath` filter supplied: include all tasks.
+//
+// Normalized output uses `title` (falls back to `subject` → `'(untitled)'`) so T10c has
+// a single contract regardless of source shape.
+
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const DEFAULT_TASKS_ROOT = join(homedir(), '.claude', 'tasks');
+const DEFAULT_PROJECTS_ROOT = join(homedir(), '.claude', 'projects');
+const ACTIVE_STATUSES = new Set(['pending', 'in_progress']);
+
+/**
+ * Replace every non-alphanumeric character with `-`, mirroring Claude Code's
+ * `~/.claude/projects/<mangled>/` naming convention.
+ *
+ * Evidence from `~/.claude/projects/` listing (verified 2026-04):
+ *   /mnt/data_ssd/dev/projects/mem     → -mnt-data-ssd-dev-projects-mem     (`/` and `_` → `-`)
+ *   /home/sds/.claude/plugins/...      → -home-sds--claude-plugins-...      (leading `.` → `-`, so `/.` → `--`)
+ *   /mnt/data/hdd/project / /agent     → -mnt-data-hdd-project---agent      (spaces/slashes → `-`)
+ *
+ * @param {string} p - Absolute project path.
+ * @returns {string} Mangled form suitable for `~/.claude/projects/<mangled>/`.
+ */
+function manglePath(p) {
+  return String(p).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+/**
+ * Read active tasks (pending + in_progress) across all task lists that belong to a given
+ * project. Output is sorted by mtime DESC and capped at `maxTasks`.
+ *
+ * @param {object} [options]
+ * @param {string} [options.tasksRoot=~/.claude/tasks] - Override tasks root (testing).
+ * @param {string} [options.projectsRoot=~/.claude/projects] - Override projects root (testing).
+ * @param {string} [options.projectPath] - Absolute project path to filter by. When undefined,
+ *                                         returns tasks from every task list encountered.
+ * @param {number} [options.maxTasks=20] - Cap on returned tasks.
+ * @returns {Array<{id:string,title:string,status:string,taskListId:string,mtime:number}>}
+ */
+export function readProjectTasks({
+  tasksRoot = DEFAULT_TASKS_ROOT,
+  projectsRoot = DEFAULT_PROJECTS_ROOT,
+  projectPath,
+  maxTasks = 20,
+} = {}) {
+  let listIds;
+  try {
+    listIds = readdirSync(tasksRoot);
+  } catch {
+    return [];
+  }
+
+  // Pre-compute the set of taskListIds registered under the project via projectsRoot
+  // (real Claude Code layout). Used as a fallback when meta.json is absent.
+  let projectListIds = null;
+  if (projectPath) {
+    try {
+      const mangled = manglePath(projectPath);
+      projectListIds = new Set(readdirSync(join(projectsRoot, mangled)));
+    } catch {
+      projectListIds = new Set();
+    }
+  }
+
+  const out = [];
+  outer: for (const id of listIds) {
+    const dir = join(tasksRoot, id);
+
+    // Project filter: meta.json (priority 1) → projectsRoot probe (priority 2) → all.
+    if (projectPath) {
+      let belongs;
+      try {
+        const meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf8'));
+        belongs = meta && meta.projectPath === projectPath;
+      } catch {
+        // No meta.json (or malformed) — fall back to real Claude Code layout.
+        belongs = projectListIds.has(id);
+      }
+      if (!belongs) continue;
+    }
+
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+
+    for (const f of entries) {
+      // Skip non-task files: meta.json, hidden .lock / .highwatermark, non-JSON.
+      if (f === 'meta.json') continue;
+      if (f.startsWith('.')) continue;
+      if (!f.endsWith('.json')) continue;
+
+      const filePath = join(dir, f);
+      let task;
+      try {
+        task = JSON.parse(readFileSync(filePath, 'utf8'));
+      } catch {
+        continue;
+      }
+      if (!task || !ACTIVE_STATUSES.has(task.status)) continue;
+
+      let mtime;
+      try {
+        mtime = statSync(filePath).mtimeMs;
+      } catch {
+        // Race: file disappeared between readdir and stat. Skip silently.
+        continue;
+      }
+
+      out.push({
+        id: task.id || f.replace(/\.json$/, ''),
+        // Normalize: plan's `title` → real Claude Code's `subject` → fallback literal.
+        title: task.title || task.subject || '(untitled)',
+        status: task.status,
+        taskListId: id,
+        mtime,
+      });
+      if (out.length >= maxTasks) break outer;
+    }
+  }
+
+  return out.sort((a, b) => b.mtime - a.mtime);
+}

package/mem-cli.mjs

@@ -14,6 +14,7 @@ import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { optimizePreview, optimizeRun } from './hook-optimize.mjs';
 import { buildSessionContextLines } from './hook-context.mjs';
+import { cmdAdopt, cmdUnadopt } from './adopt-cli.mjs';
 import { basename } from 'path';
 import { readFileSync } from 'fs';
 
@@ -2058,6 +2059,17 @@ Commands:
     --files (plural, comma-split) preferred; --file (singular) kept for back-compat.
     Use /lesson or /bug slash commands for faster capture (T8).
 
+  adopt                 Inject claude-mem-lite sentinel line into this project's
+                        ~/.claude/projects/<encoded>/memory/MEMORY.md so Claude Code
+                        auto-loads it as user-memory (higher instruction authority).
+    --all               Adopt every project under ~/.claude/projects/*/memory/
+    --force             Overwrite a sentinel block that was manually edited
+    --dry-run           Print intended writes without touching disk
+    --status            List adopted projects + version
+
+  unadopt               Precise removal of the sentinel block + plugin_claude_mem_lite.md.
+    --all               Unadopt every project
+
 DB: ${DB_PATH}`);
 }
 
@@ -2336,6 +2348,11 @@ export async function run(argv) {
     return;
   }
 
+  // adopt / unadopt do pure filesystem work on ~/.claude/projects/<encoded>/memory/ —
+  // no DB needed. Route them before ensureDb() so an unbootable DB doesn't block.
+  if (cmd === 'adopt') { cmdAdopt(cmdArgs); return; }
+  if (cmd === 'unadopt') { cmdUnadopt(cmdArgs); return; }
+
   let db;
   try {
     db = ensureDb();

package/memdir.mjs

@@ -0,0 +1,252 @@
+// Phase B (Invited-Memory plan): memdir.mjs — primitives for the per-project
+// Claude Code memdir at ~/.claude/projects/<encoded>/memory/.
+//
+// The public API lets a plugin install a single sentinel-wrapped line into
+// MEMORY.md (auto-loaded by Claude Code into the system prompt) plus an
+// on-demand `plugin_<slug>.md` detail file. Writes are idempotent, hash-guarded
+// against manual user edits, and capped by a 180-line budget so the injection
+// block never gets truncated by Claude Code's 200-line MEMORY.md cap.
+//
+// See docs/plans/2026-04-16-invited-memory-pattern.md for rationale.
+
+import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { createHash } from 'crypto';
+
+const MEMORY_LINE_BUDGET = 180;
+const SECTION_HEADER = '## 插件契约';
+
+export class UserEditedError extends Error {
+  constructor(message) { super(message); this.name = 'UserEditedError'; }
+}
+
+export class BudgetExceededError extends Error {
+  constructor(message) { super(message); this.name = 'BudgetExceededError'; }
+}
+
+// ─── Path helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Mirror Claude Code's project-path encoding: every non-alphanumeric char
+ * is replaced with "-". Lossy by design — the encoded path is a directory
+ * slug, not a reversible encoding. Ground truth fixture:
+ *   /mnt/data_ssd/dev/projects/mem → -mnt-data-ssd-dev-projects-mem
+ * Memory ref: #7687 ("Claude Code mangles EVERY non-alphanumeric char").
+ */
+export function encodeProjectPath(absPath) {
+  return String(absPath).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+/**
+ * Absolute path to the project's memdir. Caller runs mkdir-p as needed.
+ */
+export function memdirPath(projectCwd) {
+  return join(homedir(), '.claude', 'projects', encodeProjectPath(projectCwd), 'memory');
+}
+
+function memoryFile(memdir) { return join(memdir, 'MEMORY.md'); }
+
+function slugSnake(slug) {
+  return String(slug).replace(/[^a-zA-Z0-9]/g, '_');
+}
+
+function docFile(memdir, slug) {
+  return join(memdir, `plugin_${slugSnake(slug)}.md`);
+}
+
+function stateFile(memdir, slug) {
+  return join(memdir, `.plugin_${slugSnake(slug)}_state.json`);
+}
+
+// ─── Sentinel rendering & parsing ────────────────────────────────────────────
+
+function sentinelRegex(slug) {
+  // Escape regex metacharacters in the slug. In practice plugin slugs are
+  // [a-z0-9-], but guard against '.', '+' etc. from arbitrary other plugins.
+  const esc = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(
+    `<!-- ${esc}:begin (v\\d+) -->\\s*\\n([\\s\\S]*?)<!-- ${esc}:end -->`,
+  );
+}
+
+function renderSentinel(slug, version, contentLine) {
+  return [
+    `<!-- ${slug}:begin ${version} -->`,
+    SECTION_HEADER,
+    contentLine,
+    `<!-- ${slug}:end -->`,
+  ].join('\n');
+}
+
+function canonicalBody(contentLine) {
+  // Must match what sentinelRegex captures in match[2]: everything between
+  // "begin X -->\n" and "<!-- X:end -->". That's SECTION_HEADER + '\n' +
+  // contentLine + '\n'.
+  return `${SECTION_HEADER}\n${contentLine}\n`;
+}
+
+function sha256(s) { return createHash('sha256').update(s).digest('hex'); }
+
+function atomicWrite(path, content) {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+function readState(memdir, slug) {
+  const p = stateFile(memdir, slug);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+function writeState(memdir, slug, state) {
+  atomicWrite(stateFile(memdir, slug), JSON.stringify(state, null, 2) + '\n');
+}
+
+function clearState(memdir, slug) {
+  const p = stateFile(memdir, slug);
+  if (existsSync(p)) try { unlinkSync(p); } catch { /* best-effort */ }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Parse MEMORY.md for the plugin's sentinel block.
+ * @returns {{ exists: boolean, raw: string, lineCount: number,
+ *   section: string|null, body: string|null, version: string|null }}
+ */
+export function readMemoryIndex(memdir, slug) {
+  const path = memoryFile(memdir);
+  if (!existsSync(path)) {
+    return { exists: false, raw: '', lineCount: 0, section: null, body: null, version: null };
+  }
+  const raw = readFileSync(path, 'utf8');
+  const m = raw.match(sentinelRegex(slug));
+  const lineCount = raw.length === 0 ? 0 : raw.split('\n').length;
+  if (!m) return { exists: true, raw, lineCount, section: null, body: null, version: null };
+  return { exists: true, raw, lineCount, section: m[0], body: m[2], version: m[1] };
+}
+
+/**
+ * Insert-or-update the plugin's sentinel block in MEMORY.md, writing a
+ * state sidecar alongside it.
+ *
+ * Idempotent: rewriting identical inputs is a no-op (returns action='unchanged').
+ *
+ * @param {string} memdir Absolute path to the memory directory.
+ * @param {object} opts
+ * @param {string} opts.slug Plugin slug (e.g. 'claude-mem-lite').
+ * @param {string} opts.version Contract version, e.g. 'v1'.
+ * @param {string} opts.contentLine Single-line index entry (≤150 chars).
+ * @param {boolean} [opts.force=false] Override UserEditedError.
+ * @returns {{action: 'created'|'updated'|'unchanged'}}
+ *
+ * @throws {BudgetExceededError} when MEMORY.md has > 180 lines AND we'd be
+ *   adding a new section (updates to an existing sentinel are always allowed).
+ * @throws {UserEditedError} when the sentinel exists but its body hash doesn't
+ *   match the last hash we wrote (detected via the state sidecar). Also thrown
+ *   when a sentinel exists without any state file — treated as foreign content.
+ */
+export function writePluginSection(memdir, { slug, version, contentLine, force = false }) {
+  if (!existsSync(memdir)) mkdirSync(memdir, { recursive: true });
+  const path = memoryFile(memdir);
+  const raw = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const match = raw.match(sentinelRegex(slug));
+
+  const freshSection = renderSentinel(slug, version, contentLine);
+  const freshHash = sha256(canonicalBody(contentLine));
+
+  if (!match) {
+    // Insert: enforce the 180-line budget so we never get truncated at 200.
+    const existingLines = raw.length === 0 ? 0 : raw.split('\n').length;
+    if (existingLines > MEMORY_LINE_BUDGET) {
+      throw new BudgetExceededError(
+        `MEMORY.md has ${existingLines} lines (> ${MEMORY_LINE_BUDGET}); refuse to add new sentinel section for ${slug}.`,
+      );
+    }
+    // Assemble with one blank line before our section for readability.
+    let next;
+    if (raw.length === 0) {
+      next = freshSection + '\n';
+    } else if (raw.endsWith('\n\n')) {
+      next = raw + freshSection + '\n';
+    } else if (raw.endsWith('\n')) {
+      next = raw + '\n' + freshSection + '\n';
+    } else {
+      next = raw + '\n\n' + freshSection + '\n';
+    }
+    atomicWrite(path, next);
+    writeState(memdir, slug, { version, bodyHash: freshHash, writtenAt: new Date().toISOString() });
+    return { action: 'created' };
+  }
+
+  // Update path: hash-guard against user edits via state sidecar.
+  if (!force) {
+    const state = readState(memdir, slug);
+    if (!state) {
+      throw new UserEditedError(
+        `${slug} sentinel found without plugin state file — treating as foreign content. Pass force=true to re-adopt.`,
+      );
+    }
+    const currentHash = sha256(match[2]);
+    if (state.bodyHash !== currentHash) {
+      throw new UserEditedError(
+        `${slug} sentinel body was modified since last write (hash mismatch). Pass force=true to overwrite.`,
+      );
+    }
+  }
+
+  const next = raw.replace(match[0], freshSection);
+  const changed = next !== raw;
+  if (changed) atomicWrite(path, next);
+  writeState(memdir, slug, { version, bodyHash: freshHash, writtenAt: new Date().toISOString() });
+  return { action: changed ? 'updated' : 'unchanged' };
+}
+
+/**
+ * Remove the plugin's sentinel block plus its state sidecar. External content
+ * in MEMORY.md is preserved.
+ * @returns {{action: 'removed'|'absent'}}
+ */
+export function removePluginSection(memdir, slug) {
+  clearState(memdir, slug);
+  const path = memoryFile(memdir);
+  if (!existsSync(path)) return { action: 'absent' };
+  const raw = readFileSync(path, 'utf8');
+  const match = raw.match(sentinelRegex(slug));
+  if (!match) return { action: 'absent' };
+
+  // Delete the match plus a trailing newline + a preceding blank line so we
+  // don't leave a stranded paragraph gap.
+  let start = match.index;
+  let end = match.index + match[0].length;
+  if (raw[end] === '\n') end++;
+  if (start > 0 && raw.slice(0, start).endsWith('\n\n')) start--;
+  const next = raw.slice(0, start) + raw.slice(end);
+  atomicWrite(path, next);
+  return { action: 'removed' };
+}
+
+/**
+ * Whether this memdir has our sentinel. Body edits don't demote the adoption —
+ * users who hand-tweak the contract line still count as adopted.
+ */
+export function isAdopted(memdir, slug) {
+  if (!existsSync(memdir)) return false;
+  const { section } = readMemoryIndex(memdir, slug);
+  return section !== null;
+}
+
+// ─── Plugin detail doc IO ────────────────────────────────────────────────────
+
+export function writePluginDoc(memdir, slug, markdown) {
+  if (!existsSync(memdir)) mkdirSync(memdir, { recursive: true });
+  atomicWrite(docFile(memdir, slug), markdown);
+}
+
+export function removePluginDoc(memdir, slug) {
+  const path = docFile(memdir, slug);
+  if (!existsSync(path)) return;
+  try { unlinkSync(path); } catch { /* best-effort */ }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.31.2",
+  "version": "2.32.2",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -35,7 +35,18 @@
     "hook-context.mjs",
     "hook-handoff.mjs",
     "hook-update.mjs",
+    "hook-optimize.mjs",
+    "plugin-cache-guard.mjs",
+    "memdir.mjs",
+    "adopt-content.mjs",
+    "adopt-cli.mjs",
     "haiku-client.mjs",
+    "lib/activity.mjs",
+    "lib/git-state.mjs",
+    "lib/task-reader.mjs",
+    "lib/plan-reader.mjs",
+    "lib/startup-dashboard.mjs",
+    "lib/doctor-benchmark.mjs",
     "registry.mjs",
     "registry-retriever.mjs",
     "registry-indexer.mjs",
@@ -66,6 +77,10 @@
     "commands/memory.md",
     "commands/update.md",
     "commands/tools.md",
+    "commands/adopt.md",
+    "commands/unadopt.md",
+    "commands/lesson.md",
+    "commands/bug.md",
     "hooks/hooks.json",
     "scripts/launch.mjs",
     "scripts/setup.sh",
@@ -85,6 +100,9 @@
     "better-sqlite3": "^12.6.2",
     "zod": "^4.3.6"
   },
+  "overrides": {
+    "hono": ">=4.12.14"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.0.18",

package/plugin-cache-guard.mjs

@@ -0,0 +1,77 @@
+// Plugin cache hook sentinel.
+//
+// Claude Code runtime reads plugin hooks from
+// ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/hooks/hooks.json
+// NOT from the marketplace source (~/.claude/plugins/marketplaces/<mp>/hooks/hooks.json).
+//
+// When install.mjs writes mem hooks directly into ~/.claude/settings.json, any stale
+// cache hooks.json (e.g. left behind by a previous marketplace install or an auto-update
+// that re-populates cache) causes double hook registration: one fires from settings.json,
+// another from cache. This module detects and heals that state.
+//
+// Safe-by-default: clearPluginCacheHooks is only called when hasInstallManagedHooks()
+// returns true, so plugin-only users (cache is the sole registration) are not affected.
+
+import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export const DEFAULT_MARKETPLACE = 'sdsrss';
+export const DEFAULT_PLUGIN = 'claude-mem-lite';
+
+function cacheBaseFor(opts) {
+  const home = opts?.home || homedir();
+  const mp = opts?.marketplace || DEFAULT_MARKETPLACE;
+  const plugin = opts?.plugin || DEFAULT_PLUGIN;
+  return join(home, '.claude', 'plugins', 'cache', mp, plugin);
+}
+
+export function scanPluginCacheHookPollution(opts) {
+  const base = cacheBaseFor(opts);
+  if (!existsSync(base)) return [];
+  const polluted = [];
+  for (const ver of readdirSync(base)) {
+    const p = join(base, ver, 'hooks', 'hooks.json');
+    if (!existsSync(p)) continue;
+    try {
+      const h = JSON.parse(readFileSync(p, 'utf8'));
+      if (h.hooks && Object.keys(h.hooks).length > 0) polluted.push(ver);
+    } catch { /* ignore unreadable cache entries */ }
+  }
+  return polluted.sort();
+}
+
+export function clearPluginCacheHooks(opts) {
+  const base = cacheBaseFor(opts);
+  if (!existsSync(base)) return [];
+  const plugin = opts?.plugin || DEFAULT_PLUGIN;
+  const reason = opts?.reason || 'Auto-cleared to prevent duplicate hook registration';
+  const cleared = [];
+  for (const ver of readdirSync(base)) {
+    const p = join(base, ver, 'hooks', 'hooks.json');
+    if (!existsSync(p)) continue;
+    try {
+      const h = JSON.parse(readFileSync(p, 'utf8'));
+      if (!h.hooks || Object.keys(h.hooks).length === 0) continue;
+      writeFileSync(p, JSON.stringify({
+        description: h.description || `${plugin} hooks`,
+        _note: `${reason} (cache ver: ${ver})`,
+        hooks: {},
+      }, null, 2) + '\n');
+      cleared.push(ver);
+    } catch { /* ignore unwritable cache entries */ }
+  }
+  return cleared.sort();
+}
+
+export function hasInstallManagedHooks(opts) {
+  const home = opts?.home || homedir();
+  const plugin = opts?.plugin || DEFAULT_PLUGIN;
+  const settingsPath = join(home, '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) return false;
+  try {
+    const s = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const serialized = JSON.stringify(s.hooks || {});
+    return serialized.includes(`.${plugin}/`) || serialized.includes(`/${plugin}/`);
+  } catch { return false; }
+}

package/scripts/user-prompt-search.js

@@ -167,6 +167,10 @@ function readStdin() {
 
 // ─── Format Output ──────────────────────────────────────────────────────────
 
+// Phase A (v2.31.3+): drop lesson suffix when MEM_QUIET_HOOKS=1; users on invited-memory
+// path can mem_get the ID for full detail.
+const QUIET_HOOKS = process.env.MEM_QUIET_HOOKS === '1';
+
 function formatResults(rows) {
   if (!rows || rows.length === 0) return null;
 
@@ -174,7 +178,7 @@ function formatResults(rows) {
   for (const r of rows) {
     const icon = typeIcon(r.type);
     const title = truncate(r.title || '', 70);
-    const lesson = r.lesson_learned ? ` — ${truncate(r.lesson_learned, 50)}` : '';
+    const lesson = !QUIET_HOOKS && r.lesson_learned ? ` — ${truncate(r.lesson_learned, 50)}` : '';
     lines.push(`#${r.id} ${icon} ${title}${lesson}`);
   }
   return lines.join('\n');

package/server-internals.mjs

@@ -5,6 +5,54 @@ import { debugCatch, COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25 } from
 import { BASE_STOP_WORDS } from './stop-words.mjs';
 import { porterStem } from './tfidf.mjs';
 
+// ─── MCP Server Instructions Builder ───────────────────────────────────────
+// Phase A (v2.31.3+): when quiet=true, drops WHEN-TO-USE proactive-trigger and
+// Decision-rules sections; keeps the irreducible CLI/MCP tool list. Intended
+// for users who adopted invited-memory (MEMORY.md sentinel carries the same
+// triggers at higher authority). Default false preserves v2.31.2 behavior.
+
+const INSTRUCTIONS_BASE = [
+  'Long-term memory across sessions. Hooks auto-inject context; CLI preferred for explicit queries.',
+  '',
+  'CLI (via Bash):',
+  '  claude-mem-lite search "query"              — FTS5 full-text search',
+  '  claude-mem-lite search "err" --type bugfix  — filter by type',
+  '  claude-mem-lite recall "file.mjs"           — file-related memories',
+  '  claude-mem-lite recent 5                    — latest observations',
+  '  claude-mem-lite get 42,43                   — full details by ID',
+  '  claude-mem-lite timeline --anchor 42        — chronological context',
+  '',
+  'MCP tools: mem_search, mem_recent, mem_save, mem_get, mem_recall, mem_timeline for programmatic access.',
+  'mem_save: Save non-obvious insights (bugfix lessons, architecture decisions).',
+  'Search tips: short keywords (2-3 words), filter with obs_type when relevant.',
+];
+
+const INSTRUCTIONS_VERBOSE = [
+  '',
+  'WHEN TO USE (proactive triggers during coding):',
+  '  • About to Edit/Write a file → mem_recall(file="path") FIRST — past bugfixes & lessons',
+  '  • Test failure or error → mem_search(query="error keywords", obs_type="bugfix")',
+  '  • Before refactoring → mem_search(query="module-name", obs_type="refactor") for past decisions',
+  '  • Starting new feature → mem_search(query="feature area") for prior art & patterns',
+  '  • After fixing a tricky bug → mem_save(type="bugfix", lesson_learned="root cause & fix")',
+  '  • After architecture decision → mem_save(type="decision", lesson_learned="rationale")',
+  '  • Hook-injected context mentions #ID → mem_get(ids=[ID]) for full details',
+  '',
+  'Decision rules (use INSTEAD OF multi-step search):',
+  '  • "what happened recently?" → mem_recent (NOT search with empty query)',
+  '  • "what do we know about file.mjs?" → mem_recall (NOT grep + manual search)',
+  '  • "show me around observation #42" → mem_timeline (NOT mem_get + manual navigation)',
+  '  • "clean up old/duplicate memories" → mem_maintain (NOT manual mem_delete loop)',
+  '  • "is the search index healthy?" → mem_fts_check (NOT manual COUNT queries)',
+  '  • "overview of memory tiers" → mem_browse (NOT mem_search + manual grouping)',
+  '  • "export for backup" → mem_export (NOT manual SELECT queries)',
+];
+
+export function buildServerInstructions(quiet = false) {
+  if (quiet) return INSTRUCTIONS_BASE.join('\n');
+  return [...INSTRUCTIONS_BASE, ...INSTRUCTIONS_VERBOSE].join('\n');
+}
+
 // ─── Search Re-ranking Helpers ────────────────────────────────────────────
 
 /**