claude-mem-lite 2.26.0 → 2.28.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.26.0",
+      "version": "2.28.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.26.0",
+  "version": "2.28.1",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -90,6 +90,7 @@ The original sends **everything to the LLM and hopes it filters well**. claude-m
 - **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
 - **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
 - **OR query fallback** -- When AND-joined FTS5 queries return zero results, automatically relaxes to OR-joined queries for broader recall (applied in both user-prompt-search and hook-memory paths)
@@ -154,7 +155,7 @@ 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` server with 15 tools (search, recent, recall, timeline, get, save, update, stats, delete, compress, maintain, export, fts_check, browse, registry)
+2. **Register MCP server** -- `mem` server with 16 tools (search, recent, recall, timeline, get, save, update, stats, delete, compress, maintain, export, fts_check, browse, registry, use)
 3. **Configure hooks** -- `PostToolUse`, `SessionStart`, `Stop`, `UserPromptSubmit` lifecycle hooks
 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
@@ -195,8 +196,8 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
     ep-flush-*.json      # Flushed episodes awaiting processing
     reads-<project>.txt  # Read file paths (collected on flush)
   managed/
-    skills/              # Standalone skills (flat layout)
-    agents/              # Agent plugins (nested: agents/*.md + skills/*/SKILL.md)
+    skills/              # Standalone skills: {name}/SKILL.md
+    agents/              # Agent plugins: {group}/agents/{name}.md + skills/*/SKILL.md
     repos/               # Shallow-cloned source repos
 ```
 
@@ -220,7 +221,8 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 | `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. |
+| `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()`. |
 
 ### Skill Commands (in Claude Code chat)
 
@@ -323,6 +325,9 @@ 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
@@ -346,6 +351,15 @@ Registry pipeline:
   -> 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.
@@ -466,7 +480,10 @@ 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 on user prompts
+    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
+    pre-tool-recall.js   # PreToolUse hook: file lesson recall before Edit/Write
+    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)

package/README.zh-CN.md

@@ -79,13 +79,11 @@
 - **原子写入** -- 所有文件写入（episode、CLAUDE.md）使用 write-to-tmp + rename 防止崩溃时损坏
 - **健壮锁机制** -- PID 感知的锁文件，自动清理过期（>30s）或孤儿（PID 已死）锁
 - **过期会话清理** -- 活跃超过 24 小时的会话在下次启动时自动标记为 abandoned
-- **智能调度** -- 三级渐进式调度系统，在 SessionStart、UserPromptSubmit、PreToolUse 三个时机自动推荐最合适的 skill 或 agent
-- **资源注册表** -- 对已安装的 skill 和 agent 建立 FTS5 索引，支持复合评分和调用追踪
+- **智能调用** -- 三层调用系统：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` 文件
-- **闭环反馈** -- 追踪推荐是否被采纳、会话是否成功，持续改进调度质量
-- **双语意图识别** -- 同时理解中文和英文用户意图（15+ 英文 + 12+ 中文意图类别）
-- **领域同义词扩展** -- 调度查询自动扩展领域同义词（如 "修复" → fix, debug, bugfix, repair, error）
-- **持久化冷却机制** -- 5 分钟跨会话冷却 + 同会话去重，避免重复推荐
+- **领域同义词扩展** -- 注册表搜索查询自动扩展领域同义词（如 "修复" → fix, debug, bugfix, repair, error）
+- **持久化冷却机制** -- 5 分钟跨会话冷却 + 同会话去重，避免重复推荐 skill 自动加载
 - **双模式 LLM 调用** -- 自动检测 `ANTHROPIC_API_KEY` 直连 API；无 key 时回退到 `claude -p` CLI
 - **Haiku 熔断器** -- 连续 3 次 LLM 失败后，禁用 Haiku 调度 5 分钟，防止级联延迟
 - **否定意图感知** -- 正确处理 "不要测试了，先修 bug" 等复杂提示，排除被否定的意图，支持中英文混合输入
@@ -185,8 +183,8 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
     ep-flush-*.json      # 已刷新的 episode，等待处理
     reads-<project>.txt  # Read 文件路径（刷新时收集）
   managed/
-    skills/              # 独立 skill（扁平布局）
-    agents/              # Agent 插件（嵌套：agents/*.md + skills/*/SKILL.md）
+    skills/              # 独立 skill：{name}/SKILL.md
+    agents/              # Agent 插件：{group}/agents/{name}.md + skills/*/SKILL.md
     repos/               # 浅克隆的源代码仓库
 ```
 
@@ -210,7 +208,8 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 | `mem_export` | 导出观察为 JSON 或 JSONL 格式，支持按项目、类型、日期范围过滤。 |
 | `mem_fts_check` | 检查 FTS5 索引完整性或重建索引。搜索结果异常或数据库恢复后使用。 |
 | `mem_browse` | 分层记忆仪表盘。按记忆层级（working/active/archive）分组展示观察。 |
-| `mem_registry` | 管理资源注册表：按需搜索技能/代理、列表、统计、导入/移除、重索引。 |
+| `mem_registry` | 管理资源注册表：按需搜索技能/代理、列表、统计、导入/移除、重索引。搜索结果区分 managed（Read 路径）和 native（Skill 全名）调用方式。 |
+| `mem_use` | 从 managed 注册表加载 skill 或 agent。返回完整内容 + `~` 便携路径供 `Read()` 重载。 |
 
 ### 技能命令（在 Claude Code 聊天中使用）
 
@@ -280,7 +279,6 @@ SessionStart
   -> 清理孤儿/过期锁文件
   -> 查询最近观察（24 小时内）
   -> 注入上下文到 CLAUDE.md + 标准输出
-  -> 调度：根据用户提示推荐 skill/agent（Tier 0→1→2→3）
 
 PostToolUse（每次工具执行）
   -> Bash 预过滤器 ~5ms 跳过噪声（Read 路径追踪到 reads 文件）
@@ -293,74 +291,57 @@ PostToolUse（每次工具执行）
   -> 错误触发回忆：搜索记忆中相关的历史修复
 
 PreToolUse（工具执行前）
-  -> 调度：根据当前操作上下文推荐 skill/agent（Tier 0→1→2）
-
-UserPromptSubmit
-  -> 捕获用户提示文本到 user_prompts 表
-  -> 递增会话提示计数器
-  -> 交接：检测继续意图 → 注入上一次会话上下文
-  -> 调度：根据用户实际提示推荐 skill/agent（Tier 0→1→2）
-  -> 主要调度触发点 — 用户意图在此最为明确
+  -> 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] 交接：检测继续意图 → 注入上一次会话上下文
+  -> [hook.mjs] 语义记忆注入（hook-memory.mjs），通过临时文件去重
 
 Stop
   -> 刷新最终 episode 缓冲区
   -> 保存交接快照（/exit 时）
-  -> 收集调度反馈：采纳检测 + 结果评分
   -> 标记会话为已完成
   -> 启动 LLM 摘要 worker（轮询等待）
 ```
 
-### 智能调度系统
+### 智能调用系统
 
-调度系统在编码会话中主动推荐合适的 skill 和 agent，采用三级渐进式架构：
+三层调用系统确保 managed 资源（`~/.claude-mem-lite/managed/` 中的 skill 和 agent）能被正确调用：
 
 ```
-Tier 0：快速过滤（<1ms）
-  -> 跳过只读工具（Read、Glob、Grep、LSP...）
-  -> 跳过简单 Bash 查询（ls、cat、git status...）
-  -> 跳过 Claude 已选择 Skill 或 Task agent 的情况
-  -> 跳过 MCP 内部工具
-
-Tier 1：上下文信号提取（<1ms）
-  -> 意图：从用户提示提取（测试、修复、部署、审查...）
-  -> 技术栈：从最近文件扩展名推断（.ts → typescript）
-  -> 动作：从工具名推断（Edit → edit, Bash+jest → test）
-  -> 错误领域：分类错误（type-error, test-fail, build-fail...）
+L1 自动加载（UserPromptSubmit，<50ms）
+  -> 匹配 prompt 中的 managed skill/agent 名称
+  -> 加载 SKILL.md / {name}.md 内容
+  -> 输出：Read("~/.claude-mem-lite/managed/.../path.md") 调用指引
+  -> 截断时提供 mem_use(name="...") 备选
 
-Tier 2：FTS5 检索（<5ms）
-  -> 用领域同义词扩展信号（15+ 英文、12+ 中文类别）
-  -> BM25 排名搜索资源注册表
-  -> 复合评分：BM25（40%）+ 仓库星标（15%）+ 成功率（15%）+ 采纳率（10%）
+L2 Bridge（PreToolUse Skill hook，<30ms）
+  -> 拦截 Skill("name") 调用，查询 managed 注册表
+  -> 匹配到 → 输出内容 + mem_use() 提示（防止原生 handler 报错）
+  -> 未匹配 → 放行到原生 Skill handler
 
-Tier 3：Haiku 语义调度（~500ms，仅 SessionStart）
-  -> 当 FTS5 置信度低或前几名结果分数接近时激活
-  -> LLM 生成语义搜索查询以精细化检索
-  -> PreToolUse 禁用（2 秒 hook 超时不够）
+L3 显式调用（mem_use MCP 工具）
+  -> 按名称精确匹配 + FTS5 模糊回退
+  -> 返回完整内容 + 便携路径供 Read() 重载
 ```
 
-**调度触发点：**
-
-| Hook | 时间预算 | 层级 | 用途 |
-|------|---------|------|------|
-| SessionStart | 10s | 0→1→2→3 | 分析上次会话的 next_steps，提前推荐 skill/agent |
-| UserPromptSubmit | 2s | 0→1→2 | 主要调度触发点 — 用户实际提示意图最明确 |
-| PreToolUse | 2s | 0→1→2 | 根据当前操作上下文实时推荐 |
-
-**反馈闭环（Stop hook）：**
-
-会话结束时，系统回顾本次会话中所有推荐：
-- **采纳检测** -- Claude 是否实际使用了推荐的 skill（`Skill` 工具）或 agent（`Task` 工具）？
-- **结果检测** -- 会话是否成功（有编辑无报错）、部分成功（报错后修复）、还是失败？
-- **评分计算** -- 采纳 + 成功 = 1.0，采纳 + 部分 = 0.5，采纳 + 失败 = 0.2
-- 统计数据回流到复合评分，持续改进调度质量
-
-**注入模板：**
+**调用方式区分：**
 
-| 资源类型 | 位置 | 模板 |
-|---------|------|------|
-| Skill | `~/.claude/skills/`（原生） | 简短提示：使用 `/skill <name>` |
-| Skill | 托管目录 | 注入完整 skill 内容（最大 3KB） |
-| Agent | 任意 | 注入 agent 定义，用于 `Task` 工具委托 |
+| 资源类型 | 位置 | 调用方式 |
+|---------|------|---------|
+| 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 编码
 
@@ -464,7 +445,6 @@ claude-mem-lite/
   # 智能调度
   dispatch.mjs         # 三级调度编排：快速过滤、上下文信号、FTS5、Haiku
   dispatch-inject.mjs  # 注入模板渲染：skill/agent 推荐
-  dispatch-feedback.mjs # 闭环反馈：采纳检测、结果追踪
   registry.mjs         # 资源注册表 DB：schema、CRUD、FTS5、调用追踪
   registry-retriever.mjs # FTS5 检索：同义词扩展与复合评分
   registry-scanner.mjs # 文件系统扫描器：读取内容 + 哈希，委托发现层
@@ -477,6 +457,10 @@ 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 桥接
+    pre-tool-recall.js   # PreToolUse 钩子：Edit/Write 前文件教训回忆
+    prompt-search-utils.mjs # 共享逻辑：跳过模式、意图检测、名称匹配
     convert-commands.mjs # 将 command .md 转换为托管插件中的 SKILL.md
     index-managed.mjs  # 托管资源离线索引器
   # 测试和基准（仅开发）

package/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'fts-check', 'registry', 'help']);
+const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'fts-check', 'registry', 'import', 'enrich', 'help']);
 const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'release']);
 
 const cmd = process.argv[2];

package/commands/mem.md

@@ -1,5 +1,5 @@
 ---
-description: Search and manage project memory (observations, sessions, prompts)
+description: "Search and manage project memory (observations, sessions, prompts). Use when: user asks about past work, wants to find a previous bugfix, check project history, save a decision, or manage stored memories"
 ---
 
 # Memory

package/commands/memory.md

@@ -1,5 +1,5 @@
 ---
-description: Save content to memory — with explicit content, instructions, or auto-summarize current session
+description: "Save content to memory — with explicit content, instructions, or auto-summarize current session. Use when: the user asks to remember something, after solving a non-obvious problem, or to capture key session findings"
 ---
 
 # Memory Save

package/commands/recall.md

@@ -1,5 +1,5 @@
 ---
-description: Recall past observations for a file before editing
+description: "Recall past observations for a file before editing. Use when: about to edit a file, investigating a file with past issues, or before refactoring to check for past lessons"
 argument-hint: <file_path>
 ---
 

package/commands/recent.md

@@ -1,5 +1,5 @@
 ---
-description: Show recent memory observations
+description: "Show recent memory observations. Use when: checking what happened recently, reviewing session progress, or verifying recent changes were captured"
 argument-hint: [count]
 ---
 

package/commands/search.md

@@ -1,5 +1,5 @@
 ---
-description: Search memory for past bugfixes, decisions, discoveries
+description: "Search memory for past bugfixes, decisions, discoveries. Use when: encountering a familiar error, investigating a module before changes, or looking for prior solutions to a similar problem"
 argument-hint: <query>
 ---
 

package/commands/timeline.md

@@ -1,5 +1,5 @@
 ---
-description: Browse memory timeline around an observation
+description: "Browse memory timeline around an observation. Use when: exploring what happened before/after a specific event, understanding the sequence of changes that led to a bug, or reviewing chronological context"
 argument-hint: <observation_id>
 ---
 

package/commands/tools.md

@@ -1,5 +1,5 @@
 ---
-description: Import skills and agents from GitHub repositories into the tool resource registry
+description: "Import skills and agents from GitHub repositories into the tool resource registry. Use when: looking for a skill to solve a problem, importing tools from a repo, or managing installed tools"
 ---
 
 # Tool Import
@@ -19,25 +19,14 @@ When the user invokes `/mem:tools`:
 
 ### With GitHub URL
 
-1. Use WebFetch to fetch the repository README and skill/agent files:
-   - Try `https://raw.githubusercontent.com/{owner}/{repo}/main/README.md`
-   - Look for skill definitions (`.md` files with frontmatter), agent definitions, plugin.json
-   - If the repo has a `commands/` directory, fetch skill files from there
-2. Identify all skills and agents in the repository
-3. For each tool found, extract metadata using your understanding of the content:
-   - `name`: tool name (lowercase, hyphenated)
-   - `resource_type`: "skill" or "agent"
-   - `repo_url`: the GitHub URL
-   - `intent_tags`: comma-separated intent keywords (what the tool helps with)
-   - `domain_tags`: comma-separated technology/domain tags
-   - `capability_summary`: one-line description of what the tool does
-   - `trigger_patterns`: when to recommend this tool (natural language)
-   - `keywords`: additional search terms
-   - `tech_stack`: technology stack tags
-   - `use_cases`: usage scenarios
-4. Call `mem_registry(action="import", ...)` for each tool with extracted metadata
-5. Call `mem_registry(action="reindex")` to update FTS5 index
-6. Report imported tools in a table format
+1. Call `mem_registry(action="import_url", url="<github-url>", enrich=true)` to import all skills/agents
+2. The import pipeline automatically:
+   - Fetches repo file tree via GitHub API
+   - Discovers SKILL.md/AGENT.md files
+   - Parses frontmatter and extracts metadata
+   - Downloads files to managed/ directory
+   - Runs LLM enrichment for semantic tags (when enrich=true)
+3. Report imported tools in a table format
 
 ### With GitHub URL + instructions
 

package/commands/update.md

@@ -1,5 +1,5 @@
 ---
-description: Auto-maintain memory and resource registry — deduplicate, merge, decay, cleanup, reindex
+description: "Auto-maintain memory and resource registry — deduplicate, merge, decay, cleanup, reindex. Use when: search results seem noisy, after bulk imports, or during periodic maintenance"
 ---
 
 # Memory & Registry Maintenance

package/hook-handoff.mjs

@@ -2,7 +2,7 @@
 // Extracted for testability — hook.mjs has module-level side effects
 
 import { basename } from 'path';
-import { truncate, extractMatchKeywords, tokenizeHandoff, isSpecificTerm } from './utils.mjs';
+import { truncate, extractMatchKeywords, tokenizeHandoff, isSpecificTerm, LOW_SIGNAL_TITLE } from './utils.mjs';
 import {
   HANDOFF_EXPIRY_CLEAR, HANDOFF_EXPIRY_EXIT, HANDOFF_MATCH_THRESHOLD, CONTINUE_KEYWORDS,
 } from './hook-shared.mjs';
@@ -78,7 +78,6 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   }
 
   // 5. Key decisions — high importance observations (skip low-signal degraded titles)
-  const LOW_SIGNAL_TITLE = /^(Error (while working|in)|Modified |Worked on |Reviewed \d+ files:)/;
   const decisions = db.prepare(`
     SELECT title FROM observations
     WHERE memory_session_id = ? AND COALESCE(importance, 1) >= 2

package/hook-llm.mjs

@@ -6,7 +6,7 @@ import { existsSync, readFileSync, unlinkSync, readdirSync } from 'fs';
 import {
   jaccardSimilarity, truncate, clampImportance, computeRuleImportance,
   inferProject, parseJsonFromLLM,
-  computeMinHash, estimateJaccardFromMinHash, cjkBigrams, EDIT_TOOLS, debugCatch, debugLog, OBS_BM25,
+  computeMinHash, estimateJaccardFromMinHash, cjkBigrams, EDIT_TOOLS, LOW_SIGNAL_TITLE, debugCatch, debugLog, OBS_BM25,
   getCurrentBranch,
 } from './utils.mjs';
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
@@ -24,7 +24,25 @@ function buildFtsTextField(obs) {
   const factsText = Array.isArray(obs.facts) ? obs.facts.join(' ') : '';
   const aliasesText = obs.searchAliases || '';
   const bigramText = cjkBigrams((obs.title || '') + ' ' + (obs.narrative || ''));
-  return { conceptsText, factsText, textField: [conceptsText, factsText, aliasesText, bigramText].filter(Boolean).join(' ') };
+
+  // Degraded fallback: when LLM enrichment is missing, extract lightweight keywords
+  // from title + narrative so degraded observations remain FTS-searchable
+  let fallbackText = '';
+  if (!conceptsText && !factsText && !aliasesText) {
+    const raw = (obs.title || '') + ' ' + (obs.narrative || '');
+    // Extract file basenames (without extension) as searchable terms
+    const fileNames = [...new Set(
+      [...raw.matchAll(/\b([\w.-]+\.(?:mjs|js|ts|tsx|jsx|py|rs|go|vue|css|html|json|yaml|yml|md|sh|sql|toml|cfg))\b/g)]
+        .map(m => m[1].replace(/\.[^.]+$/, ''))
+    )];
+    // Extract error keywords from "→ ERROR: ..." patterns
+    const errorTerms = raw.split(/→ ERROR[: ]+/).slice(1)
+      .map(s => s.split(/[;{[\]"\\|→\n]/)[0].trim())
+      .filter(t => t.length >= 4 && t.length <= 50);
+    fallbackText = [...fileNames, ...errorTerms].join(' ');
+  }
+
+  return { conceptsText, factsText, textField: [conceptsText, factsText, aliasesText, bigramText, fallbackText].filter(Boolean).join(' ') };
 }
 
 /**
@@ -63,7 +81,7 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
     // "Error in X", "Modified X" titles are low-specificity → use longer dedup window
     // 7-day exact match prevents cross-day accumulation of "Modified package.json" noise;
     // 3-day Jaccard catches near-duplicates without blocking legitimately new observations
-    const LOW_SIGNAL = /^(Error (while working|in)|Error: |Modified |Worked on |Reviewed \d+ files:|# |node |npm |npx |\(no description\)|\(error\)$)/;
+    const LOW_SIGNAL = LOW_SIGNAL_TITLE;
     if (obs.title && LOW_SIGNAL.test(obs.title)) {
       const sevenDaysAgo = now.getTime() - 7 * 86400000;
       const threeDaysAgo = now.getTime() - 3 * 86400000;
@@ -244,8 +262,14 @@ export function buildDegradedTitle(episode) {
       // Extract meaningful error text from "cmd → ERROR: ..." format
       const errMatch = errEntry.desc.match(/→ ERROR: (.{3,80})/);
       if (errMatch) {
-        // Clean JSON/noise from the error snippet
-        const cleaned = errMatch[1].replace(/[{"[\]]/g, '').replace(/\\n/g, ' ').trim();
+        // Clean JSON/noise/tabs/CI-status from the error snippet
+        const cleaned = errMatch[1]
+          .replace(/\t/g, ' ')
+          .replace(/[{"[\]]/g, '')
+          .replace(/\\n/g, ' ')
+          .replace(/\b(?:in_progress|completed|queued|failure|success|waiting)\b/gi, '')
+          .replace(/\s{2,}/g, ' ')
+          .trim();
         if (cleaned.length >= 4) errorHint = `: ${truncate(cleaned, 50)}`;
       }
     }
@@ -266,8 +290,11 @@ export function buildDegradedTitle(episode) {
   }
   // No files: strip raw output (JSON, arrays, long tails) from Bash descriptions
   const desc = episode.entries[0]?.desc || '(no description)';
-  return desc.replace(/ → (?:ERROR: )?[\[{].*$/, hasError ? ' (error)' : '')
-    .replace(/ → .*---EXIT:\d+$/, hasError ? ' (error)' : '');
+  return desc.replace(/ → (?:ERROR: )?[[{].*$/, hasError ? ' (error)' : '')
+    .replace(/ → .*---EXIT:\d+$/, hasError ? ' (error)' : '')
+    .replace(/\t/g, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
 }
 
 /**
@@ -301,7 +328,7 @@ export function buildImmediateObservation(episode) {
   const ruleImportance = computeRuleImportance(episode);
   // Low-signal degraded titles ("Error in...", "Modified...") should not inflate importance.
   // Cap at 1 unless rule-based signals indicate genuine importance (error-in-test → 3, config → 2).
-  const LOW_SIGNAL = /^(Error (while working|in)|Error: |Modified |Worked on |Reviewed \d+ files:|# |node |npm |npx |\(no description\)|\(error\)$)/;
+  const LOW_SIGNAL = LOW_SIGNAL_TITLE;
   const isLowSignal = LOW_SIGNAL.test(title);
   let importance;
   if (isReviewPattern) {

package/hook-memory.mjs

@@ -14,7 +14,7 @@ const MAX_FILE_RECALL = 2;
 
 /**
  * Search for relevant past observations to inject as memory context.
- * Quality gates: importance>=1 (with 0.6x penalty), type-boosted, lesson-boosted, BM25-thresholded (>=1.5).
+ * Quality gates: importance>=1 (with 0.6x penalty), type-boosted, lesson-boosted, BM25-thresholded (adaptive: 0 for <5 obs, 1.5 otherwise).
  * @param {import('better-sqlite3').Database} db Memory database
  * @param {string} userPrompt User's prompt text
  * @param {string} project Current project
@@ -101,8 +101,14 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       })
       .sort((a, b) => b.score - a.score);
 
-    // Strict threshold: raised from 1.0 to 1.5 to compensate for wider pool
-    if (scored.length === 0 || scored[0].score < 1.5) return [];
+    // Adaptive threshold: BM25 IDF collapses when corpus has <5 observations,
+    // producing scores ~0.00001 even for exact matches. At 5+ obs, IDF provides
+    // meaningful discrimination and the calibrated 1.5 threshold works well.
+    const obsCount = db.prepare(
+      'SELECT COUNT(*) as c FROM observations WHERE project = ? AND COALESCE(compressed_into, 0) = 0',
+    ).get(project)?.c || 0;
+    const threshold = obsCount < 5 ? 0 : 1.5;
+    if (scored.length === 0 || scored[0].score < threshold) return [];
 
     // Update access_count for injected memories
     const result = scored.slice(0, MAX_MEMORY_INJECTIONS);

package/hook.mjs

@@ -169,7 +169,7 @@ async function handlePostToolUse() {
   // Build episode entry
   const entry = {
     tool: tool_name,
-    desc: scrubSecrets(makeEntryDesc(tool_name, toolInput, resp)),
+    desc: scrubSecrets(makeEntryDesc(tool_name, toolInput, resp, bashSig)),
     files,
     ts: Date.now(),
     isError: bashSig?.isError || false,
@@ -517,6 +517,24 @@ async function handleSessionStart() {
         `).run();
         if (boosted.changes > 0) debugLog('DEBUG', 'auto-maintain', `boosted ${boosted.changes} frequently-accessed observations`);
 
+        // Auto-dedup: merge near-identical observations (same title, same project, within 1h)
+        const dupPairs = db.prepare(`
+          SELECT a.id as keep_id, b.id as remove_id
+          FROM observations a
+          JOIN observations b ON a.title = b.title AND a.project = b.project
+            AND a.id < b.id
+            AND ABS(a.created_at_epoch - b.created_at_epoch) < 3600000
+            AND COALESCE(a.compressed_into, 0) = 0
+            AND COALESCE(b.compressed_into, 0) = 0
+          LIMIT 20
+        `).all();
+        if (dupPairs.length > 0) {
+          const removeIds = dupPairs.map(p => p.remove_id);
+          const ph = removeIds.map(() => '?').join(',');
+          db.prepare(`UPDATE observations SET superseded_at = ?, superseded_by = 'auto-dedup' WHERE id IN (${ph})`).run(Date.now(), ...removeIds);
+          debugLog('DEBUG', 'auto-maintain', `auto-deduped ${dupPairs.length} near-identical observations`);
+        }
+
         // Mark maintenance as done (24h gate) — even though compression runs in background
         writeFileSync(maintainFile, JSON.stringify({ epoch: Date.now() }));
         // Weekly summary grouping runs in background to avoid blocking SessionStart

package/hooks/hooks.json

@@ -28,6 +28,16 @@
             "timeout": 3
           }
         ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-skill-bridge.js\"",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "PostToolUse": [