claude-mem-lite 2.33.4 → 2.34.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.33.4",
+      "version": "2.34.0",
       "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.4",
+  "version": "2.34.0",
   "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

@@ -109,14 +109,14 @@ if (!event) process.exit(0);
 
 // ─── Episode Flush ──────────────────────────────────────────────────────────
 
-// hookEventName defaults to 'PostToolUse' since that's the most common caller.
-// Stop / SessionStart callers MUST pass their own event name — CC rejects
-// hook output whose hookEventName doesn't match the triggering event
-// (regression introduced in v2.33.1's structured receipt, fixed in v2.33.3).
-// v2.33.4: CC's Stop-event schema does NOT accept hookSpecificOutput at all —
-// only PreToolUse / UserPromptSubmit / PostToolUse / SessionStart carry
-// additionalContext. On Stop we flush the episode to DB but skip the JSON
-// receipt entirely; emitting it triggers "Invalid input" schema rejection.
+// hookEventName serves two roles: it is written into the emitted receipt JSON
+// AND it gates emission via RECEIPT_EVENTS. Callers MUST pass their triggering
+// event name so both work — Stop falls outside the allowlist, so its receipt
+// is skipped entirely (CC's Stop schema rejects hookSpecificOutput at the root,
+// not just on event-name mismatch). The episode still flushes to DB and
+// spawns llm-episode background enrichment; only the stdout receipt is gated.
+// Regression chain: v2.33.1 introduced the receipt; v2.33.3 misdiagnosed the
+// Stop rejection as event-name mismatch; v2.33.4 is the root-cause fix.
 const RECEIPT_EVENTS = new Set(['PostToolUse', 'SessionStart', 'UserPromptSubmit']);
 function flushEpisode(episode, hookEventName = 'PostToolUse') {
   if (!episode || episode.entries.length === 0) return;

package/package.json

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

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';
@@ -2085,6 +2086,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

@@ -186,6 +186,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 +289,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite delete <id>[,<id>,...] [--confirm]',
     inputSchema: memDeleteSchema,
+    hidden: true,
   },
   {
     name: 'mem_save',
@@ -314,6 +326,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite stats [--project X] [--days 30]',
     inputSchema: memStatsSchema,
+    hidden: true,
   },
   {
     name: 'mem_compress',
@@ -332,6 +345,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite compress [--preview] [--age-days 90]',
     inputSchema: memCompressSchema,
+    hidden: true,
   },
   {
     name: 'mem_maintain',
@@ -350,6 +364,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 +383,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 +402,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite registry <list|search|import|...> [args]',
     inputSchema: memRegistrySchema,
+    hidden: true,
   },
   {
     name: 'mem_use',
@@ -404,6 +421,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 +440,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite update <id> [--title ...] [--lesson ...]',
     inputSchema: memUpdateSchema,
+    hidden: true,
   },
   {
     name: 'mem_export',
@@ -440,6 +459,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 +496,7 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite fts-check [--rebuild]',
     inputSchema: memFtsCheckSchema,
+    hidden: true,
   },
   {
     name: 'mem_browse',
@@ -494,5 +515,6 @@ export const tools = [
       '\n' +
       'Equivalent CLI: claude-mem-lite browse [--tier active] [--project X]',
     inputSchema: memBrowseSchema,
+    hidden: true,
   },
 ];