claude-mem-lite 4.0.4 → 5.1.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "4.0.4",
+      "version": "5.1.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "4.0.4",
+  "version": "5.1.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -75,7 +75,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 
 ## Features
 
-- **Automatic capture** -- Hooks into Claude Code lifecycle (PostToolUse, SessionStart, Stop, UserPromptSubmit) to record observations without manual effort
+- **Automatic capture** -- Hooks into the Claude Code lifecycle (SessionStart, PreCompact, PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit — the seven events in `hooks/hooks.json`) to record observations without manual effort
 - **Hybrid search** -- FTS5 BM25 + TF-IDF vector cosine similarity, merged via Reciprocal Rank Fusion (RRF). FTS5 handles keyword matching; 512-dim TF-IDF vectors capture semantic similarity for recall beyond exact terms
 - **Timeline browsing** -- Navigate observations chronologically with anchor-based context windows
 - **Episode batching** -- Groups related file operations into coherent episodes before LLM encoding
@@ -105,15 +105,12 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 - **Atomic writes** -- All file writes (episodes, CLAUDE.md) use write-to-tmp + rename to prevent corruption on crash
 - **Robust locking** -- PID-aware lock files with automatic stale/orphan cleanup (>30s timeout or dead PID)
 - **Stale session cleanup** -- Sessions active for >24h are automatically marked as abandoned on next start
-- **Resource registry** -- Indexes installed skills and agents with FTS5 search, composite scoring, and invocation tracking; searchable via `mem_registry` MCP tool
-- **Unified resource discovery** -- Shared filesystem traversal layer (`resource-discovery.mjs`) used by both runtime scanner and offline indexer, supporting flat directories, plugin nesting, and loose `.md` files
-- **Domain synonym expansion** -- Registry search queries expand to domain synonyms (e.g., "fix" → debug, bugfix, troubleshoot, diagnose, repair)
+- **Domain synonym expansion** -- Search queries expand to domain synonyms (e.g., "fix" → debug, bugfix, troubleshoot, diagnose, repair)
 - **Multi-provider LLM mode** -- Provider priority `ANTHROPIC_API_KEY` (direct Anthropic API) → `OPENROUTER_API_KEY` (OpenRouter, OpenAI-compatible — point it at any model via `OPENROUTER_MODEL`) → `claude -p` CLI fallback when no key is set
 - **Lesson-learned indexing** -- `lesson_learned` field indexed in FTS5 with weight 8, making past debugging insights directly searchable
 - **Cross-source normalization** -- `mem_search` normalizes scores across observations, sessions, and prompts before merging, preventing any source from dominating results
 - **Exponential recency decay** -- Type-differentiated half-lives (decisions: 90d, discoveries: 60d, bugfixes: 14d, changes: 7d) consistently applied in all ranking paths
 - **Prompt-time memory injection** -- UserPromptSubmit hook automatically searches and injects relevant past observations with recency and importance weighting
-- **Smart skill invocation** -- Auto-loaded and searched managed skills/agents include portable `~` paths with `Read()` guidance; native plugin skills recommend `Skill("full:name")`; prevents `Skill()` misuse for managed resources that aren't registered with Claude Code's native handler
 - **Dual injection dedup** -- `user-prompt-search.js` and `handleUserPrompt` coordinate via temp file to prevent duplicate memory injection
 - **Plugin cache hook self-heal** -- Claude Code runtime reads plugin hooks from `~/.claude/plugins/cache/<mp>/<plugin>/<ver>/hooks/hooks.json`, not from the marketplace source. When `install.mjs`-managed `settings.json` hooks coexist with a stale cache `hooks.json` (e.g. from a previous marketplace install or a plugin auto-update), the runtime registers hooks twice → every session start / user prompt fires twice. `install.mjs` and `hook-update.mjs` now clear cache `hooks.json` in every version dir, and `hook.mjs session-start` self-heals on every session (gated by `hasInstallManagedHooks` so plugin-only users are not affected). `install.mjs status` reports cache pollution state (since v2.31.1/2.31.2).
 - **Result-dedup cooldown** -- User-prompt memory injection uses result-overlap detection (>80% ID overlap → skip) instead of time-based cooldown, allowing topic switches within seconds while preventing redundant injections
@@ -121,7 +118,6 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 - **Configurable LLM model** -- Switch between Haiku (fast/cheap) and Sonnet (deeper analysis) via `CLAUDE_MEM_MODEL` env var
 - **DB auto-recovery** -- Detects and cleans corrupted WAL/SHM files on startup; periodic WAL checkpoints prevent unbounded growth
 - **Schema auto-migration** -- Idempotent `ALTER TABLE` migrations run on every startup, safely adding new columns and indexes without data loss
-- **Exploration bonus** -- New resources in the registry get a fair chance in composite ranking; zombie resources (high recommend, zero adopt) are penalized in scoring
 - **LLM concurrency control** -- File-based semaphore limits background workers to 2 concurrent LLM calls, preventing resource contention
 - **stdin overflow protection** -- Hook input truncated at 256KB with regex-based action salvage for oversized tool outputs
 - **Cross-session handoff** -- Captures session state (request, completed work, next steps, key files) on `/clear` or `/exit`, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap
@@ -190,8 +186,8 @@ Source files stay in the cloned repo. Update via `git pull && node install.mjs i
 ### What happens during installation
 
 1. **Install dependencies** -- `npm install --omit=dev` (compiles native `better-sqlite3`)
-2. **Register MCP server** -- `mem-lite` server with 20 tools (9 core exposed via `tools/list` + 11 hidden-but-callable; see the Usage section for the full table). The pre-v2.78 generic server name `mem` is renamed to `mem-lite` for namespace hygiene; the tool names themselves (`mem_search`, `mem_recall`, ...) are unchanged.
-3. **Configure hooks** -- `PostToolUse`, `SessionStart`, `Stop`, `UserPromptSubmit` lifecycle hooks
+2. **Register MCP server** -- `mem-lite` server with 18 tools (9 core exposed via `tools/list` + 9 hidden-but-callable; see the Usage section for the full table). The pre-v2.78 generic server name `mem` is renamed to `mem-lite` for namespace hygiene; the tool names themselves (`mem_search`, `mem_recall`, ...) are unchanged.
+3. **Configure hooks** -- all seven lifecycle events: `SessionStart`, `PreCompact`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `UserPromptSubmit`
 4. **Create data directory** -- `~/.claude-mem-lite/` (hidden) for database, runtime, and managed resource files
 5. **Auto-migrate** -- If `~/.claude-mem/` (original claude-mem) or `~/claude-mem-lite/` (pre-v0.5 unhidden) exists, migrates database and runtime files to `~/.claude-mem-lite/`, preserving the original untouched
 6. **Initialize database** -- SQLite with WAL mode, FTS5 indexes created on first server start
@@ -224,15 +220,12 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 ```
 ~/.claude-mem-lite/
   claude-mem-lite.db       # SQLite database — memory (WAL mode)
-  resource-registry.db     # SQLite database — skill/agent registry
   runtime/
     session-<project>    # Active session state
     ep-<project>.json    # Episode buffer
     ep-flush-*.json      # Flushed episodes awaiting processing
     reads-<project>.txt  # Read file paths (collected on flush)
   managed/
-    skills/              # Standalone skills: {name}/SKILL.md
-    agents/              # Agent plugins: {group}/agents/{name}.md + skills/*/SKILL.md
     repos/               # Shallow-cloned source repos
 ```
 
@@ -240,11 +233,14 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 
 ### MCP Tools (used automatically by Claude)
 
-As of v2.70.0, the server registers 20 tools in total but only the 9 **core**
-tools appear in `tools/list`. The 11 **hidden** tools remain callable at the
+As of v2.70.0, the server registers 18 tools in total but only the 9 **core**
+tools appear in `tools/list`. The 9 **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
+omitted from the list response so Claude Code sessions don't load 9 extra
+tool schemas at startup. (It read 20 / 11 until v5.0.0 removed the two skill-registry
+tools — `tool-schemas.mjs` is the source of truth, and
+`tests/tool-count-docs.test.mjs` now holds this paragraph, both README tool tables,
+`README.zh-CN.md`, `llms.txt` and `docs/ARCHITECTURE.md` to it.) Hidden tools are the maintenance / admin / browser
 surface — reach them through the CLI column in the second table.
 
 **Core (9, exposed to Claude Code)**
@@ -261,7 +257,7 @@ surface — reach them through the CLI column in the second table.
 | `mem_defer_list` | List open deferred items for the current project. |
 | `mem_defer_drop` | Drop a deferred item without fixing it; requires a `reason` for the audit trail. |
 
-**Hidden-but-callable (11, CLI-routed)**
+**Hidden-but-callable (9, CLI-routed)**
 
 | Tool | CLI equivalent | Notes |
 |------|----------------|-------|
@@ -274,8 +270,6 @@ surface — reach them through the CLI column in the second table.
 | `mem_export` | `claude-mem-lite export` | JSON / JSONL dump, filters by project, type, date. |
 | `mem_fts_check` | `claude-mem-lite fts-check <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)
 
@@ -457,9 +451,6 @@ UserPromptSubmit (two parallel paths)
   -> [user-prompt-search.js] Auto-search memory via FTS5 + active file context
   -> [user-prompt-search.js] Inject relevant past observations with recency/importance weighting
   -> [user-prompt-search.js] Write injected IDs to temp file for dedup
-  -> [user-prompt-search.js] L1 skill auto-load: match managed skill names in prompt
-     -> Load content with portable ~ path + Read() guidance
-     -> source="managed-skill|managed-agent", path="~/.claude-mem-lite/managed/..."
   -> [hook.mjs handleUserPrompt] Capture user prompt text to user_prompts table
   -> [hook.mjs handleUserPrompt] Increment session prompt counter
   -> [hook.mjs handleUserPrompt] Handoff: detect continuation intent → inject previous session context
@@ -472,29 +463,6 @@ Stop
   -> Spawn LLM summary worker (poll-based wait)
 ```
 
-### 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 — 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:
-  -> registry-scanner.mjs discovers skills/agents on filesystem
-  -> resource-discovery.mjs handles flat dirs, plugin nesting, loose .md files
-  -> registry-indexer.mjs indexes content into FTS5 with metadata
-  -> registry-retriever.mjs provides BM25-ranked search with synonym expansion
-  -> mem_registry MCP tool exposes search/list/stats/import/remove/reindex actions
-
-Smart invocation (three layers):
-  L1 auto-load: UserPromptSubmit matches managed skill name in prompt
-     -> Loads content with path="~/.claude-mem-lite/managed/.../SKILL.md"
-     -> Guides: Read("path") or mem_use(name="..."), never Skill()
-  L2 bridge: PreToolUse hook intercepts Skill("name") for managed resources
-     -> Outputs content, prevents native handler failure
-  L3 explicit: mem_use(name="...") loads full content with reload path
-  Search: managed resources → Read(path), native plugins → Skill("full:name")
-```
-
-Composite scoring for search results: BM25 relevance (40%) + repo stars (15%) + success rate (15%) + adoption rate (10%) + freshness (10%) + exploration bonus (10%). Domain filtering ensures platform-specific resources (iOS, Go, Rust) only surface for matching projects.
 
 ### Episode Encoding
 
@@ -575,7 +543,7 @@ Shows MCP registration, hook configuration, plugin disabled state, and database
 
 ### Recovery (stuck install / hook errors)
 
-If you see `ERR_MODULE_NOT_FOUND` on PreToolUse:Read/Edit/Skill hooks, or `claude-mem-lite` commands crash with import errors, you're likely hit by a partial auto-update — the updater copied new scripts but missed a sibling `lib/*` file, breaking the hook chain (and the next auto-update that would have healed it).
+If you see `ERR_MODULE_NOT_FOUND` on PreToolUse:Read/Edit hooks, or `claude-mem-lite` commands crash with import errors, you're likely hit by a partial auto-update — the updater copied new scripts but missed a sibling `lib/*` file, breaking the hook chain (and the next auto-update that would have healed it).
 
 **v2.84.0+** ships a `repair` subcommand that re-syncs from the latest GitHub release:
 
@@ -656,12 +624,6 @@ claude-mem-lite/
   format-utils.mjs     # String formatting: truncate, typeIcon, date/time/week formatting
   hash-utils.mjs       # MinHash signatures, Jaccard similarity for dedup
   bash-utils.mjs       # Bash output significance detection: errors, tests, builds, deploys
-  # Resource registry
-  registry.mjs         # Resource registry DB: schema, CRUD, FTS5, invocation tracking
-  registry-retriever.mjs # FTS5 retrieval with synonym expansion and composite scoring
-  registry-indexer.mjs # Resource indexing pipeline
-  registry-scanner.mjs # Filesystem scanner: reads content + hashes, delegates discovery
-  resource-discovery.mjs # Shared discovery layer: flat dirs, plugin nesting, loose .md files
   haiku-client.mjs     # Unified Haiku LLM wrapper: direct API or CLI fallback
   # Install & config
   install.mjs          # CLI installer: setup, uninstall, status, doctor (npx/git clone mode)
@@ -670,12 +632,11 @@ claude-mem-lite/
   scripts/
     setup.sh           # Setup hook: npm install + migration (hidden dir + old dir)
     post-tool-use.sh   # Bash pre-filter: skips noise in ~5ms, tracks Read paths
-    user-prompt-search.js # UserPromptSubmit hook: auto-search memory + L1 skill auto-load
-    pre-skill-bridge.js  # PreToolUse hook: L2 skill bridge for managed resources
+    user-prompt-search.js # UserPromptSubmit hook: auto-search memory on user prompts
     pre-tool-recall.js   # PreToolUse hook: file lesson recall before Edit/Write
+    post-tool-recall.js  # PostToolUse hook: error recall after a failed tool call
+    pre-agent-inject.sh  # PreToolUse hook: context for spawned agents
     prompt-search-utils.mjs # Shared logic: skip patterns, intent detection, name matching
-    convert-commands.mjs # Converts command .md → SKILL.md in managed plugins
-    index-managed.mjs  # Offline indexer for managed resources
   # Test & benchmark (dev only)
   tests/               # Unit, property, integration, contract, E2E, pipeline tests
   benchmark/           # BM25 search quality benchmarks + CI gate
@@ -799,7 +760,7 @@ claude-mem-lite.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `CLAUDE_MEM_ALL_TOOLS` | `1` exposes all 20 MCP tools in `tools/list` instead of the 9 core ones (pre-v2.34.0 behavior). The 11 hidden tools stay callable by exact name either way. | _(9 core)_ |
+| `CLAUDE_MEM_ALL_TOOLS` | `1` exposes all 18 MCP tools in `tools/list` instead of the 9 core ones (pre-v2.34.0 behavior). The 9 hidden tools stay callable by exact name either way. | _(9 core)_ |
 | `CLAUDE_MEM_FILE_INTEL` | `0` disables the file-intel block injected before `Read` (past observations about the file you are about to open). | _(on)_ |
 | `CLAUDE_MEM_FILE_INTEL_MIN_TOKENS` | Files smaller than this stay silent — file-intel only pays for itself on large files. | `800` |
 | `CLAUDE_MEM_REREAD_GUARD` | `0` disables the warning when the same file is read twice in a session. Never fires on `offset`/`limit` paging. | _(on)_ |
@@ -809,18 +770,6 @@ claude-mem-lite.
 | `CLAUDE_MEM_NO_TEMPLATE_REFRESH` | `1` stops SessionStart from refreshing the adopted `CLAUDE.md` managed block when the shipped template changes. | _(refreshes)_ |
 | `MEM_QUIET_HOOKS` | See Core above — the broadest injection-volume switch. | _(disabled)_ |
 
-### Registry import bounds
-
-`registry import-url` pulls from a third-party repository, so it is bounded. Entries past a
-bound are refused, not truncated, and the refusal is printed with the import result. Set any
-of these to `0` for the pre-v3.98 unlimited behavior; an unparseable or negative value keeps
-the default rather than removing the bound.
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CLAUDE_MEM_IMPORT_MAX_ITEMS` | Max skills/agents imported from one repository. | `200` |
-| `CLAUDE_MEM_IMPORT_MAX_FILE_BYTES` | Max size of a single `SKILL.md`/`AGENT.md`. Oversized entries are skipped; the rest still import. | `2097152` (2 MB) |
-| `CLAUDE_MEM_IMPORT_MAX_TOTAL_BYTES` | Byte budget for one import run. Exhausting it stops the walk and books the remainder as refused. | `52428800` (50 MB) |
 
 ### Retrieval tuning
 
@@ -840,7 +789,6 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `CLAUDE_MEM_ERROR_RECALL_BM25_MIN` | Relevance floor for the error-recall surface (memories injected after a failed Bash command). **Off by default.** Setting it to `10.5` (the calibrated value) makes the surface stay silent when its best-matching memory is not actually about the failure — the whole set is dropped, never trimmed row-by-row. **It is a real trade, not a free win:** measured on a live database at that threshold, injections fall ~37% and ~39% of firings go silent, concentrated in projects with few memories. Off by default because nothing shows the dropped rows were noise. Explore with `node benchmark/error-recall-suite.mjs --sweep`. | `0` (off) |
 | `CLAUDE_MEM_ERROR_RECALL_RERANK` | `off` restores the flat keyword ordering of the error-recall surface. **On by default**, and unlike the floor above it removes nothing: memories that share only the failed command's vocabulary are demoted below memories that mention the failure itself, and when a project has none of the latter the result is unchanged. Measured on a live database over 52 real failing commands × 15 projects: the lead memory matched no error term in 42.3% of firings before, 21.5% after, with the injected row count identical. | _(on)_ |
 | `CLAUDE_MEM_ERROR_RECALL_ON_FAILURE` | `off` stops the plugin from recalling memories when a Bash command **fails at the host level**. On by default. Claude Code delivers failed tool calls to a separate `PostToolUseFailure` hook event, so before this the surface only ever saw commands that exited `0` while printing error-ish text — a genuinely failing build recalled nothing. Denials from your own guardrails (sandbox, policy hooks, declined permission prompts) and commands you interrupted are never recalled for. | _(on)_ |
-| `CLAUDE_MEM_REGISTRY_CONFINE` | `off` lets registry enrichment read a resource whose `local_path` lies outside the managed data directory. **On by default.** Enrichment reads the file at `resources.local_path` and sends it to an LLM; the confinement check used to guard one of the four code paths that do this (`mem_registry(action="enrich")`) and not the other three, so `enrich <name>`, `enrich --all` and `import --enrich` read any path the row happened to hold. All four are gated now. Turn it off only if you deliberately registered resources outside `CLAUDE_MEM_DIR` and want them enriched; only `off` disables it — case-insensitively and ignoring surrounding whitespace — so a typo leaves the guard on. | _(on)_ |
 | `CLAUDE_MEM_UPS_IDENTIFIER_BYPASS` | `0` disables the bypass that lets an exact identifier match skip the score floors. | _(on)_ |
 | `CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT` | How many past-prompt rows the fallback arm may return. | `1` |
 | `MEM_COVERAGE_THRESHOLD` | Fraction of query terms a memory must cover to qualify (∈ [0,1]). | `0.4` |
@@ -882,10 +830,9 @@ what is already stored — only whether new work runs.
 | `CLAUDE_MEM_SKIP_MAINTAIN` | Skip the 24h auto-maintain pass (decay, purge, backup). | _(runs)_ |
 | `CLAUDE_MEM_SKIP_OPTIMIZE` | Skip the LLM optimization pass (re-enrich, normalize, cluster-merge). | _(runs)_ |
 | `CLAUDE_MEM_SKIP_AUTO_DEDUP_FUZZY` | Skip the MinHash near-duplicate pass, keeping exact dedup. | _(runs)_ |
-| `CLAUDE_MEM_SKIP_MARKER_GC` | Skip the runtime-marker sweep. | _(runs)_ |
+| `CLAUDE_MEM_SKIP_MARKER_GC` | Skip the runtime-marker sweep. **Must be exactly `1`** — unlike the other `CLAUDE_MEM_SKIP_*` flags, which accept any truthy value, this one compares against the string `1`. That is deliberate: a truthy check makes `=0` mean "skip", which is the opposite of what anyone typing it intends. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_UPDATE` | Skip the 24h auto-update check against GitHub Releases. | _(runs)_ |
 | `CLAUDE_MEM_SKIP_SIG_VERIFY` | Skip Ed25519 signature verification of a downloaded update. **Escape hatch — leaves updates unauthenticated.** | _(verifies)_ |
-| `CLAUDE_MEM_SKIP_REPOS` | Skip skill/agent registry seeding during install. | _(seeds)_ |
 | `CLAUDE_MEM_NO_LESSON_RETRY` | `1` disables the one-shot retry that re-asks for a missing `lesson_learned`. | _(retries)_ |
 | `CLAUDE_MEM_FLUSH_TIMEOUT` | Seconds the Stop hook waits for pending episode flushes. | `15` |
 | `CLAUDE_MEM_BACKUP_BUDGET_MB` | Disk budget for backup snapshots; the next maintain/save evicts oldest snapshots past the 7-day undo grace. | `256` |
@@ -897,7 +844,6 @@ and names can change between releases.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `CLAUDE_MEM_RECOMMEND_MODE` | Skill-recommendation engine: `shadow` (log would-be recommendations, inject nothing) or `off`. **`live` is parsed but not implemented** — live injection is Phase 2. Setting it runs shadow and prints one warning to stderr per process; `claude-mem-lite doctor` also reports it as an inert flag. | `shadow` |
 | `CLAUDE_MEM_TASK_IMPERATIVE` | `on`/`1` injects the single most relevant lesson at prompt position under an imperative template. | _(off)_ |
 | `CLAUDE_MEM_SUBAGENT_INJECT` | Dispatch-time memory injection for subagents. | _(off)_ |
 | `CLAUDE_MEM_SALIENCE` | Selects a comprehension-bridge arm (`bridge`, `bind`); unset = current default behavior. | _(unset)_ |

package/README.zh-CN.md

@@ -54,7 +54,7 @@
 
 ## 功能特性
 
-- **自动捕获** -- 挂载到 Claude Code 生命周期（PostToolUse、PreToolUse、SessionStart、Stop、UserPromptSubmit），无需手动操作即可记录观察
+- **自动捕获** -- 挂载到 Claude Code 生命周期（`hooks/hooks.json` 里的七个事件：SessionStart、PreCompact、PreToolUse、PostToolUse、PostToolUseFailure、Stop、UserPromptSubmit），无需手动操作即可记录观察
 - **FTS5 搜索** -- 基于 BM25 排名的全文搜索，覆盖观察、会话摘要和用户提示，支持重要度加权
 - **时间线浏览** -- 基于锚点的时间上下文窗口，按时间顺序浏览观察
 - **Episode 批处理** -- 将相关文件操作分组为连贯的 episode，再进行 LLM 编码
@@ -81,18 +81,13 @@
 - **原子写入** -- 所有文件写入（episode、CLAUDE.md）使用 write-to-tmp + rename 防止崩溃时损坏
 - **健壮锁机制** -- PID 感知的锁文件，自动清理过期（>30s）或孤儿（PID 已死）锁
 - **过期会话清理** -- 活跃超过 24 小时的会话在下次启动时自动标记为 abandoned
-- **智能调用** -- 三层调用系统：L1 自动加载（UserPromptSubmit 匹配 skill 名注入内容 + `Read()` 路径），L2 Bridge（PreToolUse 拦截 `Skill()` 误调），L3 显式调用（`mem_use` MCP 工具）。managed 资源用 `Read("~/.claude-mem-lite/managed/.../SKILL.md")`，原生插件用 `Skill("full:name")`
-- **资源注册表** -- 对已安装的 skill 和 agent 建立 FTS5 索引，支持复合评分和调用追踪。搜索结果区分 managed（Read 路径）vs native（Skill 全名）调用方式
-- **统一资源发现** -- 共享文件系统遍历层（`resource-discovery.mjs`），运行时扫描器和离线索引器共用，支持扁平目录、插件嵌套和松散 `.md` 文件
-- **领域同义词扩展** -- 注册表搜索查询自动扩展领域同义词（如 "修复" → fix, debug, bugfix, repair, error）
-- **持久化冷却机制** -- 5 分钟跨会话冷却 + 同会话去重，避免重复推荐 skill 自动加载
+- **领域同义词扩展** -- 搜索查询自动扩展领域同义词（如 "修复" → fix, debug, bugfix, repair, error）
 - **多 provider LLM 调用** -- provider 优先级 `ANTHROPIC_API_KEY`（直连 Anthropic API）→ `OPENROUTER_API_KEY`（OpenRouter，OpenAI 兼容，可用 `OPENROUTER_MODEL` 指向任意模型）→ 无 key 时回退 `claude -p` CLI
 - **Haiku 熔断器** -- 连续 3 次 LLM 失败后，禁用 Haiku 调度 5 分钟，防止级联延迟
 - **否定意图感知** -- 正确处理 "不要测试了，先修 bug" 等复杂提示，排除被否定的意图，支持中英文混合输入
 - **可配置 LLM 模型** -- 通过 `CLAUDE_MEM_MODEL` 环境变量在 Haiku（快速/低成本）和 Sonnet（深度分析）之间切换
 - **数据库自动恢复** -- 启动时检测并清理损坏的 WAL/SHM 文件；定期 WAL checkpoint 防止无限增长
 - **Schema 自动迁移** -- 每次启动运行幂等的 `ALTER TABLE` 迁移，安全地添加新列和索引，不丢失数据
-- **探索奖励** -- 注册表中的新资源在复合排名中获得公平机会；高推荐零采纳的"僵尸"资源被惩罚
 - **LLM 并发控制** -- 基于文件的信号量将后台 worker 限制为 2 个并发 LLM 调用，防止资源争用
 - **stdin 溢出保护** -- Hook 输入在 256KB 处截断，对超大工具输出使用正则挽救关键信息
 - **跨会话交接** -- 在 `/clear` 或 `/exit` 时捕获会话状态（请求、已完成工作、后续步骤、关键文件），下次会话检测到继续意图时自动注入上下文（支持显式关键词和 FTS5 术语重叠匹配）
@@ -111,7 +106,7 @@
 
 ## 环境要求
 
-- **Node.js** >= 18
+- **Node.js** >= 22（v4.0.0 起：better-sqlite3 13 要求 >=22，Node 20 已于 2026-04 EOL；`package.json` 的 `engines` 是唯一事实来源）
 - **Claude Code** CLI 已安装并配置（`claude` 命令可用）
 - **SQLite3** 支持（由 `better-sqlite3` 提供，安装时编译）
 - **平台**：Linux 或 macOS（参见[平台支持](#平台支持)）
@@ -150,13 +145,13 @@ node install.mjs install
 ### 安装过程
 
 1. **安装依赖** -- `npm install --omit=dev`（编译原生 `better-sqlite3`）
-2. **注册 MCP 服务器** -- `mem-lite` 服务器，包含 20 个工具（9 个核心通过 `tools/list` 暴露 + 11 个隐藏但可调；完整表见 Usage 段）。v2.78 前服务器名为通用的 `mem`，现已改名为 `mem-lite` 避免与用户其它 `.mcp.json` 冲突；工具名（`mem_search`/`mem_recall` 等）保持不变。
+2. **注册 MCP 服务器** -- `mem-lite` 服务器，包含 18 个工具（9 个核心通过 `tools/list` 暴露 + 9 个隐藏但可调；完整表见 Usage 段）。v2.78 前服务器名为通用的 `mem`，现已改名为 `mem-lite` 避免与用户其它 `.mcp.json` 冲突；工具名（`mem_search`/`mem_recall` 等）保持不变。
 
 > **自动 adopt 会写进你的项目，且每次 SessionStart 都跑（v3.13+）。** 插件向**项目自己的 `<cwd>/CLAUDE.md`**（通常是会进 git 的文件）写入一个 slug 限定的**托管块**，外加 `<cwd>/.claude/plugin_claude_mem_lite.md` 详情文件。该块是一条提升 Claude 主动调用 `mem_recall` / `mem_save` 的 system-authority 指针；块以外的内容逐字保留，也能与其它插件的块共存于同一文件。这是**每次** SessionStart 都做的幂等同步，不只是第一次——块被删掉会重新写回，出货模板变了会刷新。**任何安装路径都生效**（npm、npx、`/plugin`、手动），**无需再手动跑 `/adopt`**。
 >
 > 关闭方式：项目级 `claude-mem-lite adopt --disable`（重新启用用 `--enable`）；全局 `export MEM_NO_AUTO_ADOPT=1`；只冻结模板刷新用 `CLAUDE_MEM_NO_TEMPLATE_REFRESH=1`。`claude-mem-lite unadopt` 可移除托管块与详情文件。手动 `/adopt` 仍保留用于编辑后重写或 `--all` 批量场景。
-3. **配置钩子** -- `PostToolUse`、`PreToolUse`、`SessionStart`、`Stop`、`UserPromptSubmit` 生命周期钩子
-4. **创建数据目录** -- `~/.claude-mem-lite/`（隐藏目录），存放数据库、运行时和托管资源文件
+3. **配置钩子** -- 全部七个生命周期事件：`SessionStart`、`PreCompact`、`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`Stop`、`UserPromptSubmit`
+4. **创建数据目录** -- `~/.claude-mem-lite/`（隐藏目录），存放数据库与运行时文件
 5. **自动迁移** -- 自动检测 `~/.claude-mem/`（原版 claude-mem）或 `~/claude-mem-lite/`（v0.5 前的非隐藏目录），将数据库和运行时文件迁移到 `~/.claude-mem-lite/`，原目录保持不变
 6. **初始化数据库** -- SQLite WAL 模式，FTS5 索引在服务器首次启动时创建
 
@@ -188,15 +183,12 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 ```
 ~/.claude-mem-lite/
   claude-mem-lite.db       # SQLite 数据库 — 记忆（WAL 模式）
-  resource-registry.db     # SQLite 数据库 — skill/agent 注册表
   runtime/
     session-<project>    # 活跃会话状态
     ep-<project>.json    # Episode 缓冲区
     ep-flush-*.json      # 已刷新的 episode，等待处理
     reads-<project>.txt  # Read 文件路径（刷新时收集）
   managed/
-    skills/              # 独立 skill：{name}/SKILL.md
-    agents/              # Agent 插件：{group}/agents/{name}.md + skills/*/SKILL.md
     repos/               # 浅克隆的源代码仓库
 ```
 
@@ -204,12 +196,16 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 
 ### MCP 工具
 
-v2.34.0 起服务端注册 17 个工具，但 `tools/list` 只暴露 6 个 **核心** 工具；其余
-11 个 **隐藏** 工具仍然注册在 MCP 层（按名 `tools/call` 仍命中），只是不会出现
-在列表响应里，以避免 Claude Code 会话启动时加载 11 份额外的工具 schema。隐藏
-工具走下面表格的 CLI 入口。
+v2.34.0 起服务端只把一部分工具暴露给 `tools/list`。当前是 18 个工具，其中 9 个
+**核心** 工具出现在列表里，另外 9 个 **隐藏** 工具仍然注册在 MCP 层（按名
+`tools/call` 仍命中），只是不出现在列表响应里，以避免 Claude Code 会话启动时
+多加载 9 份工具 schema。隐藏工具走下面表格的 CLI 入口。
 
-**核心（6 个，暴露给 Claude Code）**
+（这里长期写着 17 / 6 / 11，而英文 README 写着 20 / 9 / 11 —— 两个都不对。
+`tool-schemas.mjs` 是唯一事实来源，`tests/tool-count-docs.test.mjs` 现在把两份
+README 和 `docs/ARCHITECTURE.md` 都钉在它上面。）
+
+**核心（9 个，暴露给 Claude Code）**
 
 | 工具 | 描述 |
 |------|------|
@@ -219,8 +215,11 @@ v2.34.0 起服务端注册 17 个工具，但 `tools/list` 只暴露 6 个 **核
 | `mem_timeline` | 围绕锚点按时间顺序浏览观察。 |
 | `mem_get` | 获取指定观察 ID 的完整详情（包含重要度和关联 ID）。 |
 | `mem_save` | 手动保存记忆/观察。 |
+| `mem_defer` | 记录一条跨会话待办（deferred work）。 |
+| `mem_defer_list` | 列出当前项目未关闭的待办。 |
+| `mem_defer_drop` | 带理由地关闭一条待办。 |
 
-**隐藏但可按名调用（11 个，走 CLI）**
+**隐藏但可按名调用（9 个，走 CLI）**
 
 | 工具 | 对应 CLI | 说明 |
 |------|----------|------|
@@ -233,8 +232,6 @@ v2.34.0 起服务端注册 17 个工具，但 `tools/list` 只暴露 6 个 **核
 | `mem_export` | `claude-mem-lite export` | JSON / JSONL 导出，支持项目/类型/日期过滤。 |
 | `mem_fts_check` | `claude-mem-lite fts-check <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 聊天中使用）
 
@@ -370,17 +367,9 @@ PostToolUse（每次工具执行）
   -> 为有意义的 episode 启动 LLM episode worker
   -> 错误触发回忆：搜索记忆中相关的历史修复
 
-PreToolUse（工具执行前）
-  -> L2 Skill Bridge：拦截对 managed 资源的 Skill() 调用
-     -> 匹配 managed 路径 → 输出内容 + mem_use() 提示
-     -> 未匹配 → 静默放行到原生 handler
-
 UserPromptSubmit（两个并行路径）
   -> [user-prompt-search.js] 通过 FTS5 + 活跃文件上下文自动搜索记忆
   -> [user-prompt-search.js] 注入相关历史观察（按时效和重要性加权）
-  -> [user-prompt-search.js] L1 Skill 自动加载：匹配 prompt 中的 managed skill 名
-     -> 加载内容 + 便携 ~ 路径 + Read() 调用指引
-     -> source="managed-skill|managed-agent", path="~/.claude-mem-lite/managed/..."
   -> [hook.mjs] 捕获用户提示文本到 user_prompts 表
   -> [hook.mjs] 递增会话提示计数器
   -> [hook.mjs] 交接：检测继续意图 → 注入上一次会话上下文
@@ -393,36 +382,6 @@ Stop
   -> 启动 LLM 摘要 worker（轮询等待）
 ```
 
-### 智能调用系统
-
-三层调用系统确保 managed 资源（`~/.claude-mem-lite/managed/` 中的 skill 和 agent）能被正确调用：
-
-```
-L1 自动加载（UserPromptSubmit，<50ms）
-  -> 匹配 prompt 中的 managed skill/agent 名称
-  -> 加载 SKILL.md / {name}.md 内容
-  -> 输出：Read("~/.claude-mem-lite/managed/.../path.md") 调用指引
-  -> 截断时提供 mem_use(name="...") 备选
-
-L2 Bridge（PreToolUse Skill hook，<30ms）
-  -> 拦截 Skill("name") 调用，查询 managed 注册表
-  -> 匹配到 → 输出内容 + mem_use() 提示（防止原生 handler 报错）
-  -> 未匹配 → 放行到原生 Skill handler
-
-L3 显式调用（mem_use MCP 工具）
-  -> 按名称精确匹配 + FTS5 模糊回退
-  -> 返回完整内容 + 便携路径供 Read() 重载
-```
-
-**调用方式区分：**
-
-| 资源类型 | 位置 | 调用方式 |
-|---------|------|---------|
-| Managed skill | `~/.claude-mem-lite/managed/skills/` | `Read("~/.../SKILL.md")` 或 `mem_use(name="...")` |
-| Managed agent | `~/.claude-mem-lite/managed/agents/` | `Read("~/.../{name}.md")` 或 `mem_use(name="...", type="agent")` |
-| 原生插件 skill | `~/.claude/plugins/cache/` | `Skill("plugin:skill-name")` |
-| 用户自建 skill | `~/.claude/skills/` | `Skill("name")` |
-
 ### Episode 编码
 
 Episode 是一批相关操作（对同一组文件的编辑），由后台 LLM worker 处理：
@@ -470,7 +429,7 @@ npx claude-mem-lite doctor            # 诊断问题
 
 ### 故障恢复（安装卡死 / hook 报错）
 
-如果你看到 PreToolUse:Read/Edit/Skill hook 报 `ERR_MODULE_NOT_FOUND`，或者 `claude-mem-lite` 命令本身因为 import 错误崩溃，多半是被部分自动更新坑了——更新器复制了新脚本但漏了配套的 `lib/*` 文件，hook 链就此断掉（连下一次本可自愈的自动更新也跑不了）。
+如果你看到 PreToolUse:Read/Edit hook 报 `ERR_MODULE_NOT_FOUND`，或者 `claude-mem-lite` 命令本身因为 import 错误崩溃，多半是被部分自动更新坑了——更新器复制了新脚本但漏了配套的 `lib/*` 文件，hook 链就此断掉（连下一次本可自愈的自动更新也跑不了）。
 
 **v2.84.0+** 提供 `repair` 子命令，从 GitHub 最新 release 重新同步：
 
@@ -548,13 +507,6 @@ claude-mem-lite/
   format-utils.mjs     # 字符串格式化：截断、类型图标、日期/时间格式化
   hash-utils.mjs       # MinHash 签名、Jaccard 相似度（去重用）
   bash-utils.mjs       # Bash 输出显著性检测：错误、测试、构建、部署
-  # 智能调度
-  dispatch.mjs         # 三级调度编排：快速过滤、上下文信号、FTS5、Haiku
-  dispatch-inject.mjs  # 注入模板渲染：skill/agent 推荐
-  registry.mjs         # 资源注册表 DB：schema、CRUD、FTS5、调用追踪
-  registry-retriever.mjs # FTS5 检索：同义词扩展与复合评分
-  registry-scanner.mjs # 文件系统扫描器：读取内容 + 哈希，委托发现层
-  resource-discovery.mjs # 共享发现层：扁平目录、插件嵌套、松散 .md 文件
   haiku-client.mjs     # 统一 Haiku LLM 封装：直连 API 或 CLI 回退
   # 安装与配置
   install.mjs          # CLI 安装器：设置、卸载、状态、诊断（npx/git clone 模式）
@@ -563,12 +515,11 @@ claude-mem-lite/
   scripts/
     setup.sh           # Setup 钩子：npm install + 迁移（隐藏目录 + 旧目录）
     post-tool-use.sh   # Bash 预过滤器：~5ms 跳过噪声，追踪 Read 路径
-    user-prompt-search.js # UserPromptSubmit 钩子：自动搜索记忆 + L1 skill 自动加载
-    pre-skill-bridge.js  # PreToolUse 钩子：L2 managed skill 桥接
+    user-prompt-search.js # UserPromptSubmit 钩子：用户提问时自动搜索记忆
     pre-tool-recall.js   # PreToolUse 钩子：Edit/Write 前文件教训回忆
+    post-tool-recall.js  # PostToolUse 钩子：工具失败后的错误召回
+    pre-agent-inject.sh  # PreToolUse 钩子：为子代理注入上下文
     prompt-search-utils.mjs # 共享逻辑：跳过模式、意图检测、名称匹配
-    convert-commands.mjs # 将 command .md 转换为托管插件中的 SKILL.md
-    index-managed.mjs  # 托管资源离线索引器
   # 测试和基准（仅开发）
   tests/               # 单元、属性、集成、契约、E2E、管线测试
   benchmark/           # BM25 搜索质量基准 + CI 门控
@@ -611,7 +562,7 @@ npm run benchmark:gate    # CI 门控：指标回退超过 5% 容差时失败
 
 | 变量 | 说明 | 默认值 |
 |------|------|--------|
-| `CLAUDE_MEM_DIR` | 自定义数据目录。所有数据库、运行时文件和托管资源均存储在此。 | `~/.claude-mem-lite/` |
+| `CLAUDE_MEM_DIR` | 自定义数据目录。所有数据库与运行时文件均存储在此。 | `~/.claude-mem-lite/` |
 | `CLAUDE_MEM_MODEL` | 后台 LLM 调用模型（Episode 提取、会话总结、调度）。可选 `haiku` 或 `sonnet`。 | `haiku` |
 | `ANTHROPIC_API_KEY` | Anthropic API key。设置后所有后台 LLM 调用直连 Anthropic Messages API（带 prompt caching），优先级最高。 | _(未设 → CLI)_ |
 | `OPENROUTER_API_KEY` | OpenRouter API key（OpenAI 兼容）。当**未设** `ANTHROPIC_API_KEY` 时用于后台 LLM 调用；两者都未设则回退到 `claude -p` CLI。 | _(未设)_ |
@@ -620,7 +571,6 @@ npm run benchmark:gate    # CI 门控：指标回退超过 5% 容差时失败
 | `MEM_QUIET_HOOKS` | 低噪声 hook。设为 `1` 时，SessionStart 注入去掉 `File Lessons` / `Key Context` 两节，`[mem] Related memories` 去掉 lesson 后缀，MCP server instructions 去掉 `WHEN TO USE` / `Decision rules` 两段。ID 与 `Recent` 表仍保留，`mem_get(ids=[…])` 可继续展开细节。适用于启用了 invited-memory adopt 流程或偏好最小化自动注入的用户。**v2.82.0 起此 env 不再阻挡 auto-adopt——如需关闭 auto-adopt 用 `MEM_NO_AUTO_ADOPT=1`。** | _(禁用)_ |
 | `MEM_NO_AUTO_ADOPT` | auto-adopt 全局关闭开关（v2.82.0+）。设为 `1` 阻止每次 SessionStart 在**所有**项目自动写入 `CLAUDE.md` 托管块。项目级关闭走 `claude-mem-lite adopt --disable`（写 `<memdir>/.mem-no-auto-adopt` 哨兵，存活于 marker 删除）。 | _(禁用)_ |
 | `MEM_NO_ADOPT_HINT` | 静音当前项目未 adopt 时 SessionStart 追加的那一行 "Invited-memory 未启用…" 提示。v2.82.1 起任何安装路径每次 SessionStart 都自动 adopt，所以该提示一般只在你显式 opt out（`MEM_NO_AUTO_ADOPT=1` 或 `claude-mem-lite adopt --disable`）的项目才会出现。 | _(禁用)_ |
-| `CLAUDE_MEM_REGISTRY_CONFINE` | 设为 `off` 允许 registry enrich 读取 `local_path` 位于托管数据目录之外的资源。**默认开启。** enrich 会读取 `resources.local_path` 指向的文件并发给 LLM；此前这道路径限制只接在四条读取路径中的一条（`mem_registry(action="enrich")`）上，`enrich <name>`、`enrich --all` 和 `import --enrich` 三条都是裸读。现在四条同门。仅当你确实把资源注册在 `CLAUDE_MEM_DIR` 之外并希望对其 enrich 时才关闭；只有精确值 `off` 会关闭它，拼错则守卫保持开启。 | _(开启)_ |
 
 ## 许可证
 

package/adopt-content.mjs

@@ -151,7 +151,6 @@ PreToolUse hook 在你 Read / Edit / Write 文件前已自动 \`mem_recall\` 该
 | 导出 JSON/JSONL | \`${CLI} export [--format jsonl]\` |
 | 统计总量 / 健康 | \`${CLI} stats [--days 30]\` |
 | 删除 / 更新某条 | \`${CLI} delete <id>[,<id>]\` · \`${CLI} update <id> [--title ...]\` |
-| skill-agent registry | \`${CLI} registry <list\\|search\\|import>\` |
 
 ## CLI 速查（常用检索）
 

package/cli/common.mjs

@@ -209,27 +209,21 @@ export const KNOWN_CLI_FLAGS = new Set([
   'age-days',
   'all',
   'anchor',
-  'batch',
   'before',
   'benchmark',
   'body',
   'branch',
-  'capability-summary',
-  'category',
   'closes-deferred',
   'concepts',
   'confirm',
   'days',
   'deep',
   'detail',
-  'domain-tags',
   'dry-run',
-  'enrich',
   'execute',
   'fields',
   'file',
   'files',
-  'floors',
   'force',
   'format',
   'from',
@@ -240,16 +234,11 @@ export const KNOWN_CLI_FLAGS = new Set([
   'importance',
   'include-compressed',
   'include-noise',
-  'intent-tags',
-  'invocation-name',
   'json',
   'key',
-  'keywords',
   'lesson',
   'lesson-learned',
   'limit',
-  'local-path',
-  'margins',
   'max',
   'memdir',
   'merge-ids',
@@ -265,9 +254,7 @@ export const KNOWN_CLI_FLAGS = new Set([
   'quality',
   'query',
   'reason',
-  'repo-url',
   'rerank',
-  'resource-type',
   'retain-days',
   'retry',
   'run',
@@ -279,16 +266,12 @@ export const KNOWN_CLI_FLAGS = new Set([
   'sort',
   'source',
   'status',
-  'sweep',
   'task',
-  'tech-stack',
   'text',
   'tier',
   'title',
   'to',
-  'trigger-patterns',
   'type',
-  'use-cases',
   'verbose',
   // Catalogued 2026-08-13 when suggestUnknownFlags started reporting EVERY unknown
   // flag: these are real, code-read flags that the old edit-distance gate happened to

package/cli.mjs

@@ -18,10 +18,7 @@ const CLI_COMMANDS = new Set([
   'maintain',
   'optimize',
   'fts-check',
-  'registry',
-  'import',
   'import-jsonl',
-  'enrich',
   'activity',
   'adopt',
   'unadopt',
@@ -29,6 +26,10 @@ const CLI_COMMANDS = new Set([
   'defer',
   'help',
 ]);
+// Removed with the skill/agent resource registry (docs/audits/20260906-145304.md).
+// Kept as a named set so a stale script or muscle-memory invocation gets the reason rather
+// than a bare "Unknown command" plus a misleading edit-distance suggestion.
+const REMOVED_COMMANDS = new Set(['registry', 'import', 'enrich']);
 const INSTALL_COMMANDS = new Set([
   'install',
   'uninstall',
@@ -95,6 +96,21 @@ if (cmd === '--version' || cmd === '-v' || cmd === '-V' || cmd === 'version') {
 } else if (INSTALL_COMMANDS.has(cmd)) {
   const { main } = await import('./install.mjs');
   await main(process.argv.slice(2));
+} else if (REMOVED_COMMANDS.has(cmd)) {
+  // Released-artifact discoverability signal for the skill-registry removal. Deliberately
+  // names NO version: this ships before the version is decided, and a hardcoded one is a
+  // guess in a third place (package.json and the CHANGELOG heading being the other two).
+  // The revert instruction is version-specific and correct, which is what a user needs.
+  // Deliberately NOT routed through the edit-distance suggester below: its nearest
+  // match for `import` is `import-jsonl`, a different feature that accepts a path
+  // argument, so a stale `import <github-url>` would be pointed at something that
+  // could plausibly run. Naming the removal is the only honest answer.
+  process.stderr.write(
+    `[mem] "${cmd}" was removed along with the skill/agent resource registry.\n` +
+      "[mem] Claude Code's own plugins/marketplace replace it. See CHANGELOG.md for the\n" +
+      '[mem] migration note; to revert, pin claude-mem-lite@4.0.4.\n',
+  );
+  process.exit(1);
 } else {
   process.stderr.write(`[mem] Unknown command: "${cmd}"\n`);
   // Suggest closest command by edit distance

package/commands/mem.md

@@ -30,9 +30,9 @@ When the user invokes `/mem`, parse their intent:
 - `/mem save <text>` → call `mem_save` MCP tool with the text as content
 - `/mem stats` → run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs stats` via Bash
 - `/mem get <ids>` → run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs get <ids>` via Bash
-- `/mem cleanup` → run `mem_maintain(action="scan")`, report pending purge count and stale items to user, ask for confirmation, then run `mem_maintain(action="execute", operations=["purge_stale"])` if confirmed
-- `/mem cleanup Nd` (e.g. `60d`) → same as above but use `retain_days=N` to only purge items older than N days
-- `/mem cleanup keep Nd` (e.g. `keep 14d`) → same as above with `retain_days=N`
+- `/mem cleanup` → run `mem_maintain(action="scan")`, report pending purge count and stale items to user, ask for confirmation, then run `mem_maintain(action="execute", operations=["purge_stale"], confirm=true)` if confirmed. **`confirm=true` is required and is not optional politeness:** without it the call returns a dry-run PREVIEW and deletes nothing, while still succeeding — so you would report a cleanup that never happened.
+- `/mem cleanup Nd` (e.g. `60d`) → same as above but add `retain_days=N` to only purge items older than N days. **`retain_days` must be between 7 and 365**; anything outside that range is rejected by the schema, so `/mem cleanup 3d` cannot be honoured — say so rather than silently substituting the default.
+- `/mem cleanup keep Nd` (e.g. `keep 14d`) → same as above with `retain_days=N`, same 7–365 range.
 - `/mem <query>` (no subcommand) → treat as search, run `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs search <query>` via Bash
 
 Use Bash commands first. For detailed data, use `node ${CLAUDE_PLUGIN_ROOT}/cli.mjs get <id>` via Bash.