claude-mem-lite 2.33.5 → 2.34.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.33.5",
+      "version": "2.34.1",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.33.5",
+  "version": "2.34.1",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -209,6 +209,15 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 
 ### MCP Tools (used automatically by Claude)
 
+As of v2.34.0, the server registers 17 tools in total but only the 6 **core**
+tools appear in `tools/list`. The 11 **hidden** tools remain callable at the
+protocol layer (`tools/call` by exact name still routes normally); they're
+omitted from the list response so Claude Code sessions don't load 11 extra
+tool schemas at startup. Hidden tools are the maintenance / admin / browser
+surface — reach them through the CLI column in the second table.
+
+**Core (6, exposed to Claude Code)**
+
 | Tool | Description |
 |------|-------------|
 | `mem_search` | FTS5 full-text search with BM25 ranking. Filters by type, project, date range, importance level. |
@@ -217,16 +226,22 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 | `mem_timeline` | Browse observations chronologically around an anchor point. |
 | `mem_get` | Retrieve full details for specific observation IDs (includes importance and related_ids). |
 | `mem_save` | Manually save a memory/observation. |
-| `mem_update` | Update an existing observation in-place. Preserves original ID and references. |
-| `mem_stats` | View statistics: counts, type distribution, top projects, daily activity. |
-| `mem_delete` | Delete observations by ID with preview/confirm workflow. FTS5 cleanup is automatic. |
-| `mem_compress` | Compress old low-value observations into weekly summaries to reduce noise. |
-| `mem_maintain` | Memory maintenance: scan for duplicates/stale/broken items, then execute cleanup/dedup/rebuild_vectors operations. |
-| `mem_export` | Export observations as JSON or JSONL for backup or migration. Filters by project, type, date range. |
-| `mem_fts_check` | Check FTS5 index integrity or rebuild indexes. Use when search results seem wrong or after DB recovery. |
-| `mem_browse` | Tier-grouped memory dashboard. Shows observations organized by memory tier (working/active/archive). |
-| `mem_registry` | Manage resource registry: search for skills/agents by need, list resources, view stats, import/remove tools, reindex. Search results differentiate managed (Read path) vs native (Skill full name) invocation. |
-| `mem_use` | Load a skill or agent from the managed registry by name. Returns full content with portable `~` path for reload via `Read()`. |
+
+**Hidden-but-callable (11, CLI-routed)**
+
+| Tool | CLI equivalent | Notes |
+|------|----------------|-------|
+| `mem_update` | `claude-mem-lite update <id>` | Edit an observation in place. |
+| `mem_stats` | `claude-mem-lite stats` | Counts, type distribution, daily activity. |
+| `mem_delete` | `claude-mem-lite delete <id>` | Preview / confirm workflow, FTS5 cleanup. |
+| `mem_compress` | `claude-mem-lite compress --preview` | Roll up old low-value observations. |
+| `mem_maintain` | `claude-mem-lite maintain --action scan` | dedup / decay / cleanup / rebuild_vectors. |
+| `mem_optimize` | `claude-mem-lite optimize --action preview` | LLM-powered re-enrich / normalize / cluster-merge. |
+| `mem_export` | `claude-mem-lite export` | JSON / JSONL dump, filters by project, type, date. |
+| `mem_fts_check` | `claude-mem-lite fts-check [--rebuild]` | FTS5 integrity + rebuild. |
+| `mem_browse` | `claude-mem-lite browse` | Tier-grouped dashboard (working / active / archive). |
+| `mem_registry` | `claude-mem-lite registry <action>` | List / search / import / remove skills + agents. |
+| `mem_use` | _MCP only_ | Load a skill / agent from the registry by name. |
 
 ### Skill Commands (in Claude Code chat)
 
@@ -399,7 +414,7 @@ Stop
 
 ### Resource Registry
 
-The resource registry (`registry.mjs`, `registry-retriever.mjs`) indexes installed skills and agents into a searchable FTS5 database. Unlike the previous proactive dispatch system, the registry is now on-demand — Claude searches it via the `mem_registry` MCP tool when it needs to discover relevant skills or agents.
+The resource registry (`registry.mjs`, `registry-retriever.mjs`) indexes installed skills and agents into a searchable FTS5 database. Unlike the previous proactive dispatch system, the registry is now on-demand — it's reachable via the `claude-mem-lite registry` CLI (primary path for Claude Code since v2.34.0 hides the `mem_registry` MCP tool from `tools/list`) or by direct `tools/call mem_registry` for MCP clients that know the name.
 
 ```
 Registry pipeline:

package/README.zh-CN.md

@@ -194,7 +194,14 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 
 ## 使用方法
 
-### MCP 工具（由 Claude 自动使用）
+### MCP 工具
+
+v2.34.0 起服务端注册 17 个工具，但 `tools/list` 只暴露 6 个 **核心** 工具；其余
+11 个 **隐藏** 工具仍然注册在 MCP 层（按名 `tools/call` 仍命中），只是不会出现
+在列表响应里，以避免 Claude Code 会话启动时加载 11 份额外的工具 schema。隐藏
+工具走下面表格的 CLI 入口。
+
+**核心（6 个，暴露给 Claude Code）**
 
 | 工具 | 描述 |
 |------|------|
@@ -204,16 +211,22 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 | `mem_timeline` | 围绕锚点按时间顺序浏览观察。 |
 | `mem_get` | 获取指定观察 ID 的完整详情（包含重要度和关联 ID）。 |
 | `mem_save` | 手动保存记忆/观察。 |
-| `mem_update` | 原地更新已有观察，保留原始 ID 和引用关系。 |
-| `mem_stats` | 查看统计：计数、类型分布、热门项目、每日活动。 |
-| `mem_delete` | 按 ID 删除观察，支持预览/确认工作流。FTS5 自动清理。 |
-| `mem_compress` | 压缩旧的低价值观察为每周摘要，减少噪声。 |
-| `mem_maintain` | 记忆维护：扫描重复/过期/损坏条目，执行清理/去重/向量重建操作。 |
-| `mem_export` | 导出观察为 JSON 或 JSONL 格式，支持按项目、类型、日期范围过滤。 |
-| `mem_fts_check` | 检查 FTS5 索引完整性或重建索引。搜索结果异常或数据库恢复后使用。 |
-| `mem_browse` | 分层记忆仪表盘。按记忆层级（working/active/archive）分组展示观察。 |
-| `mem_registry` | 管理资源注册表：按需搜索技能/代理、列表、统计、导入/移除、重索引。搜索结果区分 managed（Read 路径）和 native（Skill 全名）调用方式。 |
-| `mem_use` | 从 managed 注册表加载 skill 或 agent。返回完整内容 + `~` 便携路径供 `Read()` 重载。 |
+
+**隐藏但可按名调用（11 个，走 CLI）**
+
+| 工具 | 对应 CLI | 说明 |
+|------|----------|------|
+| `mem_update` | `claude-mem-lite update <id>` | 原地更新某条观察。 |
+| `mem_stats` | `claude-mem-lite stats` | 计数、类型分布、每日活动。 |
+| `mem_delete` | `claude-mem-lite delete <id>` | 预览 / 确认流程，FTS5 自动清理。 |
+| `mem_compress` | `claude-mem-lite compress --preview` | 压缩旧的低价值观察。 |
+| `mem_maintain` | `claude-mem-lite maintain --action scan` | 去重 / decay / 清理 / 向量重建。 |
+| `mem_optimize` | `claude-mem-lite optimize --action preview` | LLM 深度优化：re-enrich / normalize / cluster-merge。 |
+| `mem_export` | `claude-mem-lite export` | JSON / JSONL 导出，支持项目/类型/日期过滤。 |
+| `mem_fts_check` | `claude-mem-lite fts-check [--rebuild]` | FTS5 完整性检查与重建。 |
+| `mem_browse` | `claude-mem-lite browse` | 分层仪表盘（working / active / archive）。 |
+| `mem_registry` | `claude-mem-lite registry <action>` | 列 / 搜索 / 导入 / 移除 skill / agent。 |
+| `mem_use` | _MCP only_ | 从 registry 按名载入 skill / agent。 |
 
 ### 技能命令（在 Claude Code 聊天中使用）
 

package/adopt-content.mjs

@@ -31,6 +31,9 @@ export function getDetailDoc() {
 
 ## 何时调用 MCP 工具
 
+以下 6 个核心 MCP 工具在 \`tools/list\` 中默认暴露，覆盖了契约的热路径：
+\`mem_search\` / \`mem_recent\` / \`mem_recall\` / \`mem_get\` / \`mem_save\` / \`mem_timeline\`。
+
 | 时机 | 工具 | 关键参数 |
 |------|------|----------|
 | Edit / Write 前 | \`mem_recall\` | \`file="<路径>"\` —— 过往 bugfix 与教训 |
@@ -46,12 +49,28 @@ export function getDetailDoc() {
 - "最近做了啥" → \`mem_recent\`
 - "<文件> 有哪些记忆" → \`mem_recall\`
 - "#NN 前后发生了啥" → \`mem_timeline\`
-- "清理过期记忆" → \`mem_maintain\`
-- "FTS 索引健康吗" → \`mem_fts_check\`
-- "按 tier 浏览" → \`mem_browse\`
-- "备份导出" → \`mem_export\`
 
-## CLI 速查
+## 维护 / 管理类工具（走 CLI）
+
+v2.34.0 起，以下 11 个工具从 \`tools/list\` 中隐藏以缩小启动上下文；它们仍注册在
+MCP 层，按名 \`tools/call\` 仍可命中，但对 Claude Code 这类只读 tools/list 的
+调用方只走下面的 CLI 入口：
+
+| 场景 | CLI |
+|------|-----|
+| 清理过期记忆 | \`claude-mem-lite maintain --action scan\` → \`--action execute\` |
+| 深度优化（Haiku） | \`claude-mem-lite optimize --action preview\` |
+| 压缩旧条目 | \`claude-mem-lite compress --preview\` |
+| FTS5 索引检查 / 重建 | \`claude-mem-lite fts-check [--rebuild]\` |
+| tier 分组浏览 | \`claude-mem-lite browse [--tier active]\` |
+| 导出 JSON/JSONL | \`claude-mem-lite export [--format jsonl]\` |
+| 统计总量 / 健康 | \`claude-mem-lite stats [--days 30]\` |
+| 删除某条 | \`claude-mem-lite delete <id>[,<id>]\` |
+| 更新某条 | \`claude-mem-lite update <id> [--title ...]\` |
+| 列 / 搜索 / 导入 skill-agent registry | \`claude-mem-lite registry <list\\|search\\|import>\` |
+| 按 registry 名载入 skill/agent | （MCP only：\`mem_use\`；由用户主动请求时才使用） |
+
+## CLI 速查（常用检索）
 
 | 命令 | 用途 |
 |------|------|

package/hook.mjs

@@ -417,27 +417,35 @@ async function handleStop() {
       try { buildAndSaveHandoff(db, sessionId, project, 'exit', episodeSnapshot, ccSessionId || sessionId); }
       catch (e) { debugCatch(e, 'handleStop-handoff'); }
 
-      // Fast summary baseline — ensures summary exists even if background LLM fails
+      // Fast summary baseline — ensures summary exists even if background LLM fails.
+      // T4-P2-B: guard against Stop firing twice for the same session (rare but possible;
+      // mirrors handleSessionStart line 795 hasSummary guard). Uses mem-internal sessionId
+      // as the WHERE key per the top-of-file dual-id invariant (#7789).
       try {
-        const firstPrompt = db.prepare(`
-          SELECT prompt_text FROM user_prompts
-          WHERE content_session_id = ?
-          ORDER BY prompt_number ASC LIMIT 1
-        `).get(sessionId);
-        const recentObs = db.prepare(`
-          SELECT title FROM observations
-          WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0
-          ORDER BY created_at_epoch DESC LIMIT 5
-        `).all(sessionId);
-        const fastRequest = truncate(firstPrompt?.prompt_text || '', 200);
-        const fastCompleted = recentObs.map(o => o.title).filter(Boolean).join('; ');
-        if (fastRequest || fastCompleted) {
-          const now = new Date();
-          db.prepare(`
-            INSERT INTO session_summaries
-            (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, created_at, created_at_epoch)
-            VALUES (?, ?, ?, '', '', ?, '', '', '[]', '[]', 'fast', ?, ?)
-          `).run(sessionId, project, fastRequest, truncate(fastCompleted, 300), now.toISOString(), now.getTime());
+        const existingSummary = db.prepare(
+          'SELECT 1 FROM session_summaries WHERE memory_session_id = ? LIMIT 1'
+        ).get(sessionId);
+        if (!existingSummary) {
+          const firstPrompt = db.prepare(`
+            SELECT prompt_text FROM user_prompts
+            WHERE content_session_id = ?
+            ORDER BY prompt_number ASC LIMIT 1
+          `).get(sessionId);
+          const recentObs = db.prepare(`
+            SELECT title FROM observations
+            WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0
+            ORDER BY created_at_epoch DESC LIMIT 5
+          `).all(sessionId);
+          const fastRequest = truncate(firstPrompt?.prompt_text || '', 200);
+          const fastCompleted = recentObs.map(o => o.title).filter(Boolean).join('; ');
+          if (fastRequest || fastCompleted) {
+            const now = new Date();
+            db.prepare(`
+              INSERT INTO session_summaries
+              (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, created_at, created_at_epoch)
+              VALUES (?, ?, ?, '', '', ?, '', '', '[]', '[]', 'fast', ?, ?)
+            `).run(sessionId, project, fastRequest, truncate(fastCompleted, 300), now.toISOString(), now.getTime());
+          }
         }
       } catch (e) { debugCatch(e, 'handleStop-fast-summary'); }
     } finally {
@@ -603,12 +611,14 @@ async function handleSessionStart() {
         const STALE_AGE = Date.now() - 30 * 86400000;
         const OP_CAP = 500;
 
-        // Purge FIRST: delete entries already marked pending-purge from previous cycles (7-day retention)
-        // Must run before decay/idle-mark to avoid same-cycle delete of newly-marked entries
+        // Purge FIRST: delete pending-purge entries. Schema has no marked_at_epoch, so we
+        // anchor retention on created_at_epoch instead: 30d marking gate + 7d grace = 37d.
+        // Older cutoffs (e.g. 7d) were always redundant with the 30d marking filter and
+        // made purge effectively immediate on the next maintenance cycle — fix for T4-P1-A.
         const purged = db.prepare(`
           DELETE FROM observations WHERE compressed_into = ${COMPRESSED_PENDING_PURGE}
             AND created_at_epoch < ?
-        `).run(Date.now() - 7 * 86400000);
+        `).run(Date.now() - 37 * 86400000);
         if (purged.changes > 0) debugLog('DEBUG', 'auto-maintain', `purged ${purged.changes} stale observations`);
 
         // Cleanup: remove broken observations (no title AND no narrative)
@@ -906,9 +916,13 @@ async function handleUserPrompt() {
       VALUES (?, ?, ?, ?, ?, 'active')
     `).run(sessionId, sessionId, project, now.toISOString(), now.getTime());
 
-    // Increment prompt counter
-    db.prepare('UPDATE sdk_sessions SET prompt_counter = COALESCE(prompt_counter, 0) + 1 WHERE content_session_id = ?').run(sessionId);
-    const counter = db.prepare('SELECT prompt_counter FROM sdk_sessions WHERE content_session_id = ?').get(sessionId);
+    // T4-P2-D: atomic increment+read via UPDATE ... RETURNING (SQLite 3.35+).
+    // Previously UPDATE + SELECT as two statements; parallel prompts could read a stale
+    // counter and emit duplicate prompt_number values. better-sqlite3 ships a modern SQLite.
+    const bumped = db.prepare(
+      'UPDATE sdk_sessions SET prompt_counter = COALESCE(prompt_counter, 0) + 1 WHERE content_session_id = ? RETURNING prompt_counter'
+    ).get(sessionId);
+    const promptNumber = bumped?.prompt_counter || 1;
 
     db.prepare(`
       INSERT INTO user_prompts (content_session_id, prompt_text, prompt_number, created_at, created_at_epoch)
@@ -916,7 +930,7 @@ async function handleUserPrompt() {
     `).run(
       sessionId,
       scrubSecrets(promptText.slice(0, 10000)),
-      counter?.prompt_counter || 1,
+      promptNumber,
       now.toISOString(), now.getTime()
     );
 
@@ -928,7 +942,7 @@ async function handleUserPrompt() {
     const ccSessionId = typeof hookData.session_id === 'string' && hookData.session_id.length > 0
       ? hookData.session_id
       : null;
-    if (counter?.prompt_counter <= 3) {
+    if (promptNumber <= 3) {
       try {
         if (detectContinuationIntent(db, promptText, project, ccSessionId)) {
           const injection = renderHandoffInjection(db, project, ccSessionId);

package/mem-cli.mjs

@@ -783,7 +783,7 @@ function cmdSave(db, args) {
   const { positional, flags } = parseArgs(args);
   const text = positional.join(' ');
   if (!text) {
-    fail('[mem] Usage: mem save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2]');
+    fail('[mem] Usage: mem save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T]');
     return;
   }
 
@@ -805,9 +805,21 @@ function cmdSave(db, args) {
   const project = flags.project ? resolveProject(db, flags.project) : inferProject();
   const saveFiles = flags.files ? flags.files.split(',').map(f => f.trim()).filter(Boolean) : [];
 
+  // Optional lesson_learned — accepts --lesson or --lesson-learned (alias)
+  // Mirrors MCP memSaveSchema.lesson_learned (≤500 chars) and cmdUpdate's flag handling.
+  const rawLesson = flags.lesson !== undefined ? flags.lesson
+    : flags['lesson-learned'] !== undefined ? flags['lesson-learned']
+    : null;
+  if (rawLesson !== null && typeof rawLesson === 'string' && rawLesson.length > 500) {
+    fail(`[mem] --lesson too long (${rawLesson.length} chars, max 500).`);
+    return;
+  }
+
   // Secret scrubbing (aligned with MCP mem_save)
   const safeContent = scrubSecrets(text);
   const safeTitle = scrubSecrets(rawTitle);
+  const safeLesson = (rawLesson !== null && typeof rawLesson === 'string' && rawLesson.length > 0)
+    ? scrubSecrets(rawLesson) : null;
 
   // Dedup: skip if similar title/content saved in last 5 minutes (aligned with MCP mem_save)
   const fiveMinAgo = Date.now() - 5 * 60 * 1000;
@@ -827,8 +839,11 @@ function cmdSave(db, args) {
   }
 
   // MinHash + CJK bigrams (aligned with MCP mem_save)
+  // Include lesson in the FTS-indexed text so the +0.3 lesson-boost actually surfaces
+  // lesson-bearing rows (mirrors MCP mem_save which builds the same indexText).
   const minhashSig = computeMinHash(safeTitle + ' ' + safeContent);
-  const bigramText = cjkBigrams(safeTitle + ' ' + safeContent);
+  const indexText = [safeTitle, safeContent, safeLesson].filter(Boolean).join(' ');
+  const bigramText = cjkBigrams(indexText);
   const textField = bigramText ? safeContent + ' ' + bigramText : safeContent;
 
   const now = new Date();
@@ -843,9 +858,9 @@ function cmdSave(db, args) {
   // Atomic: insert observation + observation_files + TF-IDF vector (aligned with MCP mem_save)
   const saveTx = db.transaction(() => {
     const result = db.prepare(`
-      INSERT INTO observations (memory_session_id, project, text, type, title, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, branch, created_at, created_at_epoch)
-      VALUES (?, ?, ?, ?, ?, ?, '', '', '[]', ?, ?, ?, ?, ?, ?)
-    `).run(sessionId, project, textField, type, safeTitle, safeContent, JSON.stringify(saveFiles), importance, minhashSig, getCurrentBranch(), now.toISOString(), now.getTime());
+      INSERT INTO observations (memory_session_id, project, text, type, title, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, lesson_learned, branch, created_at, created_at_epoch)
+      VALUES (?, ?, ?, ?, ?, ?, '', '', '[]', ?, ?, ?, ?, ?, ?, ?)
+    `).run(sessionId, project, textField, type, safeTitle, safeContent, JSON.stringify(saveFiles), importance, minhashSig, safeLesson, getCurrentBranch(), now.toISOString(), now.getTime());
     const savedId = Number(result.lastInsertRowid);
 
     // Populate observation_files junction table (aligned with MCP mem_save)
@@ -870,7 +885,8 @@ function cmdSave(db, args) {
   });
   const result = saveTx();
 
-  out(`[mem] Saved #${result.lastInsertRowid} [${type}] "${truncate(safeTitle, 80)}" (project: ${project})`);
+  const lessonNote = safeLesson ? ' 💡lesson captured' : '';
+  out(`[mem] Saved #${result.lastInsertRowid} [${type}] "${truncate(safeTitle, 80)}" (project: ${project})${lessonNote}`);
 }
 
 // N-1: Quality-focused stats for R-2 A/B baseline.
@@ -1645,6 +1661,9 @@ function cmdMaintain(db, args) {
   const OP_CAP = 1000;
   const results = [];
 
+  // T2-P1-B: surface the OP_CAP hit so users know to re-run, matching MCP mem_maintain.
+  const capHint = (changes) => (changes >= OP_CAP ? ' (cap reached, re-run for more)' : '');
+
   db.transaction(() => {
     if (ops.includes('cleanup')) {
       const deleted = db.prepare(`
@@ -1655,7 +1674,7 @@ function cmdMaintain(db, args) {
             ${projectFilter} LIMIT ${OP_CAP}
         )
       `).run(...baseParams);
-      results.push(`Cleaned up ${deleted.changes} broken observations`);
+      results.push(`Cleaned up ${deleted.changes} broken observations${capHint(deleted.changes)}`);
     }
 
     if (ops.includes('decay')) {
@@ -1683,7 +1702,8 @@ function cmdMaintain(db, args) {
             ${projectFilter} LIMIT ${OP_CAP}
         )
       `).run(staleAge, ...baseParams);
-      results.push(`Decayed ${decayed.changes} stale observations, marked ${idleMarked.changes} idle as pending-purge`);
+      const decayCap = (decayed.changes >= OP_CAP || idleMarked.changes >= OP_CAP) ? ' (cap reached, re-run for more)' : '';
+      results.push(`Decayed ${decayed.changes} stale observations, marked ${idleMarked.changes} idle as pending-purge${decayCap}`);
     }
 
     if (ops.includes('boost')) {
@@ -1697,7 +1717,7 @@ function cmdMaintain(db, args) {
             ${projectFilter} LIMIT ${OP_CAP}
         )
       `).run(...baseParams);
-      results.push(`Boosted ${boosted.changes} frequently-accessed observations`);
+      results.push(`Boosted ${boosted.changes} frequently-accessed observations${capHint(boosted.changes)}`);
     }
 
     if (ops.includes('dedup') && flags['merge-ids']) {
@@ -1715,17 +1735,41 @@ function cmdMaintain(db, args) {
       results.push(`Merged ${totalMerged} duplicate observations`);
     }
 
+    // T2-P1-B parity with MCP: warn when merge-ids is provided but dedup wasn't requested.
+    if (!ops.includes('dedup') && flags['merge-ids']) {
+      results.push('Warning: --merge-ids provided but "dedup" not in operations — merge-ids ignored');
+    }
+
     if (ops.includes('purge_stale')) {
       const retainDays = parseInt(flags['retain-days'], 10) || 30;
       const retainCutoff = Date.now() - retainDays * 86400000;
-      const purged = db.prepare(`
-        DELETE FROM observations WHERE id IN (
-          SELECT id FROM observations
-          WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ?
-            ${projectFilter} LIMIT ${OP_CAP}
-        )
-      `).run(retainCutoff, ...baseParams);
-      results.push(`Purged ${purged.changes} stale observations`);
+      // T2-P0-A (CLI parity): purge_stale is the only DELETE in this code path — require
+      // --confirm so a mis-typed `maintain execute --ops purge_stale` can't wipe rows silently.
+      const confirmed = flags.confirm === true || flags.confirm === 'true';
+      if (!confirmed) {
+        const previewRow = db.prepare(`
+          SELECT COUNT(*) AS candidates, MIN(created_at_epoch) AS oldest, MAX(created_at_epoch) AS newest
+          FROM observations
+          WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ? ${projectFilter}
+        `).get(retainCutoff, ...baseParams);
+        const pushLines = [`purge_stale preview (no --confirm):`,
+          `  Candidates (pending-purge, older than ${retainDays}d): ${previewRow.candidates}`];
+        if (previewRow.candidates > 0) {
+          pushLines.push(`  Oldest: ${new Date(previewRow.oldest).toISOString().slice(0, 10)}`);
+          pushLines.push(`  Newest: ${new Date(previewRow.newest).toISOString().slice(0, 10)}`);
+        }
+        pushLines.push(`  To delete, re-run with --confirm.`);
+        results.push(pushLines.join('\n'));
+      } else {
+        const purged = db.prepare(`
+          DELETE FROM observations WHERE id IN (
+            SELECT id FROM observations
+            WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ?
+              ${projectFilter} LIMIT ${OP_CAP}
+          )
+        `).run(retainCutoff, ...baseParams);
+        results.push(`Purged ${purged.changes} stale observations (retained last ${retainDays} days)${capHint(purged.changes)}`);
+      }
     }
   })();
 
@@ -1993,6 +2037,7 @@ Commands:
     --importance N      1-3 (default: 2)
     --project P         Project name
     --files f1,f2       Comma-separated file paths
+    --lesson T          Lesson learned (≤500 chars; alias: --lesson-learned)
 
   delete <id1,id2,...>  Delete observations by ID
     --confirm           Execute deletion (preview by default)
@@ -2180,10 +2225,32 @@ async function cmdEnrich(argv) {
 async function cmdOptimize(db, args) {
   const run = args.includes('--run');
   const runAll = args.includes('--run-all');
+  // T2-P1-D: --task accepts a single task or a comma-separated list, parity with MCP memOptimizeSchema.tasks.
+  const VALID_TASKS = ['re-enrich', 'normalize', 'cluster-merge', 'smart-compress'];
   const taskIdx = args.indexOf('--task');
-  const tasks = taskIdx >= 0 && args[taskIdx + 1] ? [args[taskIdx + 1]] : undefined;
+  let tasks;
+  if (taskIdx >= 0 && args[taskIdx + 1]) {
+    const parsed = args[taskIdx + 1].split(',').map(s => s.trim()).filter(Boolean);
+    const invalid = parsed.filter(t => !VALID_TASKS.includes(t));
+    if (invalid.length > 0) {
+      fail(`[mem] Unknown task(s): ${invalid.join(', ')}. Valid: ${VALID_TASKS.join(', ')}`);
+      return;
+    }
+    tasks = parsed;
+  }
+  // T2-P1-C: reject --max 0 / --max <non-positive> / --max <non-number> explicitly — the old
+  // `|| 15` fallback silently turned these into the default (15), burning LLM tokens.
   const maxIdx = args.indexOf('--max');
-  const maxItems = maxIdx >= 0 ? parseInt(args[maxIdx + 1], 10) || 15 : 15;
+  let maxItems = 15;
+  if (maxIdx >= 0) {
+    const raw = args[maxIdx + 1];
+    const parsed = parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 100) {
+      fail(`[mem] Invalid --max "${raw}". Must be an integer between 1 and 100.`);
+      return;
+    }
+    maxItems = parsed;
+  }
   // R-7 micro: --scope wide targets bugfix/refactor/feature/decision with narrative but no
   // lesson_learned (the "Haiku judged 'none'" cases). Default 'narrow' preserves old behavior.
   const scopeIdx = args.indexOf('--scope');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.33.5",
+  "version": "2.34.1",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {

package/scripts/pre-skill-bridge.js

@@ -66,13 +66,24 @@ try {
 
     // Read and output
     const content = readFileSync(skillPath, 'utf8');
-    // Token budget: ~4 chars per token, 4000 token limit = 16000 chars
+    // T4-P1-B: JSON hookSpecificOutput parity with pre-tool-recall.js. Some CC variants
+    // (notably sdscc) silently drop plain-text stdout from PreToolUse — the previous
+    // console.log() form would render on stock CC but no-op on those variants.
+    // Token budget: ~4 chars per token, 4000 token limit = 16000 chars.
+    let additionalContext;
     if (content.length > 16000) {
       const summary = content.slice(0, 800);
-      console.log(`<skill-bridge name="${row.name}" source="managed" truncated="true">\n${summary}\n...\n</skill-bridge>\n\nSkill content truncated. Use mem_use(name="${row.name}") to load full content.`);
+      additionalContext = `<skill-bridge name="${row.name}" source="managed" truncated="true">\n${summary}\n...\n</skill-bridge>\n\nSkill content truncated. Use mem_use(name="${row.name}") to load full content.`;
     } else {
-      console.log(`<skill-bridge name="${row.name}" source="managed">\n${content}\n</skill-bridge>\n\nThis skill was loaded from the managed registry. Follow the instructions above.`);
+      additionalContext = `<skill-bridge name="${row.name}" source="managed">\n${content}\n</skill-bridge>\n\nThis skill was loaded from the managed registry. Follow the instructions above.`;
     }
+    process.stdout.write(JSON.stringify({
+      suppressOutput: true,
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext,
+      },
+    }));
   } catch {
     // Silent failure — never block Skill tool
   } finally {

package/server.mjs

@@ -4,6 +4,7 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, fmtDate, isoWeekKey, debugLog, debugCatch, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, getCurrentBranch, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined, notLowSignalTitleClause, LOW_SIGNAL_TITLE } from './utils.mjs';
 import { extractCjkLikePatterns } from './nlp.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
@@ -158,7 +159,7 @@ function buildObsFtsQuery(scoring, { multiplier, withSnippet, withOffset, includ
   const mult = multiplier ? ` * ${multiplier}` : '';
   const lowSignalClause = includeNoise ? '' : `AND ${notLowSignalTitleClause('o')}`;
   return `
-    SELECT o.id, o.type, o.title, o.subtitle, o.project, o.created_at, o.importance,
+    SELECT o.id, o.type, o.title, o.subtitle, o.project, o.created_at, o.created_at_epoch, o.importance,
            o.files_modified,
            ${withSnippet ? "snippet(observations_fts, 2, '»', '«', '…', 10) as match_snippet," : ''}
            ${scoreExpr}${mult} as score
@@ -200,7 +201,8 @@ function buildObsFtsParams({ now, projectBoost, ftsQuery, args, epochFrom, epoch
 function ftsRowToResult(r, { scoreMultiplier, snippet } = {}) {
   return {
     source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle,
-    project: r.project, date: r.created_at, score: scoreMultiplier ? r.score * scoreMultiplier : r.score,
+    project: r.project, date: r.created_at, created_at_epoch: r.created_at_epoch,
+    score: scoreMultiplier ? r.score * scoreMultiplier : r.score,
     files_modified: r.files_modified, importance: r.importance, snippet: snippet ? (r.match_snippet || '') : '',
   };
 }
@@ -311,7 +313,7 @@ function searchObservations(ctx) {
       LIMIT ? OFFSET ?
     `).all(...params);
     for (const r of rows) {
-      results.push({ source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle, project: r.project, date: r.created_at, dateEpoch: r.created_at_epoch });
+      results.push({ source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle, project: r.project, date: r.created_at, created_at_epoch: r.created_at_epoch, files_modified: r.files_modified, importance: r.importance });
     }
   }
 
@@ -370,7 +372,7 @@ function searchSessions(ctx) {
     const now = Date.now();
     const sessionProjectBoost = args.project ? null : currentProject;
     const rows = db.prepare(`
-      SELECT s.id, s.request, s.completed, s.project, s.created_at,
+      SELECT s.id, s.request, s.completed, s.project, s.created_at, s.created_at_epoch,
              ${SESS_BM25}
                * (1.0 + EXP(-0.693 * (? - s.created_at_epoch) / ${RECENCY_HALF_LIFE_MS}.0))
                * (CASE WHEN ? IS NOT NULL AND s.project = ? THEN 2.0 ELSE 1.0 END) as score
@@ -392,7 +394,7 @@ function searchSessions(ctx) {
       perSourceLimit, perSourceOffset
     );
     for (const r of rows) {
-      results.push({ source: 'session', id: r.id, request: r.request, completed: r.completed, project: r.project, date: r.created_at, score: r.score });
+      results.push({ source: 'session', id: r.id, request: r.request, completed: r.completed, project: r.project, date: r.created_at, created_at_epoch: r.created_at_epoch, score: r.score });
     }
   } else if (!searchType) {
     // Skip sessions in unfiltered no-query mode (too noisy)
@@ -411,7 +413,7 @@ function searchSessions(ctx) {
       LIMIT ? OFFSET ?
     `).all(...params);
     for (const r of rows) {
-      results.push({ source: 'session', id: r.id, request: r.request, completed: r.completed, project: r.project, date: r.created_at, dateEpoch: r.created_at_epoch });
+      results.push({ source: 'session', id: r.id, request: r.request, completed: r.completed, project: r.project, date: r.created_at, created_at_epoch: r.created_at_epoch });
     }
   }
 
@@ -424,7 +426,7 @@ function searchPrompts(ctx) {
 
   if (ftsQuery) {
     const rows = db.prepare(`
-      SELECT p.id, p.prompt_text, p.content_session_id, p.created_at,
+      SELECT p.id, p.prompt_text, p.content_session_id, p.created_at, p.created_at_epoch,
              bm25(user_prompts_fts, 1) as score
       FROM user_prompts_fts
       JOIN user_prompts p ON user_prompts_fts.rowid = p.id
@@ -444,7 +446,7 @@ function searchPrompts(ctx) {
       perSourceLimit, perSourceOffset
     );
     for (const r of rows) {
-      results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, score: r.score });
+      results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, created_at_epoch: r.created_at_epoch, score: r.score });
     }
     // CJK LIKE fallback: FTS5 unicode61 can't tokenize CJK substrings in prompts
     if (rows.length === 0 && args.query) {
@@ -453,7 +455,7 @@ function searchPrompts(ctx) {
         const likeConds = cjkPatterns.map(() => 'p.prompt_text LIKE ?');
         const likeParams = cjkPatterns.map(p => `%${p}%`);
         const fallbackRows = db.prepare(`
-          SELECT p.id, p.prompt_text, p.content_session_id, p.created_at
+          SELECT p.id, p.prompt_text, p.content_session_id, p.created_at, p.created_at_epoch
           FROM user_prompts p
           JOIN sdk_sessions s ON p.content_session_id = s.content_session_id
           WHERE (${likeConds.join(' OR ')})
@@ -471,7 +473,7 @@ function searchPrompts(ctx) {
           perSourceLimit, perSourceOffset
         );
         for (const r of fallbackRows) {
-          results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, score: 0 });
+          results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, created_at_epoch: r.created_at_epoch, score: 0 });
         }
       }
     }
@@ -492,7 +494,7 @@ function searchPrompts(ctx) {
       LIMIT ? OFFSET ?
     `).all(...params);
     for (const r of rows) {
-      results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, dateEpoch: r.created_at_epoch });
+      results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, created_at_epoch: r.created_at_epoch });
     }
   }
 
@@ -521,7 +523,10 @@ function formatSearchOutput(paginatedResults, args, ftsQuery, totalCount, isCros
     ? `${paginatedResults.length} of ${totalCount}`
     : `${paginatedResults.length}`;
   const hasMixed = paginatedResults.some(r => r.source === 'session' || r.source === 'prompt');
-  lines.push(`Found ${countLabel} result(s)${args.query ? ` for "${args.query}"` : ''}:${hasMixed ? ' (# observation, S# session, P# prompt)' : ''}\n`);
+  // P2-6: empty/omitted query falls through to a "listing recent" path — label it explicitly
+  // so callers don't mistake BM25-less results for relevance-ranked ones.
+  const qLabel = args.query ? ` for "${args.query}"` : ' (no query — listing recent)';
+  lines.push(`Found ${countLabel} result(s)${qLabel}:${hasMixed ? ' (# observation, S# session, P# prompt)' : ''}\n`);
 
   for (const r of paginatedResults) {
     if (r.source === 'obs') {
@@ -626,7 +631,7 @@ server.registerTool(
       if (ftsQuery) {
         results.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
       } else {
-        results.sort((a, b) => (b.dateEpoch ?? 0) - (a.dateEpoch ?? 0));
+        results.sort((a, b) => (b.created_at_epoch ?? 0) - (a.created_at_epoch ?? 0));
       }
     }
 
@@ -831,15 +836,17 @@ server.registerTool(
     const source = args.source || 'obs';
     const placeholders = args.ids.map(() => '?').join(',');
 
-    let rows, allFields, prefix;
+    let rows, allFields, prefix, sourceLabel;
     if (source === 'session') {
       rows = db.prepare(`SELECT * FROM session_summaries WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...args.ids);
       allFields = ['id', 'request', 'investigated', 'learned', 'completed', 'next_steps', 'files_read', 'files_edited', 'notes', 'project', 'created_at', 'memory_session_id', 'prompt_number'];
       prefix = 'S#';
+      sourceLabel = 'sessions';
     } else if (source === 'prompt') {
       rows = db.prepare(`SELECT * FROM user_prompts WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...args.ids);
       allFields = ['id', 'prompt_text', 'content_session_id', 'prompt_number', 'created_at'];
       prefix = 'P#';
+      sourceLabel = 'prompts';
     } else {
       // Increment access_count for retrieved observations (batch UPDATE)
       try {
@@ -851,15 +858,43 @@ server.registerTool(
       rows = db.prepare(`SELECT * FROM observations WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...args.ids);
       allFields = ['id', 'type', 'title', 'subtitle', 'narrative', 'text', 'facts', 'concepts', 'lesson_learned', 'search_aliases', 'files_read', 'files_modified', 'project', 'created_at', 'memory_session_id', 'prompt_number', 'importance', 'related_ids', 'access_count', 'branch', 'superseded_at', 'superseded_by', 'last_accessed_at'];
       prefix = '#';
+      sourceLabel = 'observations';
+    }
+
+    // P1-3: validate requested fields — throw on all-invalid so callers don't silently get an
+    // empty record (header only). Partial-invalid is tolerated but surfaced as a note.
+    let fieldsNote = '';
+    if (args.fields?.length) {
+      const invalid = args.fields.filter(f => !allFields.includes(f));
+      const valid = args.fields.filter(f => allFields.includes(f));
+      if (valid.length === 0) {
+        throw new Error(`No valid fields. Unknown field(s): ${invalid.join(', ')}. Valid: ${allFields.join(', ')}`);
+      }
+      if (invalid.length > 0) {
+        fieldsNote = `Note: unknown field(s) dropped: ${invalid.join(', ')}. Valid: ${allFields.join(', ')}`;
+      }
     }
 
     if (rows.length === 0) {
-      return { content: [{ type: 'text', text: `No ${source === 'session' ? 'sessions' : source === 'prompt' ? 'prompts' : 'observations'} found for given IDs.` }] };
+      // P2-7: for source=session/prompt, check whether the IDs exist as observations so the
+      // caller can switch source instead of chasing a phantom miss.
+      let hint = '';
+      if (source === 'session' || source === 'prompt') {
+        try {
+          const obsHits = db.prepare(`SELECT id FROM observations WHERE id IN (${placeholders})`).all(...args.ids);
+          if (obsHits.length > 0) {
+            hint = ` These ID(s) exist as observations: ${obsHits.map(r => r.id).join(', ')}. Try source='obs'.`;
+          }
+        } catch { /* best-effort hint */ }
+      }
+      const msg = `No ${sourceLabel} found for given IDs.${hint}`;
+      return { content: [{ type: 'text', text: fieldsNote ? `${msg}\n\n${fieldsNote}` : msg }] };
     }
 
     const fields = args.fields?.length ? args.fields.filter(f => allFields.includes(f)) : allFields;
 
     const parts = [];
+    if (fieldsNote) parts.push(fieldsNote);
     for (const row of rows) {
       const lines = [`── ${prefix}${row.id} ──`];
       for (const f of fields) {
@@ -874,6 +909,13 @@ server.registerTool(
       parts.push(lines.join('\n'));
     }
 
+    // P1-4: surface IDs that weren't found (mirrors mem_delete's missing-ID note).
+    const foundIds = new Set(rows.map(r => r.id));
+    const missing = args.ids.filter(id => !foundIds.has(id));
+    if (missing.length > 0) {
+      parts.push(`Note: ID(s) ${missing.join(', ')} not found.`);
+    }
+
     return { content: [{ type: 'text', text: parts.join('\n\n') }] };
   })
 );
@@ -1365,11 +1407,43 @@ server.registerTool(
     }
 
     if (action === 'execute') {
-      const ops = args.operations || ['cleanup', 'decay', 'boost'];
+      const ops = args.operations && args.operations.length > 0
+        ? args.operations
+        : ['cleanup', 'decay', 'boost'];
+      // T2-P1-A: reject explicit empty array (vs. omitted → defaults above). Empty-array
+      // callers are almost always mistakes; silently running only FTS5 optimize hides the error.
+      if (args.operations && args.operations.length === 0) {
+        return { content: [{ type: 'text', text: 'operations array is empty. Pass a non-empty list (e.g. ["cleanup","decay","boost"]) or omit operations to use the default set.' }], isError: true };
+      }
       const results = [];
       const staleAge = Date.now() - STALE_AGE_MS;
       const OP_ROW_CAP = 1000; // safety cap per operation
 
+      // T2-P0-A: purge_stale is the only DELETE in this handler. Require confirm=true;
+      // a first call without confirm returns a dry-run preview so callers know the blast radius.
+      const purgeRequested = ops.includes('purge_stale');
+      if (purgeRequested && args.confirm !== true) {
+        const retainDays = args.retain_days ?? 30;
+        const retainCutoff = Date.now() - retainDays * 86400000;
+        const previewRow = db.prepare(`
+          SELECT COUNT(*) AS candidates, MIN(created_at_epoch) AS oldest, MAX(created_at_epoch) AS newest
+          FROM observations
+          WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ? ${projectFilter}
+        `).get(retainCutoff, ...baseParams);
+        const lines = [
+          'purge_stale preview (confirm=false):',
+          `  Candidates (pending-purge, older than ${retainDays}d): ${previewRow.candidates}`,
+        ];
+        if (previewRow.candidates > 0) {
+          lines.push(`  Oldest: ${new Date(previewRow.oldest).toISOString().slice(0, 10)}`);
+          lines.push(`  Newest: ${new Date(previewRow.newest).toISOString().slice(0, 10)}`);
+        }
+        lines.push('');
+        lines.push('Nothing was deleted. To execute, re-run with confirm=true:');
+        lines.push(`  mem_maintain(action="execute", operations=${JSON.stringify(ops)}, confirm=true${args.retain_days ? `, retain_days=${args.retain_days}` : ''}${args.project ? `, project="${args.project}"` : ''})`);
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+      }
+
       db.transaction(() => {
         if (ops.includes('cleanup')) {
           const deleted = db.prepare(`
@@ -1540,6 +1614,9 @@ server.registerTool(
       tasks: args.tasks,
       maxItems: args.max_items || 15,
       force,
+      // T2-P0-B: scope parity with CLI (--scope wide). When omitted, optimizeRun defaults
+      // to narrow via its own code; passing through keeps that fallback intact.
+      reenrichScope: args.scope,
     });
 
     const lines = ['🔧 LLM Optimization Results:'];
@@ -1625,15 +1702,18 @@ server.registerTool(
       const typeFilter = args.type;
       const where = typeFilter ? 'WHERE type = ? AND status = ?' : 'WHERE status = ?';
       const params = typeFilter ? [typeFilter, 'active'] : ['active'];
+      // T3-P2-A: order by adoption then recommendation (CLI parity), and coalesce NULL counts
+      // so the output shows "adopt:0" rather than the jarring "adopt:null".
       const resources = rdb.prepare(`
         SELECT name, type, invocation_name, recommend_count, adopt_count, capability_summary
-        FROM resources ${where} ORDER BY type, name
+        FROM resources ${where}
+        ORDER BY COALESCE(adopt_count, 0) DESC, COALESCE(recommend_count, 0) DESC, type, name
       `).all(...params);
 
       if (resources.length === 0) return { content: [{ type: 'text', text: 'No resources found.' }] };
 
       const lines = resources.map(r =>
-        `${r.type === 'skill' ? 'S' : 'A'} ${r.name}${r.invocation_name ? ` (${r.invocation_name})` : ''} — rec:${r.recommend_count} adopt:${r.adopt_count} — ${truncate(r.capability_summary || '', 80)}`
+        `${r.type === 'skill' ? 'S' : 'A'} ${r.name}${r.invocation_name ? ` (${r.invocation_name})` : ''} — rec:${r.recommend_count ?? 0} adopt:${r.adopt_count ?? 0} — ${truncate(r.capability_summary || '', 80)}`
       );
       return { content: [{ type: 'text', text: `Resources (${resources.length}):\n${lines.join('\n')}` }] };
     }
@@ -1908,19 +1988,29 @@ server.registerTool(
     wheres.push('superseded_at IS NULL');
     if (args.project) { wheres.push('project = ?'); params.push(resolveProject(args.project)); }
     if (args.type) { wheres.push('type = ?'); params.push(args.type); }
+    // T3-P1-A: surface invalid dates instead of silently dropping the filter — mirrors
+    // mem_search, which threw. A dropped filter can quietly expand the export blast radius.
     if (args.date_from) {
       const epoch = new Date(args.date_from).getTime();
-      if (!isNaN(epoch)) { wheres.push('created_at_epoch >= ?'); params.push(epoch); }
+      if (isNaN(epoch)) throw new Error(`Invalid date_from: "${args.date_from}" (use ISO 8601 or YYYY-MM-DD)`);
+      wheres.push('created_at_epoch >= ?');
+      params.push(epoch);
     }
     if (args.date_to) {
       const d = args.date_to.length === 10 ? args.date_to + 'T23:59:59.999Z' : args.date_to;
       const epoch = new Date(d).getTime();
-      if (!isNaN(epoch)) { wheres.push('created_at_epoch <= ?'); params.push(epoch); }
+      if (isNaN(epoch)) throw new Error(`Invalid date_to: "${args.date_to}" (use ISO 8601 or YYYY-MM-DD)`);
+      wheres.push('created_at_epoch <= ?');
+      params.push(epoch);
     }
 
     const where = wheres.length > 0 ? 'WHERE ' + wheres.join(' AND ') : '';
     const exportLimit = Math.min(args.limit ?? 200, 1000);
-    const rows = db.prepare(`SELECT id, project, type, title, subtitle, narrative, concepts, facts, lesson_learned, importance, files_modified, created_at, created_at_epoch FROM observations ${where} ORDER BY created_at_epoch DESC LIMIT ?`).all(...params, exportLimit);
+    // T3-P2-B: probe limit+1 so we can tell "user hit their own limit with more waiting" from
+    // "user got exactly what existed". Trim to exportLimit before rendering.
+    const probed = db.prepare(`SELECT id, project, type, title, subtitle, narrative, concepts, facts, lesson_learned, importance, files_modified, branch, access_count, memory_session_id, created_at, created_at_epoch FROM observations ${where} ORDER BY created_at_epoch DESC LIMIT ?`).all(...params, exportLimit + 1);
+    const rows = probed.slice(0, exportLimit);
+    const moreAvailable = probed.length > exportLimit;
 
     if (rows.length === 0) return { content: [{ type: 'text', text: 'No observations found matching the criteria.' }] };
 
@@ -1928,7 +2018,7 @@ server.registerTool(
       ? rows.map(r => JSON.stringify(r)).join('\n')
       : JSON.stringify(rows, null, 2);
 
-    const cap = rows.length >= exportLimit ? `\nNote: Results capped at ${exportLimit}. Use date_from/date_to or increase limit (max 1000) to export more.` : '';
+    const cap = moreAvailable ? `\nNote: Results capped at ${exportLimit}. Use date_from/date_to or increase limit (max 1000) to export more.` : '';
     return { content: [{ type: 'text', text: `Exported ${rows.length} observations:${cap}\n${output}` }] };
   })
 );
@@ -1987,20 +2077,20 @@ server.registerTool(
     inputSchema: memFtsCheckSchema,
   },
   safeHandler(async (args) => {
+    // T3-P2-C: Zod `action: z.enum(['check','rebuild'])` filters any other value before we
+    // reach this handler, so there's no "Unknown action" fallback to write.
     if (args.action === 'check') {
       const result = checkFTSIntegrity(db);
       return { content: [{ type: 'text', text: result.healthy
         ? 'FTS5 indexes are healthy — all integrity checks passed.'
         : `FTS5 issues found:\n${result.details.join('\n')}` }] };
     }
-    if (args.action === 'rebuild') {
-      const result = rebuildFTS(db);
-      const summary = result.errors.length > 0
-        ? `Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`
-        : `Successfully rebuilt: ${result.rebuilt.join(', ')}`;
-      return { content: [{ type: 'text', text: summary }] };
-    }
-    return { content: [{ type: 'text', text: `Unknown action: ${args.action}` }], isError: true };
+    // args.action === 'rebuild'
+    const result = rebuildFTS(db);
+    const summary = result.errors.length > 0
+      ? `Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`
+      : `Successfully rebuilt: ${result.rebuilt.join(', ')}`;
+    return { content: [{ type: 'text', text: summary }] };
   })
 );
 
@@ -2085,6 +2175,54 @@ server.registerTool(
   })
 );
 
+// ─── Hidden tool filter ─────────────────────────────────────────────────────
+// All 17 tools are registered (so `tools/call <name>` still resolves for
+// scripts and direct MCP clients), but only the 6 core tools appear in the
+// `tools/list` response. Hiding the 11 maintenance/admin tools keeps Claude
+// Code's startup context small while preserving the contract that the plugin
+// dogfoods (see CLAUDE.md §Mem usage contract and adopt-content.mjs).
+//
+// Safe because:
+//   - Protocol-layer override: we replace the mcp.js default ListTools
+//     handler on the underlying Server (setRequestHandler is a Map.set).
+//   - `enabled` stays true, so `tools/call` keeps routing normally — per
+//     mcp.js line 106, a `disabled` tool would reject calls too.
+
+const HIDDEN_TOOL_NAMES = new Set(
+  TOOL_DEFS.filter((t) => t.hidden === true).map((t) => t.name),
+);
+
+// Opt-out: setting CLAUDE_MEM_ALL_TOOLS=1 restores pre-v2.34.0 behavior where
+// all 17 tools are visible in `tools/list`. Users who relied on Claude Code
+// autonomously invoking the now-hidden maintenance tools can use this as an
+// immediate escape hatch while adopting the CLI entry points documented in
+// adopt-content.mjs / README.
+const EXPOSE_ALL_TOOLS = process.env.CLAUDE_MEM_ALL_TOOLS === '1';
+
+if (!EXPOSE_ALL_TOOLS) {
+  // Force mcp.js to install its default ListTools/CallTools handlers before
+  // we override; registerTool already did this, but keep the call explicit so
+  // a future reorder of tool registration doesn't break the override.
+  const originalHandler = server.server._requestHandlers.get('tools/list');
+  if (typeof originalHandler !== 'function') {
+    throw new Error('tools/list handler missing — server initialization order changed');
+  }
+  server.server.setRequestHandler(ListToolsRequestSchema, async (req, extra) => {
+    const full = await originalHandler(req, extra);
+    return { ...full, tools: full.tools.filter((t) => !HIDDEN_TOOL_NAMES.has(t.name)) };
+  });
+}
+
+// One-time discoverability banner (stderr only — Claude Code surfaces it on
+// session start). Skipped under MEM_QUIET_HOOKS=1 so CI / tests / hermeticity
+// harnesses stay silent.
+if (!effectiveQuiet()) {
+  const status = EXPOSE_ALL_TOOLS
+    ? 'all 17 tools exposed via CLAUDE_MEM_ALL_TOOLS=1'
+    : `tools/list narrowed to ${TOOL_DEFS.length - HIDDEN_TOOL_NAMES.size} core tools (${HIDDEN_TOOL_NAMES.size} hidden but callable by exact name; unset CLAUDE_MEM_ALL_TOOLS to keep, set =1 to restore all)`;
+  process.stderr.write(`[claude-mem-lite v${PKG_VERSION}] ${status}\n`);
+}
+
 // ─── WAL Checkpoint (periodic) ───────────────────────────────────────────────
 
 // Checkpoint WAL every 5 minutes to prevent unbounded growth

package/tool-schemas.mjs

@@ -50,8 +50,8 @@ export const memRecentSchema = {
 };
 
 export const memTimelineSchema = {
-  anchor: coerceInt.pipe(z.number().int()).optional().describe('Observation ID as center point'),
-  query: z.string().optional().describe('FTS5 query to auto-find anchor'),
+  anchor: coerceInt.pipe(z.number().int()).optional().describe('Observation ID as center point. Takes precedence over query when both are provided.'),
+  query: z.string().optional().describe('FTS5 query to auto-find anchor. Ignored when anchor is also given; use one or the other.'),
   before: coerceInt.pipe(z.number().int().min(0).max(50)).optional().describe('Items before anchor (default 5)'),
   after: coerceInt.pipe(z.number().int().min(0).max(50)).optional().describe('Items after anchor (default 5)'),
   project: z.string().optional().describe('Filter by project'),
@@ -96,18 +96,22 @@ export const memOptimizeSchema = {
     .describe('Which optimization tasks to run (default: all)'),
   max_items: coerceInt.pipe(z.number().int().min(1).max(100)).optional().default(15)
     .describe('Maximum LLM calls across all tasks (default: 15)'),
+  scope: z.enum(['narrow', 'wide']).optional().default('narrow')
+    .describe("Re-enrich scope: narrow=narrative-only candidates (default); wide=R-7 backfill (bugfix/refactor/feature/decision with narrative but lesson_learned='none'). CLI parity: --scope wide."),
 };
 
 export const memMaintainSchema = {
   action: z.enum(['scan', 'execute']).describe('scan=analyze candidates, execute=apply changes'),
   operations: z.array(z.enum(['dedup', 'decay', 'cleanup', 'boost', 'purge_stale', 'rebuild_vectors'])).optional()
-    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, purge_stale=delete decayed obs (needs confirm via scan first), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors'),
+    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, purge_stale=DELETE pending-purge obs older than retain_days (requires confirm=true; first call previews), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors'),
   merge_ids: z.preprocess(
     (v) => Array.isArray(v) ? v.map(g => Array.isArray(g) ? g.map(x => typeof x === 'string' ? parseInt(x, 10) : x) : g) : v,
     z.array(z.array(z.number().int()).min(2))
   ).optional().describe('For dedup: [[keepId, removeId1, removeId2], ...] — first ID in each group is kept'),
   retain_days: coerceInt.pipe(z.number().int().min(7).max(365)).optional()
     .describe('For purge_stale: keep observations newer than N days (default 30)'),
+  confirm: coerceBool.optional()
+    .describe('Required for destructive ops in `execute` mode (currently: purge_stale). Omit/false → dry-run preview; true → actually delete.'),
   project: z.string().optional().describe('Filter by project'),
 };
 
@@ -186,6 +190,17 @@ export const memBrowseSchema = {
 // Research note: discouragement-style descriptions reduce over-invocation by
 // 40-60% vs. encouragement-style ("use this to..."). See tests/tool-schemas.test.mjs
 // for the invariants this list must satisfy.
+//
+// Core vs hidden (v2.34.0): only 6 tools are exposed via MCP `tools/list`. The
+// remaining 11 stay registered — and are still callable by name at the MCP
+// protocol level (`tools/call` by exact name) — but are omitted from the list
+// response so they don't bloat every agent's startup context. The core set
+// covers the hot paths the invited-memory contract promises (recall before
+// Edit, save after bugfix, search/recent/timeline/get for retrieval). Hidden
+// tools are either maintenance (compress/maintain/optimize/fts_check),
+// admin/infra (stats/export/update/delete), or specialized browsers
+// (browse/registry/use) — all of which have CLI equivalents documented in
+// `adopt-content.mjs`.
 // ────────────────────────────────────────────────────────────────────────────
 
 export const tools = [
@@ -278,6 +293,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite delete <id>[,<id>,...] [--confirm]',
     inputSchema: memDeleteSchema,
+    hidden: true,
   },
   {
     name: 'mem_save',
@@ -314,6 +330,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite stats [--project X] [--days 30]',
     inputSchema: memStatsSchema,
+    hidden: true,
   },
   {
     name: 'mem_compress',
@@ -332,6 +349,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite compress [--preview] [--age-days 90]',
     inputSchema: memCompressSchema,
+    hidden: true,
   },
   {
     name: 'mem_maintain',
@@ -350,6 +368,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite maintain --action scan --operations dedup,decay',
     inputSchema: memMaintainSchema,
+    hidden: true,
   },
   {
     name: 'mem_optimize',
@@ -368,6 +387,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite optimize [--action preview|run|run_all] [--max-items N]',
     inputSchema: memOptimizeSchema,
+    hidden: true,
   },
   {
     name: 'mem_registry',
@@ -386,6 +406,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite registry <list|search|import|...> [args]',
     inputSchema: memRegistrySchema,
+    hidden: true,
   },
   {
     name: 'mem_use',
@@ -404,6 +425,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: MCP only (no CLI handler — use mem_registry to inspect)',
     inputSchema: memUseSchema,
+    hidden: true,
   },
   {
     name: 'mem_update',
@@ -422,6 +444,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite update <id> [--title ...] [--lesson ...]',
     inputSchema: memUpdateSchema,
+    hidden: true,
   },
   {
     name: 'mem_export',
@@ -440,6 +463,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite export [--format jsonl] [--project X] [--limit 500]',
     inputSchema: memExportSchema,
+    hidden: true,
   },
   {
     name: 'mem_recall',
@@ -476,6 +500,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite fts-check [--rebuild]',
     inputSchema: memFtsCheckSchema,
+    hidden: true,
   },
   {
     name: 'mem_browse',
@@ -494,5 +519,6 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite browse [--tier active] [--project X]',
     inputSchema: memBrowseSchema,
+    hidden: true,
   },
 ];