claude-mem-lite 2.20.0 → 2.23.1

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -154,7 +154,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 12 tools (search, timeline, get, save, update, stats, delete, compress, maintain, registry, export, fts_check)
+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)
 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
@@ -207,6 +207,8 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 | Tool | Description |
 |------|-------------|
 | `mem_search` | FTS5 full-text search with BM25 ranking. Filters by type, project, date range, importance level. |
+| `mem_recent` | Show most recent observations, ordered by time. Quick snapshot of latest activity. |
+| `mem_recall` | Recall observations related to a file. Use before editing to surface past bugfixes and context. |
 | `mem_timeline` | Browse observations chronologically around an anchor point. |
 | `mem_get` | Retrieve full details for specific observation IDs (includes importance and related_ids). |
 | `mem_save` | Manually save a memory/observation. |
@@ -217,6 +219,7 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 | `mem_maintain` | Memory maintenance: scan for duplicates/stale/broken items, then execute cleanup/dedup/rebuild_vectors operations. |
 | `mem_export` | Export observations as JSON or JSONL for backup or migration. Filters by project, type, date range. |
 | `mem_fts_check` | Check FTS5 index integrity or rebuild indexes. Use when search results seem wrong or after DB recovery. |
+| `mem_browse` | Tier-grouped memory dashboard. Shows observations organized by memory tier (working/active/archive). |
 | `mem_registry` | Manage resource registry: search for skills/agents by need, list resources, view stats, import/remove tools, reindex. |
 
 ### Skill Commands (in Claude Code chat)
@@ -224,9 +227,11 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
 ```
 /mem search <query>        # Full-text search across all memories
 /mem recent [n]            # Show recent N observations (default 10)
+/mem recall <file>         # Show past observations for a file
 /mem save <text>           # Save a manual memory/note
 /mem stats                 # Show memory statistics
 /mem timeline <query>      # Browse timeline around a match
+/mem browse                # Tier-grouped memory dashboard
 /mem <query>               # Shorthand for search
 ```
 

package/README.zh-CN.md

@@ -144,7 +144,7 @@ node install.mjs install
 ### 安装过程
 
 1. **安装依赖** -- `npm install --omit=dev`（编译原生 `better-sqlite3`）
-2. **注册 MCP 服务器** -- `mem` 服务器，包含 12 个工具（search、timeline、get、save、update、stats、delete、compress、maintain、registry、export、fts_check）
+2. **注册 MCP 服务器** -- `mem` 服务器，包含 15 个工具（search、recent、recall、timeline、get、save、update、stats、delete、compress、maintain、export、fts_check、browse、registry）
 3. **配置钩子** -- `PostToolUse`、`PreToolUse`、`SessionStart`、`Stop`、`UserPromptSubmit` 生命周期钩子
 4. **创建数据目录** -- `~/.claude-mem-lite/`（隐藏目录），存放数据库、运行时和托管资源文件
 5. **自动迁移** -- 自动检测 `~/.claude-mem/`（原版 claude-mem）或 `~/claude-mem-lite/`（v0.5 前的非隐藏目录），将数据库和运行时文件迁移到 `~/.claude-mem-lite/`，原目录保持不变
@@ -197,6 +197,8 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 | 工具 | 描述 |
 |------|------|
 | `mem_search` | 基于 BM25 排名的 FTS5 全文搜索。支持按类型、项目、日期范围、重要度过滤。 |
+| `mem_recent` | 显示最近的观察，按时间排序。快速查看最新活动。 |
+| `mem_recall` | 召回与文件相关的观察。编辑文件前使用，回顾过去的修复和上下文。 |
 | `mem_timeline` | 围绕锚点按时间顺序浏览观察。 |
 | `mem_get` | 获取指定观察 ID 的完整详情（包含重要度和关联 ID）。 |
 | `mem_save` | 手动保存记忆/观察。 |
@@ -207,6 +209,7 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 | `mem_maintain` | 记忆维护：扫描重复/过期/损坏条目，执行清理/去重/向量重建操作。 |
 | `mem_export` | 导出观察为 JSON 或 JSONL 格式，支持按项目、类型、日期范围过滤。 |
 | `mem_fts_check` | 检查 FTS5 索引完整性或重建索引。搜索结果异常或数据库恢复后使用。 |
+| `mem_browse` | 分层记忆仪表盘。按记忆层级（working/active/archive）分组展示观察。 |
 | `mem_registry` | 管理资源注册表：按需搜索技能/代理、列表、统计、导入/移除、重索引。 |
 
 ### 技能命令（在 Claude Code 聊天中使用）
@@ -214,9 +217,11 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
 ```
 /mem search <query>        # 全文搜索所有记忆
 /mem recent [n]            # 显示最近 N 条观察（默认 10）
+/mem recall <file>         # 显示文件相关的历史观察
 /mem save <text>           # 保存手动记忆/笔记
 /mem stats                 # 显示记忆统计
 /mem timeline <query>      # 围绕匹配结果浏览时间线
+/mem browse                # 分层记忆仪表盘
 /mem <query>               # search 的简写
 ```
 

package/cli.mjs

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
-const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'help']);
+const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'delete', 'update', 'export', 'compress', 'maintain', 'fts-check', 'registry', 'help']);
 
 const cmd = process.argv[2];
 
-if (CLI_COMMANDS.has(cmd)) {
+if (cmd === '--help' || cmd === '-h') {
+  const { run } = await import('./mem-cli.mjs');
+  await run(['help']);
+} else if (CLI_COMMANDS.has(cmd)) {
   const { run } = await import('./mem-cli.mjs');
   await run(process.argv.slice(2));
 } else {

package/hook-context.mjs

@@ -82,14 +82,19 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
   const selectedSess = [];
   let totalTokens = 0;
 
-  // Score each candidate: value = recency * importance, cost = tokens
+  // Type quality multipliers — aligned with scoring-sql.mjs TYPE_QUALITY_CASE
+  // Demotes bugfix (noisy error logs) and promotes high-signal types
+  const TYPE_QUALITY = { decision: 1.5, discovery: 1.3, feature: 1.2, refactor: 1.0, change: 0.8, bugfix: 0.35 };
+
+  // Score each candidate: value = recency * type_quality * importance, cost = tokens
   // Recency uses exponential half-life (consistent with server.mjs BM25 scoring)
   const scoredObs = obsPool.map(o => {
     const halfLifeMs = DECAY_HALF_LIFE_BY_TYPE[o.type] || DEFAULT_DECAY_HALF_LIFE_MS;
     const recency = 1.0 + Math.exp(-0.693 * (now_ms - o.created_at_epoch) / halfLifeMs);
+    const typeQuality = TYPE_QUALITY[o.type] || 1.0;
     const impBoost = 0.5 + 0.5 * (o.importance || 1);
     const lessonBoost = o.lesson_learned ? 1.3 : 1.0;
-    const value = recency * impBoost * lessonBoost;
+    const value = recency * typeQuality * impBoost * lessonBoost;
     const cost = estimateTokens((o.title || '') + (o.narrative || ''));
     return { ...o, value, cost, valueDensity: cost > 0 ? value / Math.sqrt(cost) : 0 };
   });

package/hook-episode.mjs

@@ -194,12 +194,15 @@ export function mergePendingEntries(episode) {
       if (pending.ts < oneHourAgo) { try { unlinkSync(fp); } catch {} continue; }
       // Only merge entries belonging to the same project
       if (pending.project && episode.project && pending.project !== episode.project) continue;
-      unlinkSync(fp);
       if (pending.entry) {
+        unlinkSync(fp);
         episode.entries.push(pending.entry);
         episode.lastAt = Math.max(episode.lastAt, pending.entry.ts || pending.ts);
         addFileToEpisode(episode, pending.entry.files || []);
         merged++;
+      } else {
+        // No entry data — clean up the file without merging
+        try { unlinkSync(fp); } catch {}
       }
     } catch {
       // Corrupt pending file — remove

package/hook-memory.mjs

@@ -5,7 +5,9 @@ import { sanitizeFtsQuery, relaxFtsQueryToOr, debugCatch, OBS_BM25 } from './uti
 
 const MAX_MEMORY_INJECTIONS = 3;
 const MEMORY_LOOKBACK_MS = 60 * 86400000; // 60 days
-const MEMORY_TYPE_BOOST = { bugfix: 1.5, decision: 1.3, discovery: 1.0, feature: 0.8, change: 0.5, refactor: 0.5 };
+// Aligned with TYPE_QUALITY_CASE: high-signal types > noisy types
+// Bugfix lessons are still surfaced via the separate lesson_learned boost (1.5×)
+const MEMORY_TYPE_BOOST = { decision: 1.5, discovery: 1.3, feature: 1.2, refactor: 1.0, change: 0.8, bugfix: 0.5 };
 
 const FILE_RECALL_LOOKBACK_MS = 60 * 86400000; // 60 days
 const MAX_FILE_RECALL = 2;

package/hook-update.mjs

@@ -193,7 +193,7 @@ export function getCurrentVersion() {
 
 // ── Source files to copy (must match install.mjs SOURCE_FILES) ──
 const SOURCE_FILES = [
-  'server.mjs', 'server-internals.mjs', 'tool-schemas.mjs',
+  'cli.mjs', 'server.mjs', 'server-internals.mjs', 'tool-schemas.mjs',
   'hook.mjs', 'hook-shared.mjs', 'hook-llm.mjs', 'hook-memory.mjs', 'skip-tools.mjs',
   'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs', 'hook-handoff.mjs', 'hook-update.mjs',
   'haiku-client.mjs', 'utils.mjs', 'schema.mjs', 'package.json', 'package-lock.json', 'skill.md',
@@ -218,10 +218,11 @@ async function downloadAndInstall(tarballUrl) {
       debugLog('WARN', 'hook-update', `Rejected suspicious tarball URL: ${tarballUrl}`);
       return false;
     }
-    execSync(
-      `curl -sL -H "Accept: application/vnd.github+json" "${tarballUrl}" | tar xz -C "${tmpDir}" --strip-components=1`,
-      { timeout: 30000, stdio: 'pipe' }
-    );
+    const tarballPath = join(tmpDir, 'release.tar.gz');
+    execFileSync('curl', ['-sL', '-H', 'Accept: application/vnd.github+json', tarballUrl, '-o', tarballPath],
+      { timeout: 30000, stdio: 'pipe' });
+    execFileSync('tar', ['xzf', tarballPath, '-C', tmpDir, '--strip-components=1'],
+      { timeout: 30000, stdio: 'pipe' });
 
     return installExtractedRelease(tmpDir);
   } catch (err) {
@@ -285,6 +286,9 @@ export function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR) {
       }
     } catch (e) { debugCatch(e, 'post-update-mcp-dedup'); }
 
+    // Post-update: prune old plugin cache versions (keep latest 3)
+    try { prunePluginCache(); } catch (e) { debugCatch(e, 'prunePluginCache'); }
+
     debugLog('DEBUG', 'hook-update', `Auto-update: switched ${installed.length} paths`);
     return true;
   } catch (err) {
@@ -344,6 +348,33 @@ function copyReleaseIntoStaging(sourceDir, stagingDir) {
   debugLog('DEBUG', 'hook-update', `Auto-update staged ${copied} source files`);
 }
 
+// ── Plugin Cache Pruning ──────────────────────────────────
+const PLUGIN_CACHE_KEEP = 3;
+
+export function prunePluginCache() {
+  const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', 'sdsrss', 'claude-mem-lite');
+  if (!existsSync(cacheBase)) return 0;
+
+  const entries = readdirSync(cacheBase)
+    .filter(name => /^\d+\.\d+/.test(name))  // version-like dirs only
+    .sort((a, b) => compareVersions(b, a));   // newest first
+
+  if (entries.length <= PLUGIN_CACHE_KEEP) return 0;
+
+  const toRemove = entries.slice(PLUGIN_CACHE_KEEP);
+  let removed = 0;
+  for (const ver of toRemove) {
+    try {
+      rmSync(join(cacheBase, ver), { recursive: true, force: true });
+      removed++;
+    } catch {}
+  }
+  if (removed > 0) {
+    debugLog('DEBUG', 'hook-update', `Plugin cache pruned: removed ${removed} old version(s), kept latest ${PLUGIN_CACHE_KEEP}`);
+  }
+  return removed;
+}
+
 // ── State Persistence ──────────────────────────────────────
 function readState() {
   try {
@@ -357,6 +388,8 @@ function saveState(state) {
   try {
     const dir = join(INSTALL_DIR, 'runtime');
     mkdirSync(dir, { recursive: true });
-    writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+    const tmpFile = STATE_FILE + `.tmp-${process.pid}`;
+    writeFileSync(tmpFile, JSON.stringify(state, null, 2));
+    renameSync(tmpFile, STATE_FILE);
   } catch {}
 }

package/hook.mjs

@@ -812,7 +812,7 @@ async function handleUserPrompt() {
 
       // Read IDs already injected by user-prompt-search.js to avoid duplicate injection
       try {
-        const injectedFile = `/tmp/.claude-mem-injected-${project}`;
+        const injectedFile = join(RUNTIME_DIR, `.claude-mem-injected-${project}`);
         const raw = readFileSync(injectedFile, 'utf8');
         const { ids, ts } = JSON.parse(raw);
         // Only use if written within last 10 seconds (same prompt cycle)

package/install.mjs

@@ -3,7 +3,7 @@
 
 import { execSync, execFileSync } from 'child_process';
 import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, copyFileSync, cpSync, renameSync, symlinkSync, unlinkSync, readdirSync, statSync } from 'fs';
-import { join, resolve, dirname } from 'path';
+import { join, resolve, dirname, isAbsolute } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 
@@ -202,7 +202,7 @@ async function install() {
   if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
 
   const SOURCE_FILES = [
-    'server.mjs', 'server-internals.mjs', 'tool-schemas.mjs',
+    'cli.mjs', 'server.mjs', 'server-internals.mjs', 'tool-schemas.mjs',
     'hook.mjs', 'hook-shared.mjs', 'hook-llm.mjs', 'hook-memory.mjs', 'skip-tools.mjs',
     'hook-semaphore.mjs', 'hook-episode.mjs', 'hook-context.mjs', 'hook-handoff.mjs', 'hook-update.mjs',
     'haiku-client.mjs', 'utils.mjs', 'schema.mjs', 'package.json', 'package-lock.json', 'skill.md',
@@ -259,6 +259,8 @@ async function install() {
     if (existsSync(postToolSrc)) copyFileSync(postToolSrc, join(scriptsDir, 'post-tool-use.sh'));
     const promptSearchSrc = join(PROJECT_DIR, 'scripts', 'user-prompt-search.js');
     if (existsSync(promptSearchSrc)) copyFileSync(promptSearchSrc, join(scriptsDir, 'user-prompt-search.js'));
+    const promptSearchUtilsSrc = join(PROJECT_DIR, 'scripts', 'prompt-search-utils.mjs');
+    if (existsSync(promptSearchUtilsSrc)) copyFileSync(promptSearchUtilsSrc, join(scriptsDir, 'prompt-search-utils.mjs'));
     // Ensure bash script is executable
     try { execFileSync('chmod', ['+x', join(scriptsDir, 'post-tool-use.sh')], { stdio: 'pipe' }); } catch {}
     // Copy commands directory
@@ -292,6 +294,31 @@ async function install() {
     }
   }
 
+  // 2b. Create global CLI symlink (claude-mem-lite command)
+  const cliSource = join(INSTALL_DIR, 'cli.mjs');
+  if (existsSync(cliSource)) {
+    try { execFileSync('chmod', ['+x', cliSource], { stdio: 'pipe' }); } catch {}
+    // Try ~/.local/bin first (user-writable, commonly on PATH)
+    const localBin = join(homedir(), '.local', 'bin');
+    const cliLink = join(localBin, 'claude-mem-lite');
+    try {
+      if (!existsSync(localBin)) mkdirSync(localBin, { recursive: true });
+      if (existsSync(cliLink)) unlinkSync(cliLink);
+      symlinkSync(cliSource, cliLink);
+      ok(`CLI: ${cliLink} → ${cliSource}`);
+    } catch {
+      // Fallback: try /usr/local/bin (may need sudo)
+      try {
+        const globalLink = '/usr/local/bin/claude-mem-lite';
+        if (existsSync(globalLink)) unlinkSync(globalLink);
+        symlinkSync(cliSource, globalLink);
+        ok(`CLI: ${globalLink} → ${cliSource}`);
+      } catch {
+        warn('CLI symlink failed — run manually: ln -sf ' + cliSource + ' ~/.local/bin/claude-mem-lite');
+      }
+    }
+  }
+
   // 3. Register MCP server (skip if plugin system already handles it)
   // Plugin MCP must stay at root .mcp.json so Claude Code registers plugin:*:mem.
   // Duplicate mem registrations in practice come from old global install.mjs state
@@ -353,6 +380,21 @@ async function install() {
         }
       }
     } catch (e) { warn(`Marketplace hooks dedup: ${e.message}`); }
+
+    // Sync launch.mjs to plugin cache — ensures MCP server loads dev code via symlink detection
+    try {
+      const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', MARKETPLACE_KEY, 'claude-mem-lite');
+      if (existsSync(cacheBase)) {
+        const srcLaunch = join(PROJECT_DIR, 'scripts', 'launch.mjs');
+        for (const ver of readdirSync(cacheBase)) {
+          const dest = join(cacheBase, ver, 'scripts', 'launch.mjs');
+          if (existsSync(join(cacheBase, ver, 'scripts'))) {
+            copyFileSync(srcLaunch, dest);
+          }
+        }
+        ok('Plugin cache: launch.mjs synced (dev mode MCP routing)');
+      }
+    } catch (e) { warn(`Plugin cache sync: ${e.message}`); }
   }
 
   // 4. Configure hooks (merge: preserve user's existing hooks, replace ours)
@@ -552,6 +594,9 @@ async function install() {
           mkdirSync(join(managedDir, 'skills'), { recursive: true });
           mkdirSync(join(managedDir, 'agents'), { recursive: true });
           for (const entry of entries) {
+            // Path traversal guard: reject entries with '..' or absolute paths
+            if (entry.path.includes('..') || entry.name.includes('..') ||
+                isAbsolute(entry.path) || isAbsolute(entry.name)) continue;
             const srcPath = entry.path === '.' ? clonePath : join(clonePath, entry.path);
             const destDir = join(managedDir, entry.type === 'skill' ? 'skills' : 'agents');
             const destPath = join(destDir, entry.name);
@@ -721,6 +766,14 @@ async function uninstall() {
     warn('MCP server not found or already removed');
   }
 
+  // 1b. Remove CLI symlink
+  for (const binDir of [join(homedir(), '.local', 'bin'), '/usr/local/bin']) {
+    const cliLink = join(binDir, 'claude-mem-lite');
+    try {
+      if (existsSync(cliLink)) { unlinkSync(cliLink); ok(`CLI symlink removed: ${cliLink}`); }
+    } catch { /* may not have permissions */ }
+  }
+
   // 2. Remove hooks from settings.json (match both npx and git-clone install paths)
   const settings = readSettings();
   cleanupMemHooksFromSettings(settings);
@@ -879,6 +932,18 @@ async function status() {
     warn('Database: not found');
   }
 
+  // CLI
+  try {
+    const cliVer = execSync('claude-mem-lite --help 2>/dev/null && echo OK', { encoding: 'utf8', timeout: 5000 });
+    if (cliVer.includes('OK')) {
+      ok('CLI: claude-mem-lite command available');
+    } else {
+      warn('CLI: command not on PATH');
+    }
+  } catch {
+    warn('CLI: command not on PATH — run install again to create symlink');
+  }
+
   // Old system
   const vectorDb = join(OLD_DATA_DIR, 'vector-db');
   if (existsSync(vectorDb)) {
@@ -1068,6 +1133,23 @@ async function doctor() {
     }
   }
 
+  // Plugin cache versions
+  const pluginCacheBase = join(homedir(), '.claude', 'plugins', 'cache', MARKETPLACE_KEY, 'claude-mem-lite');
+  if (existsSync(pluginCacheBase)) {
+    try {
+      const versions = readdirSync(pluginCacheBase).filter(n => /^\d+\./.test(n));
+      let sizeStr;
+      try {
+        sizeStr = execFileSync('du', ['-sh', pluginCacheBase], { encoding: 'utf8', timeout: 5000 }).trim().split('\t')[0];
+      } catch { sizeStr = '?'; }
+      if (versions.length > 3) {
+        warn(`Plugin cache: ${versions.length} versions (${sizeStr}) — run setup.sh or update to auto-prune to 3`);
+      } else {
+        ok(`Plugin cache: ${versions.length} version(s) (${sizeStr})`);
+      }
+    } catch {}
+  }
+
   console.log(`\n  ${issues === 0 ? 'All checks passed!' : `${issues} issue(s) found.`}\n`);
 }