claude-mem-lite 2.1.4 → 2.1.6

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -95,6 +95,7 @@ The original sends **everything to the LLM and hopes it filters well**. claude-m
 - **Exploration bonus** -- New resources in the registry get a fair chance in composite ranking; zombie resources (high recommend, zero adopt) are penalized
 - **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
 
 ## Platform Support
 
@@ -224,7 +225,7 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 
 ## Database Schema
 
-Four core tables with FTS5 virtual tables for search:
+Five core tables with FTS5 virtual tables for search:
 
 **observations** -- Individual coding observations (decisions, bugfixes, features, etc.)
 ```
@@ -250,6 +251,12 @@ started_at, completed_at, status, prompt_counter
 id, content_session_id, prompt_text, prompt_number
 ```
 
+**session_handoffs** -- Cross-session handoff snapshots (UPSERT, max 2 per project)
+```
+project, type, session_id, working_on, completed, unfinished,
+key_files, key_decisions, match_keywords, created_at_epoch
+```
+
 FTS5 indexes: `observations_fts`, `session_summaries_fts`, `user_prompts_fts`
 
 ## How It Works
@@ -258,7 +265,7 @@ FTS5 indexes: `observations_fts`, `session_summaries_fts`, `user_prompts_fts`
 
 ```
 SessionStart
-  -> Generate session ID
+  -> Generate session ID (or save handoff snapshot on /clear)
   -> Mark stale sessions (>24h active) as abandoned
   -> Clean orphaned/stale lock files
   -> Query recent observations (24h)
@@ -281,11 +288,13 @@ PreToolUse (before tool execution)
 UserPromptSubmit
   -> Capture user prompt text to user_prompts table
   -> Increment session prompt counter
+  -> Handoff: detect continuation intent → inject previous session context
   -> Dispatch: recommend skill/agent based on user's actual prompt (Tier 0→1→2)
   -> Primary dispatch point — user intent is clearest here
 
 Stop
   -> Flush final episode buffer
+  -> Save handoff snapshot (on /exit)
   -> Collect dispatch feedback: adoption detection + outcome scoring
   -> Mark session completed
   -> Spawn LLM summary worker (poll-based wait)
@@ -419,6 +428,7 @@ claude-mem-lite/
   hook.mjs             # Claude Code hooks: episode capture, error recall, session management
   hook-llm.mjs         # Background LLM workers: episode extraction, session summaries
   hook-shared.mjs      # Shared hook infrastructure: session management, DB access, LLM calls
+  hook-handoff.mjs     # Cross-session handoff: state extraction, intent detection, injection
   hook-context.mjs     # CLAUDE.md context injection and token budgeting
   hook-episode.mjs     # Episode buffer management: atomic writes, pending entry merging
   hook-semaphore.mjs   # LLM concurrency control: file-based semaphore for background workers
@@ -444,7 +454,7 @@ claude-mem-lite/
     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 (581 tests)
+  tests/               # Unit, property, integration, contract, E2E, pipeline tests (789 tests)
   benchmark/           # BM25 search quality benchmarks + CI gate
 ```
 
@@ -466,7 +476,7 @@ The benchmark suite runs as a CI gate (`npm run benchmark:gate`) to prevent sear
 
 ```bash
 npm run lint              # ESLint static analysis
-npm test                  # Run all 581 tests (vitest)
+npm test                  # Run all 789 tests (vitest)
 npm run test:smoke        # Run 5 core smoke tests
 npm run test:coverage     # Run tests with V8 coverage (≥70% lines/functions, ≥60% branches)
 npm run benchmark         # Run full search quality benchmark

package/README.zh-CN.md

@@ -95,6 +95,7 @@
 - **探索奖励** -- 注册表中的新资源在复合排名中获得公平机会；高推荐零采纳的"僵尸"资源被惩罚
 - **LLM 并发控制** -- 基于文件的信号量将后台 worker 限制为 2 个并发 LLM 调用，防止资源争用
 - **stdin 溢出保护** -- Hook 输入在 256KB 处截断，对超大工具输出使用正则挽救关键信息
+- **跨会话交接** -- 在 `/clear` 或 `/exit` 时捕获会话状态（请求、已完成工作、后续步骤、关键文件），下次会话检测到继续意图时自动注入上下文（支持显式关键词和 FTS5 术语重叠匹配）
 
 ## 平台支持
 
@@ -224,7 +225,7 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 
 ## 数据库结构
 
-四张核心表 + FTS5 虚拟表用于搜索：
+五张核心表 + FTS5 虚拟表用于搜索：
 
 **observations** -- 单条编码观察（决策、bug修复、功能等）
 ```
@@ -250,6 +251,12 @@ started_at, completed_at, status, prompt_counter
 id, content_session_id, prompt_text, prompt_number
 ```
 
+**session_handoffs** -- 跨会话交接快照（UPSERT，每个项目最多 2 行）
+```
+project, type, session_id, working_on, completed, unfinished,
+key_files, key_decisions, match_keywords, created_at_epoch
+```
+
 FTS5 索引：`observations_fts`、`session_summaries_fts`、`user_prompts_fts`
 
 ## 工作原理
@@ -258,7 +265,7 @@ FTS5 索引：`observations_fts`、`session_summaries_fts`、`user_prompts_fts`
 
 ```
 SessionStart
-  -> 生成会话 ID
+  -> 生成会话 ID（/clear 时保存交接快照）
   -> 标记过期会话（活跃 >24h）为 abandoned
   -> 清理孤儿/过期锁文件
   -> 查询最近观察（24 小时内）
@@ -281,11 +288,13 @@ PreToolUse（工具执行前）
 UserPromptSubmit
   -> 捕获用户提示文本到 user_prompts 表
   -> 递增会话提示计数器
+  -> 交接：检测继续意图 → 注入上一次会话上下文
   -> 调度：根据用户实际提示推荐 skill/agent（Tier 0→1→2）
   -> 主要调度触发点 — 用户意图在此最为明确
 
 Stop
   -> 刷新最终 episode 缓冲区
+  -> 保存交接快照（/exit 时）
   -> 收集调度反馈：采纳检测 + 结果评分
   -> 标记会话为已完成
   -> 启动 LLM 摘要 worker（轮询等待）
@@ -419,6 +428,7 @@ claude-mem-lite/
   hook.mjs             # Claude Code 钩子：episode 捕获、错误回忆、会话管理
   hook-llm.mjs         # 后台 LLM worker：episode 提取、会话摘要
   hook-shared.mjs      # 共享钩子基础设施：会话管理、数据库访问、LLM 调用
+  hook-handoff.mjs     # 跨会话交接：状态提取、意图检测、上下文注入
   hook-context.mjs     # CLAUDE.md 上下文注入与 token 预算
   hook-episode.mjs     # Episode 缓冲区管理：原子写入、待处理条目合并
   hook-semaphore.mjs   # LLM 并发控制：基于文件的信号量
@@ -444,7 +454,7 @@ claude-mem-lite/
     convert-commands.mjs # 将 command .md 转换为托管插件中的 SKILL.md
     index-managed.mjs  # 托管资源离线索引器
   # 测试和基准（仅开发）
-  tests/               # 单元、属性、集成、契约、E2E、管线测试（581 个）
+  tests/               # 单元、属性、集成、契约、E2E、管线测试（789 个）
   benchmark/           # BM25 搜索质量基准 + CI 门控
 ```
 
@@ -466,7 +476,7 @@ claude-mem-lite/
 
 ```bash
 npm run lint              # ESLint 静态分析
-npm test                  # 运行全部 581 个测试（vitest）
+npm test                  # 运行全部 789 个测试（vitest）
 npm run test:smoke        # 运行 5 个核心冒烟测试
 npm run test:coverage     # 运行测试并生成 V8 覆盖率（≥70% 行/函数，≥60% 分支）
 npm run benchmark         # 运行完整搜索质量基准测试

package/dispatch.mjs

@@ -578,7 +578,10 @@ export function needsHaikuDispatch(results) {
 
   if (results.length === 0) return true;
 
-  const topScore = Math.abs(results[0].relevance);
+  // Prefer composite_score (includes behavioral signals) over raw BM25 relevance.
+  // Both are negative (more negative = better). Use absolute values for comparison.
+  const scoreOf = r => Math.abs(r.composite_score ?? r.relevance);
+  const topScore = scoreOf(results[0]);
 
   // Relative threshold: if only one result or few results, use absolute minimum
   // For larger result sets, use mean-relative threshold
@@ -588,14 +591,14 @@ export function needsHaikuDispatch(results) {
   }
 
   // Compute mean relevance across results
-  const meanScore = results.reduce((sum, r) => sum + Math.abs(r.relevance), 0) / results.length;
+  const meanScore = results.reduce((sum, r) => sum + scoreOf(r), 0) / results.length;
 
   // Top result should be significantly above mean (at least 1.5x)
   if (topScore < meanScore * 1.5 && topScore < 3.0) return true;
 
   // Top two results too close → ambiguous, need Haiku to disambiguate
   if (results.length > 1) {
-    const gap = topScore - Math.abs(results[1].relevance);
+    const gap = topScore - scoreOf(results[1]);
     // Gap should be at least 10% of top score, or at least 0.5 absolute
     if (gap < Math.max(topScore * 0.1, 0.5)) return true;
   }
@@ -633,19 +636,19 @@ JSON: {"query":"search keywords for finding the right skill or agent","type":"sk
 // ─── Cooldown & Dedup (DB-persisted, survives process restarts) ─────────────
 
 export function isRecentlyRecommended(db, resourceId, sessionId) {
-  // Check 1: Per-session recommendation cap (avoid overwhelming user with suggestions)
+  // Check 1 & 2: Session-scoped checks (cap + dedup) — only when sessionId is available
   if (sessionId) {
     const sessionCount = db.prepare(
       'SELECT COUNT(*) as cnt FROM invocations WHERE session_id = ? AND recommended = 1'
     ).get(sessionId);
     if (sessionCount.cnt >= SESSION_RECOMMEND_CAP) return true;
-  }
 
-  // Check 2: Already recommended in this session (session dedup)
-  const sessionHit = db.prepare(
-    'SELECT 1 FROM invocations WHERE resource_id = ? AND session_id = ? LIMIT 1'
-  ).get(resourceId, sessionId);
-  if (sessionHit) return true;
+    // Already recommended in this session (session dedup)
+    const sessionHit = db.prepare(
+      'SELECT 1 FROM invocations WHERE resource_id = ? AND session_id = ? LIMIT 1'
+    ).get(resourceId, sessionId);
+    if (sessionHit) return true;
+  }
 
   // Check 3: Recommended within cooldown window (cross-session cooldown)
   const cooldownHit = db.prepare(
@@ -702,7 +705,9 @@ function applyAdoptionDecay(results) {
 
     if (multiplier === 0) return null;
     if (multiplier < 1) {
-      return { ...r, relevance: r.relevance * multiplier, _decayed: true };
+      // BM25 scores are negative (more negative = more relevant).
+      // To penalize: divide by multiplier to make less negative (worse rank).
+      return { ...r, relevance: r.relevance / multiplier, _decayed: true };
     }
     return r;
   }).filter(Boolean);
@@ -796,7 +801,13 @@ export async function dispatchOnSessionStart(db, userPrompt, sessionId) {
             limit: 3,
             projectDomains,
           });
-          if (haikuResults.length > 0) results = haikuResults;
+          if (haikuResults.length > 0) {
+            // Apply same post-processing as Tier2 to prevent zombie/low-confidence bypass
+            haikuResults = reRankByKeywords(haikuResults, signals.rawKeywords);
+            haikuResults = applyAdoptionDecay(haikuResults);
+            haikuResults = passesConfidenceGate(haikuResults, signals);
+            if (haikuResults.length > 0) results = haikuResults;
+          }
         }
       }
     }

package/hook-context.mjs

@@ -78,14 +78,13 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
     LIMIT 10
   `).all(project, now_ms - windows.sessWindow);
 
-  const now = Date.now();
   const selectedObs = [];
   const selectedSess = [];
   let totalTokens = 0;
 
   // Score each candidate: value = recency * importance, cost = tokens
   const scoredObs = obsPool.map(o => {
-    const ageDays = (now - o.created_at_epoch) / 86400000;
+    const ageDays = (now_ms - o.created_at_epoch) / 86400000;
     const recency = 1 / (1 + ageDays);
     const impBoost = 0.5 + 0.5 * (o.importance || 1);
     const value = recency * impBoost;
@@ -94,7 +93,7 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
   });
 
   const scoredSess = sessPool.map(s => {
-    const ageDays = (now - s.created_at_epoch) / 86400000;
+    const ageDays = (now_ms - s.created_at_epoch) / 86400000;
     const recency = 1 / (1 + ageDays);
     const value = recency * 1.5; // Session summaries slightly boosted
     const cost = estimateTokens((s.request || '') + (s.completed || '') + (s.next_steps || ''));

package/hook-memory.mjs

@@ -28,7 +28,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
 
     const selectStmt = db.prepare(`
       SELECT o.id, o.type, o.title, o.importance,
-             bm25(observations_fts) as relevance
+             bm25(observations_fts, 10, 5, 5, 3, 3, 2) as relevance
       FROM observations_fts
       JOIN observations o ON o.id = observations_fts.rowid
       WHERE observations_fts MATCH ?
@@ -36,7 +36,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
         AND o.importance >= 2
         AND o.created_at_epoch > ?
         AND COALESCE(o.compressed_into, 0) = 0
-      ORDER BY bm25(observations_fts)
+      ORDER BY bm25(observations_fts, 10, 5, 5, 3, 3, 2)
       LIMIT 10
     `);
     const rows = selectStmt.all(ftsQuery, project, cutoff);

package/hook-shared.mjs

@@ -26,6 +26,12 @@ export const RELATED_OBS_WINDOW_MS = 7 * 86400000;       // 7 days
 export const FALLBACK_OBS_WINDOW_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 export const RESOURCE_RESCAN_INTERVAL_MS = 60 * 60 * 1000;    // 1 hour
 
+// Handoff system constants
+export const HANDOFF_EXPIRY_CLEAR = 3600000;                   // 1 hour
+export const HANDOFF_EXPIRY_EXIT = 7 * 24 * 60 * 60 * 1000;   // 7 days
+export const HANDOFF_MATCH_THRESHOLD = 3;                       // min weighted score
+export const CONTINUE_KEYWORDS = /继续|接着|上次|之前的|前面的|刚才|\bcontinue\b|\bresume\b|\bwhere[\s\-]+we[\s\-]+left\b|\bpick[\s\-]+up\b|\bcarry[\s\-]+on\b/i;
+
 // Ensure runtime directory exists
 try { if (!existsSync(RUNTIME_DIR)) mkdirSync(RUNTIME_DIR, { recursive: true }); } catch {}
 
@@ -121,9 +127,10 @@ export function spawnBackground(bgEvent, ...extraArgs) {
 
 export function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
 
-// ─── Injection Budget (per-session, in-memory) ──────────────────────────────
-// Limits total context injections across all hooks to prevent context bloat.
-// Reset at session-start. Each hook checks before injecting.
+// ─── Injection Budget (per hook invocation, in-memory) ───────────────────────
+// Limits context injections within a single hook process to prevent context bloat.
+// Note: each hook event runs in a separate process, so this is per-invocation,
+// not per-session. Session-level dedup is handled by cooldown/sessionId checks.
 
 export const MAX_INJECTIONS_PER_SESSION = 3;
 let _injectionCount = 0;

package/hook.mjs

@@ -31,6 +31,7 @@ import {
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildDegradedTitle } from './hook-llm.mjs';
 import { searchRelevantMemories } from './hook-memory.mjs';
+import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection } from './hook-handoff.mjs';
 
 // Prevent recursive hooks from background claude -p calls
 // Background workers (llm-episode, llm-summary, resource-scan) are exempt — they're ours
@@ -318,6 +319,9 @@ async function handleStop() {
   const sessionId = getSessionId();
   const project = inferProject();
 
+  // Snapshot episode BEFORE flush for handoff extraction
+  const episodeSnapshot = readEpisodeRaw();
+
   // Flush remaining episode buffer (locked to prevent race with handlePostToolUse)
   if (acquireLock(1000)) {
     try {
@@ -340,6 +344,27 @@ async function handleStop() {
         if (episode && episode.entries && episode.entries.length > 0 && episodeHasSignificantContent(episode)) {
           if (!episode.sessionId) episode.sessionId = sessionId;
           if (!episode.project) episode.project = project;
+          // Immediate save: persist rule-based observation to DB before spawning background worker.
+          // Without this, data is lost if the background worker fails.
+          try {
+            const hasError = episode.entries.some(e => e.isError);
+            const hasEdit = episode.entries.some(e => EDIT_TOOLS.has(e.tool));
+            const inferredType = hasError ? 'bugfix' : hasEdit ? 'change' : 'discovery';
+            const fileList = (episode.files || []).map(f => basename(f)).join(', ') || '(multiple)';
+            const obs = {
+              type: inferredType,
+              title: truncate(buildDegradedTitle(episode), 120),
+              subtitle: fileList,
+              narrative: episode.entries.map(e => e.desc).join('; '),
+              concepts: [],
+              facts: [],
+              files: episode.files,
+              filesRead: episode.filesRead || [],
+              importance: computeRuleImportance(episode),
+            };
+            const id = saveObservation(obs, episode.project, episode.sessionId);
+            if (id) episode.savedId = id;
+          } catch (e) { debugCatch(e, 'handleStop-fallback-immediateSave'); }
           const flushFile = join(RUNTIME_DIR, `ep-flush-${Date.now()}-${randomUUID().slice(0, 8)}.json`);
           writeFileSync(flushFile, JSON.stringify(episode));
           spawnBackground('llm-episode', flushFile);
@@ -350,7 +375,7 @@ async function handleStop() {
     } catch (e) { debugCatch(e, 'handleStop-fallback'); }
   }
 
-  // Mark session completed (sync, instant)
+  // Mark session completed + save handoff (sync, instant)
   const db = openDb();
   if (db) {
     try {
@@ -358,6 +383,9 @@ async function handleStop() {
         UPDATE sdk_sessions SET status = 'completed', completed_at = ?, completed_at_epoch = ?
         WHERE content_session_id = ? AND status = 'active'
       `).run(new Date().toISOString(), Date.now(), sessionId);
+      // Save handoff snapshot for cross-session continuity
+      try { buildAndSaveHandoff(db, sessionId, project, 'exit', episodeSnapshot); }
+      catch (e) { debugCatch(e, 'handleStop-handoff'); }
     } finally {
       db.close();
     }
@@ -366,10 +394,11 @@ async function handleStop() {
   // Dispatch: collect feedback on recommendations using actual tool events
   // PostToolUse tracks Skill/Task/Edit/Write/Bash events in a JSONL file.
   // These events drive adoption detection (Skill/Task) and outcome detection (Edit/Bash errors).
+  // Always clear event file to prevent stale events accumulating if registry DB is unavailable.
   try {
+    const sessionEvents = readAndClearToolEvents();
     const rdb = getRegistryDb();
     if (rdb) {
-      const sessionEvents = readAndClearToolEvents();
       await collectFeedback(rdb, sessionId, sessionEvents);
     }
   } catch (e) { debugCatch(e, 'handleStop-feedback'); }
@@ -386,6 +415,9 @@ async function handleStop() {
 async function handleSessionStart() {
   resetInjectionBudget();
 
+  // Snapshot episode BEFORE flush for handoff extraction
+  const episodeSnapshot = readEpisodeRaw();
+
   // Flush any leftover episode buffer from previous session (e.g. after /clear)
   if (acquireLock()) {
     try {
@@ -464,6 +496,10 @@ async function handleSessionStart() {
     // ── Non-transactional operations (side effects, background work) ──
 
     if (prevSessionId) {
+      // Save handoff for cross-session continuity (/clear or /compact)
+      try { buildAndSaveHandoff(db, prevSessionId, prevProject || project, 'clear', episodeSnapshot); }
+      catch (e) { debugCatch(e, 'session-start-handoff'); }
+
       // Collect dispatch feedback for previous session
       try {
         const rdb = getRegistryDb();
@@ -774,6 +810,19 @@ async function handleUserPrompt() {
       now.toISOString(), now.getTime()
     );
 
+    // Cross-session handoff injection (first prompt only, before semantic memory)
+    if (counter?.prompt_counter === 1 && hasInjectionBudget()) {
+      try {
+        if (detectContinuationIntent(db, promptText, project)) {
+          const injection = renderHandoffInjection(db, project);
+          if (injection) {
+            process.stdout.write(injection + '\n');
+            incrementInjection();
+          }
+        }
+      } catch (e) { debugCatch(e, 'handleUserPrompt-handoff'); }
+    }
+
     // Semantic memory injection: search past observations for the user's prompt
     if (hasInjectionBudget()) {
       try {

package/install.mjs

@@ -1213,7 +1213,7 @@ async function install() {
   const SOURCE_FILES = [
     'server.mjs', 'server-internals.mjs', 'tool-schemas.mjs',
     'hook.mjs', 'hook-shared.mjs', 'hook-llm.mjs', 'hook-memory.mjs',
-    'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs',
+    'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs', 'hook-handoff.mjs',
     'haiku-client.mjs', 'utils.mjs', 'schema.mjs', 'package.json', 'skill.md',
     'registry.mjs', 'registry-scanner.mjs', 'registry-indexer.mjs',
     'registry-retriever.mjs', 'resource-discovery.mjs',
@@ -1581,7 +1581,7 @@ async function install() {
 async function uninstall() {
   console.log('\nclaude-mem-lite uninstaller\n');
 
-  // 1. Remove MCP
+  // 1. Remove MCP (legacy hook-based install)
   try {
     execFileSync('claude', ['mcp', 'remove', '-s', 'user', 'mem'], { stdio: 'pipe' });
     ok('MCP server removed');
@@ -1589,7 +1589,7 @@ async function uninstall() {
     warn('MCP server not found or already removed');
   }
 
-  // 2. Remove hooks (match both npx and git-clone install paths)
+  // 2. Remove hooks from settings.json (match both npx and git-clone install paths)
   const settings = readSettings();
   if (settings.hooks) {
     for (const [event, configs] of Object.entries(settings.hooks)) {
@@ -1598,11 +1598,67 @@ async function uninstall() {
       if (settings.hooks[event].length === 0) delete settings.hooks[event];
     }
     if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
-    writeSettings(settings);
-    ok('Hooks removed');
   }
 
-  // 3. Purge data if requested
+  // 3. Clean plugin system entries from settings.json
+  const pluginKey = 'claude-mem-lite@sdsrss';
+  const marketplaceKey = 'sdsrss';
+  if (settings.enabledPlugins) {
+    delete settings.enabledPlugins[pluginKey];
+  }
+  if (settings.extraKnownMarketplaces) {
+    delete settings.extraKnownMarketplaces[marketplaceKey];
+  }
+  writeSettings(settings);
+  ok('Hooks and plugin settings cleaned');
+
+  // 4. Clean plugin system registry files
+  const pluginsDir = join(homedir(), '.claude', 'plugins');
+
+  // 4a. Remove marketplace directory
+  const marketplaceDir = join(pluginsDir, 'marketplaces', marketplaceKey);
+  if (existsSync(marketplaceDir)) {
+    rmSync(marketplaceDir, { recursive: true, force: true });
+    ok('Marketplace directory removed');
+  }
+
+  // 4b. Remove cache directory
+  const cacheDir = join(pluginsDir, 'cache', marketplaceKey);
+  if (existsSync(cacheDir)) {
+    rmSync(cacheDir, { recursive: true, force: true });
+    ok('Plugin cache removed');
+  }
+
+  // 4c. Clean known_marketplaces.json
+  const knownPath = join(pluginsDir, 'known_marketplaces.json');
+  try {
+    const known = JSON.parse(readFileSync(knownPath, 'utf8'));
+    if (marketplaceKey in known) {
+      delete known[marketplaceKey];
+      writeFileSync(knownPath, JSON.stringify(known, null, 2) + '\n');
+      ok('Removed from known_marketplaces.json');
+    }
+  } catch { /* file may not exist */ }
+
+  // 4d. Clean installed_plugins.json
+  const installedPath = join(pluginsDir, 'installed_plugins.json');
+  try {
+    const installed = JSON.parse(readFileSync(installedPath, 'utf8'));
+    const plugins = installed.plugins || installed;
+    let cleaned = false;
+    for (const key of Object.keys(plugins)) {
+      if (key.includes('claude-mem-lite') || key.includes('sdsrss')) {
+        delete plugins[key];
+        cleaned = true;
+      }
+    }
+    if (cleaned) {
+      writeFileSync(installedPath, JSON.stringify(installed, null, 2) + '\n');
+      ok('Removed from installed_plugins.json');
+    }
+  } catch { /* file may not exist */ }
+
+  // 5. Purge data if requested
   if (flags.has('--purge')) {
     const expectedPurgePath = join(homedir(), '.claude-mem-lite');
     if (existsSync(DATA_DIR) && DATA_DIR === expectedPurgePath) {

package/package.json

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

package/registry-retriever.mjs

@@ -338,8 +338,9 @@ export function filterByProjectDomain(results, projectDomains) {
 // Sign convention: bm25() returns NEGATIVE (more negative = more relevant).
 // We keep the negative direction and SUBTRACT positive behavioral signals to make
 // better resources more negative. ORDER BY ... ASC puts most negative (best) first.
-const COMPOSITE_ORDER = `
-  ORDER BY (
+// Composite score expression (shared between SELECT and ORDER BY)
+// Sign convention: more negative = better. BM25 is negative, behavioral signals are subtracted.
+const COMPOSITE_EXPR = `(
     bm25(resources_fts, 5.0, 3.0, 3.0, 2.0, 2.0, 1.0, 1.0, 1.0) * 0.4
     - COALESCE(r.repo_stars * 1.0 / (r.repo_stars + 100.0), 0) * 0.15
     - (
@@ -369,23 +370,27 @@ const COMPOSITE_ORDER = `
            AND (r.adopt_count + 1.0) / (r.recommend_count + 2.0) < 0.1
         THEN 0.10
         ELSE 0 END
-  ) ASC
-`;
+  )`;
+
+// COMPOSITE_ORDER kept for SEARCH_BY_TYPE_SQL and other queries
+const COMPOSITE_ORDER = `ORDER BY ${COMPOSITE_EXPR} ASC`;
 
 const SEARCH_SQL = `
   SELECT r.*,
-    bm25(resources_fts, 5.0, 3.0, 3.0, 2.0, 2.0, 1.0, 1.0, 1.0) AS relevance
+    bm25(resources_fts, 5.0, 3.0, 3.0, 2.0, 2.0, 1.0, 1.0, 1.0) AS relevance,
+    ${COMPOSITE_EXPR} AS composite_score
   FROM resources_fts
   JOIN resources r ON r.id = resources_fts.rowid
   WHERE resources_fts MATCH ?
     AND r.status = 'active'
-  ${COMPOSITE_ORDER}
+  ORDER BY ${COMPOSITE_EXPR} ASC
   LIMIT ?
 `;
 
 const SEARCH_BY_TYPE_SQL = `
   SELECT r.*,
-    bm25(resources_fts, 5.0, 3.0, 3.0, 2.0, 2.0, 1.0, 1.0, 1.0) AS relevance
+    bm25(resources_fts, 5.0, 3.0, 3.0, 2.0, 2.0, 1.0, 1.0, 1.0) AS relevance,
+    ${COMPOSITE_EXPR} AS composite_score
   FROM resources_fts
   JOIN resources r ON r.id = resources_fts.rowid
   WHERE resources_fts MATCH ?

package/schema.mjs

@@ -74,6 +74,20 @@ const CORE_SCHEMA = `
     created_at_epoch INTEGER NOT NULL,
     FOREIGN KEY(content_session_id) REFERENCES sdk_sessions(content_session_id) ON DELETE CASCADE ON UPDATE CASCADE
   );
+
+  CREATE TABLE IF NOT EXISTS session_handoffs (
+    project TEXT NOT NULL,
+    type TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    working_on TEXT,
+    completed TEXT,
+    unfinished TEXT,
+    key_files TEXT,
+    key_decisions TEXT,
+    match_keywords TEXT,
+    created_at_epoch INTEGER,
+    PRIMARY KEY (project, type)
+  );
 `;
 
 // Column migrations (idempotent — only swallow "duplicate column" errors)

package/server.mjs

@@ -939,6 +939,12 @@ server.registerTool(
         const narrative = obs.map(o => `- ${o.title || '(untitled)'}`).join('\n');
         const sessionId = obs[0].project ? `compress-${obs[0].project}` : 'compress-manual';
 
+        // Use median timestamp of compressed observations instead of now,
+        // so the summary appears at the correct position in timeline/recency scoring.
+        const sortedEpochs = obs.map(o => o.created_at_epoch).sort((a, b) => a - b);
+        const medianEpoch = sortedEpochs[Math.floor(sortedEpochs.length / 2)];
+        const medianDate = new Date(medianEpoch);
+
         // Ensure session exists (INSERT OR IGNORE avoids race condition)
         const now = new Date();
         db.prepare(`
@@ -948,7 +954,7 @@ server.registerTool(
 
         const summaryResult = insertSummary.run(
           sessionId, proj, narrative, dominantType, title, narrative,
-          now.toISOString(), now.getTime()
+          medianDate.toISOString(), medianEpoch
         );
         const summaryId = Number(summaryResult.lastInsertRowid);
 

package/utils.mjs

@@ -676,3 +676,63 @@ export function parseJsonFromLLM(text) {
   if (obj) try { return JSON.parse(obj[0]); } catch {}
   return null;
 }
+
+// ─── Handoff Utilities ──────────────────────────────────────────────────────
+
+/** Stop words for handoff keyword extraction (broader than ERROR_STOP_WORDS). */
+export const HANDOFF_STOP_WORDS = new Set([
+  'the', 'and', 'for', 'that', 'this', 'with', 'from', 'are', 'was', 'were',
+  'been', 'have', 'has', 'had', 'does', 'did', 'will', 'would', 'should', 'could',
+  'can', 'may', 'must', 'not', 'but', 'its', 'all', 'any', 'each', 'some',
+  'into', 'over', 'after', 'before', 'between', 'about', 'also', 'just', 'then',
+  'than', 'when', 'where', 'how', 'what', 'which', 'who', 'why', 'here', 'there',
+  'more', 'very', 'only', 'still', 'now', 'new', 'old', 'get', 'got', 'set',
+  'true', 'false', 'null', 'undefined', 'function', 'return', 'const', 'let', 'var',
+  'import', 'export', 'default', 'class', 'async', 'await', 'try', 'catch',
+]);
+
+/**
+ * Tokenize text for handoff keyword matching.
+ * Splits on whitespace/punctuation, lowercases, filters short tokens.
+ * @param {string} text Input text
+ * @returns {string[]} Array of lowercase tokens (length >= 3)
+ */
+export function tokenizeHandoff(text) {
+  if (!text) return [];
+  return text
+    .split(/[\s,;:.()[\]{}'"`<>→|/\\#@!?=+*&^%$~]+/)
+    .map(w => w.toLowerCase().replace(/^[.\-]+|[.\-]+$/g, ''))
+    .filter(w => w.length >= 3);
+}
+
+/**
+ * Check if a token is a "specific" term (file name, identifier, etc.)
+ * that should get double weight in intent matching.
+ * @param {string} token Lowercase token
+ * @returns {boolean}
+ */
+export function isSpecificTerm(token) {
+  if (!token || token.length < 3) return false;
+  if (token.includes('_') || token.includes('-')) return true;
+  if (HANDOFF_STOP_WORDS.has(token)) return false;
+  return token.length >= 4 && !/^\d+$/.test(token);
+}
+
+/**
+ * Extract match keywords from text and file paths for handoff intent matching.
+ * @param {string} text Combined text from prompts, observations, etc.
+ * @param {string[]} files Array of file paths
+ * @returns {string} Space-separated keywords
+ */
+export function extractMatchKeywords(text, files) {
+  const terms = new Set();
+  for (const f of files) {
+    const base = basename(f).replace(/\.[^.]+$/, '');
+    if (base.length >= 3) terms.add(base.toLowerCase());
+  }
+  const words = tokenizeHandoff(text);
+  for (const w of words) {
+    if (!HANDOFF_STOP_WORDS.has(w)) terms.add(w);
+  }
+  return [...terms].join(' ');
+}