claude-mem-lite 2.26.1 → 2.28.2

package/scripts/user-prompt-search.js

@@ -3,11 +3,13 @@
 // Runs as UserPromptSubmit hook — injects relevant memories before Claude sees the prompt
 // Lightweight: only imports schema.mjs and utils.mjs, no MCP SDK
 
-import { ensureDb, DB_DIR } from '../schema.mjs';
-import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE } from '../utils.mjs';
-import { writeFileSync, readFileSync } from 'fs';
+import { ensureDb, DB_DIR, REGISTRY_DB_PATH } from '../schema.mjs';
+import { sanitizeFtsQuery, relaxFtsQueryToOr, truncate, typeIcon, inferProject, OBS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, isPathConfined } from '../utils.mjs';
+import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
 import { join } from 'path';
-import { shouldSkip, detectIntent, shouldSkipByDedup, extractFiles, DEDUP_STALE_MS } from './prompt-search-utils.mjs';
+import { homedir } from 'os';
+import Database from 'better-sqlite3';
+import { shouldSkip, detectIntent, shouldSkipByDedup, extractFiles, DEDUP_STALE_MS, matchRegistrySkillName } from './prompt-search-utils.mjs';
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -152,6 +154,92 @@ function formatResults(rows) {
   return lines.join('\n');
 }
 
+// ─── Registry Skill Auto-Load ──────────────────────────────────────────────
+
+const SKILL_COOLDOWN_FILE = join(DB_DIR, 'runtime', `.skill-cooldown-${inferProject()}`);
+const SKILL_COOLDOWN_MS = 300_000; // 5 minutes
+const SKILL_TOKEN_LIMIT = 16000;   // ~4000 tokens
+
+function loadManagedSkillNames() {
+  if (!existsSync(REGISTRY_DB_PATH)) return new Set();
+  try {
+    const rdb = new Database(REGISTRY_DB_PATH, { readonly: true });
+    rdb.pragma('busy_timeout = 500');
+    try {
+      const rows = rdb.prepare(`
+        SELECT name FROM resources
+        WHERE status = 'active' AND local_path LIKE '%/.claude-mem-lite/managed/%'
+      `).all();
+      return new Set(rows.map(r => r.name.toLowerCase()));
+    } finally { rdb.close(); }
+  } catch { return new Set(); }
+}
+
+function toPortablePath(absPath) {
+  const home = homedir();
+  return absPath.startsWith(home) ? '~' + absPath.slice(home.length) : absPath;
+}
+
+function loadSkillContent(skillName) {
+  if (!existsSync(REGISTRY_DB_PATH)) return null;
+  try {
+    const rdb = new Database(REGISTRY_DB_PATH, { readonly: true });
+    rdb.pragma('busy_timeout = 500');
+    try {
+      const row = rdb.prepare(`
+        SELECT name, type, local_path FROM resources
+        WHERE status = 'active'
+          AND (name = ? OR invocation_name = ?)
+          AND local_path LIKE '%/.claude-mem-lite/managed/%'
+        LIMIT 1
+      `).get(skillName, skillName);
+
+      if (!row || !row.local_path) return null;
+
+      let path = row.local_path;
+      if (!path.endsWith('.md')) {
+        const candidate = join(path, 'SKILL.md');
+        if (existsSync(candidate)) path = candidate;
+      }
+      // Path confinement check — prevent LIKE bypass via '../' in local_path
+      const managedBase = join(homedir(), '.claude-mem-lite');
+      if (!isPathConfined(path, managedBase)) return null;
+      if (!existsSync(path)) return null;
+
+      const portablePath = toPortablePath(path);
+      const sourceLabel = row.type === 'agent' ? 'managed-agent' : 'managed-skill';
+      const content = readFileSync(path, 'utf8');
+      if (content.length > SKILL_TOKEN_LIMIT) {
+        return `<skill-auto-loaded name="${row.name}" source="${sourceLabel}" path="${portablePath}" truncated="true">\n${content.slice(0, 800)}\n...\n</skill-auto-loaded>\nSkill truncated. Full content: Read("${portablePath}") or mem_use(name="${row.name}")`;
+      }
+      return `<skill-auto-loaded name="${row.name}" source="${sourceLabel}" path="${portablePath}">\n${content}\n</skill-auto-loaded>\nFollow the instructions above. Reload: Read("${portablePath}")`;
+    } finally { rdb.close(); }
+  } catch { return null; }
+}
+
+function getSkillCooldown() {
+  try {
+    const raw = readFileSync(SKILL_COOLDOWN_FILE, 'utf8');
+    const data = JSON.parse(raw);
+    const now = Date.now();
+    const cleaned = {};
+    for (const [k, v] of Object.entries(data)) {
+      if (now - v < SKILL_COOLDOWN_MS) cleaned[k] = v;
+    }
+    return cleaned;
+  } catch { return {}; }
+}
+
+function setSkillCooldown(name) {
+  try {
+    const data = getSkillCooldown();
+    data[name] = Date.now();
+    const tmp = SKILL_COOLDOWN_FILE + `.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(data));
+    renameSync(tmp, SKILL_COOLDOWN_FILE);
+  } catch { /* silent */ }
+}
+
 // ─── Main ───────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -209,9 +297,9 @@ async function main() {
     }
 
     const candidateIds = rows.map(r => r.id);
-    if (shouldSkipByDedup(candidateIds, INJECTED_IDS_FILE)) return;
+    const dedupSkip = shouldSkipByDedup(candidateIds, INJECTED_IDS_FILE);
 
-    const output = formatResults(rows);
+    const output = !dedupSkip ? formatResults(rows) : null;
     if (output) {
       process.stdout.write(output + '\n');
       // Write injected IDs for dedup with hook.mjs handleUserPrompt + self-dedup
@@ -228,6 +316,22 @@ async function main() {
         }));
       } catch {}
     }
+
+    // ─── L1: Registry skill auto-load ───────────────────────────────────
+    try {
+      const skillNames = loadManagedSkillNames();
+      const matched = matchRegistrySkillName(promptText, skillNames);
+      if (matched) {
+        const cooldown = getSkillCooldown();
+        if (!cooldown[matched]) {
+          const skillContent = loadSkillContent(matched);
+          if (skillContent) {
+            process.stdout.write('\n' + skillContent + '\n');
+            setSkillCooldown(matched);
+          }
+        }
+      }
+    } catch { /* silent — never block on registry failure */ }
   } catch {
     // Hooks must never break Claude Code — swallow all errors
   } finally {

package/server.mjs

@@ -4,13 +4,14 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, fmtDate, isoWeekKey, debugLog, debugCatch, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, getCurrentBranch, DEFAULT_DECAY_HALF_LIFE_MS } from './utils.mjs';
+import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, estimateJaccardFromMinHash, scrubSecrets, cjkBigrams, fmtDate, isoWeekKey, debugLog, debugCatch, COMPRESSED_PENDING_PURGE, OBS_BM25, SESS_BM25, TYPE_DECAY_CASE, TYPE_QUALITY_CASE, getCurrentBranch, DEFAULT_DECAY_HALF_LIFE_MS, isPathConfined } from './utils.mjs';
 import { resolveProject as _resolveProjectShared } from './project-utils.mjs';
 import { ensureDb, DB_PATH, REGISTRY_DB_PATH, checkFTSIntegrity, rebuildFTS } from './schema.mjs';
 import { reRankWithContext, markSuperseded, extractPRFTerms, expandQueryByConcepts, autoBoostIfNeeded, runIdleCleanup } from './server-internals.mjs';
 import { computeTier, TIER_CASE_SQL, tierSqlParams } from './tier.mjs';
-import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema } from './tool-schemas.mjs';
-import { basename } from 'path';
+import { memSearchSchema, memRecentSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memUpdateSchema, memExportSchema, memRecallSchema, memFtsCheckSchema, memRegistrySchema, memBrowseSchema, memUseSchema } from './tool-schemas.mjs';
+import { basename, join } from 'path';
+import { homedir } from 'os';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
 import { getVocabulary, rebuildVocabulary, _resetVocabCache, computeVector, vectorSearch, rrfMerge } from './tfidf.mjs';
@@ -21,7 +22,7 @@ const { version: PKG_VERSION } = require('./package.json');
 
 // ─── Database ───────────────────────────────────────────────────────────────
 
-import { rmSync } from 'fs';
+import { rmSync, existsSync, readFileSync } from 'fs';
 
 let db;
 try {
@@ -115,6 +116,15 @@ const server = new McpServer(
       '  • Starting work on a module → recall past decisions: claude-mem-lite search "module-name" --type decision',
       '  • After solving a non-obvious problem → save the lesson: mem_save with lesson_learned',
       '  • When hook-injected context mentions a relevant ID → get details: claude-mem-lite get ID',
+      '',
+      'Decision rules (use INSTEAD OF multi-step search):',
+      '  • "what happened recently?" → mem_recent (NOT search with empty query)',
+      '  • "what do we know about file.mjs?" → mem_recall (NOT grep + manual search)',
+      '  • "show me around observation #42" → mem_timeline (NOT mem_get + manual navigation)',
+      '  • "clean up old/duplicate memories" → mem_maintain (NOT manual mem_delete loop)',
+      '  • "is the search index healthy?" → mem_fts_check (NOT manual COUNT queries)',
+      '  • "overview of memory tiers" → mem_browse (NOT mem_search + manual grouping)',
+      '  • "export for backup" → mem_export (NOT manual SELECT queries)',
     ].join('\n'),
   },
 );
@@ -514,7 +524,7 @@ function formatSearchOutput(paginatedResults, args, ftsQuery, totalCount, isCros
 server.registerTool(
   'mem_search',
   {
-    description: 'FTS5 full-text search across observations, sessions, and prompts with BM25 ranking. Returns compact index (use mem_get for details).',
+    description: 'Search project memory for past bugfixes, decisions, and discoveries. Use when: encountering a familiar error, investigating a module before changes, or looking for prior art on a problem. Returns compact index (use mem_get for full details).',
     inputSchema: memSearchSchema,
   },
   safeHandler(async (args) => {
@@ -650,7 +660,7 @@ server.registerTool(
 server.registerTool(
   'mem_recent',
   {
-    description: 'Show most recent observations, ordered by time. Quick way to see latest activity without a search query.',
+    description: 'Show most recent observations. Use when: checking what happened recently in the project, reviewing progress after being away, or verifying that a recent change was captured.',
     inputSchema: memRecentSchema,
   },
   safeHandler(async (args) => {
@@ -689,7 +699,7 @@ server.registerTool(
 server.registerTool(
   'mem_timeline',
   {
-    description: 'Browse observations as a timeline around an anchor point. Use query to auto-find anchor, or specify anchor ID directly.',
+    description: 'Browse observations as a timeline around an anchor point. Use when: exploring what happened before/after a specific observation, understanding the sequence of changes that led to a bug, or reviewing a session chronologically.',
     inputSchema: memTimelineSchema,
   },
   safeHandler(async (args) => {
@@ -748,7 +758,9 @@ server.registerTool(
     }
 
     // Update access_count for anchor (aligned with CLI timeline)
-    db.prepare('UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id = ?').run(Date.now(), anchorId);
+    try {
+      db.prepare('UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id = ?').run(Date.now(), anchorId);
+    } catch { /* non-critical: FTS5 trigger may fail on corrupted index */ }
 
     const projectFilter = args.project ? 'AND project = ?' : '';
     const baseParams = args.project ? [args.project] : [];
@@ -790,7 +802,7 @@ server.registerTool(
 server.registerTool(
   'mem_get',
   {
-    description: 'Get full details for one or more records by ID. Use after mem_search to drill into specific records.',
+    description: 'Get full details for one or more records by ID. Use when: hook-injected context mentions a relevant observation ID, or after mem_search to drill into specific results for narrative, lesson_learned, and file details.',
     inputSchema: memGetSchema,
   },
   safeHandler(async (args) => {
@@ -808,11 +820,12 @@ server.registerTool(
       prefix = 'P#';
     } else {
       // Increment access_count for retrieved observations (batch UPDATE)
-      db.prepare(
-        `UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id IN (${placeholders})`
-      ).run(Date.now(), ...args.ids);
-      // Auto-boost importance for frequently accessed observations
-      autoBoostIfNeeded(db, args.ids);
+      try {
+        db.prepare(
+          `UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id IN (${placeholders})`
+        ).run(Date.now(), ...args.ids);
+        autoBoostIfNeeded(db, args.ids);
+      } catch { /* non-critical: FTS5 trigger may fail on corrupted index */ }
       rows = db.prepare(`SELECT * FROM observations WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...args.ids);
       allFields = ['id', 'type', 'title', 'subtitle', 'narrative', 'text', 'facts', 'concepts', 'lesson_learned', 'search_aliases', 'files_read', 'files_modified', 'project', 'created_at', 'memory_session_id', 'prompt_number', 'importance', 'related_ids', 'access_count', 'branch', 'superseded_at', 'superseded_by', 'last_accessed_at'];
       prefix = '#';
@@ -848,7 +861,7 @@ server.registerTool(
 server.registerTool(
   'mem_delete',
   {
-    description: 'Delete observations by ID. Use confirm=false to preview, confirm=true to execute. FTS5 cleanup is automatic via triggers.',
+    description: 'Delete observations by ID. Use when: cleaning up incorrect or duplicate observations, removing test data, or when the user asks to forget something. Use confirm=false to preview, confirm=true to execute.',
     inputSchema: memDeleteSchema,
   },
   safeHandler(async (args) => {
@@ -912,7 +925,7 @@ server.registerTool(
 server.registerTool(
   'mem_save',
   {
-    description: 'Manually save a memory/observation. Use for important findings, decisions, or notes worth preserving.',
+    description: 'Save a memory/observation. Use when: solving a non-obvious bug (save the lesson), making an architecture decision, discovering something not obvious from code alone, or when the user asks to remember something.',
     inputSchema: memSaveSchema,
   },
   safeHandler(async (args) => {
@@ -994,7 +1007,7 @@ server.registerTool(
 server.registerTool(
   'mem_stats',
   {
-    description: 'Get statistics about stored memories: counts, types, projects, recent activity.',
+    description: 'Get memory statistics: counts, types, projects, daily activity, data health. Use when: assessing memory system health, checking how much project history exists, or diagnosing search quality issues.',
     inputSchema: memStatsSchema,
   },
   safeHandler(async (args) => {
@@ -1104,7 +1117,7 @@ server.registerTool(
 server.registerTool(
   'mem_compress',
   {
-    description: 'Compress old low-value observations into weekly summaries. Use preview=true to see candidates first.',
+    description: 'Compress old low-value observations into weekly summaries. Use when: memory database is growing large, observations are months old, or after a major project phase completes. Use preview=true to see candidates first.',
     inputSchema: memCompressSchema,
   },
   safeHandler(async (args) => {
@@ -1217,7 +1230,7 @@ server.registerTool(
 server.registerTool(
   'mem_maintain',
   {
-    description: 'Memory maintenance: scan for duplicates/stale/broken items, then execute cleanup/decay/boost/dedup operations.',
+    description: 'Memory maintenance: scan for duplicates/stale/broken items, then execute cleanup/decay/boost/dedup operations. Use when: search results seem noisy with duplicates, after bulk imports, or during periodic maintenance.',
     inputSchema: memMaintainSchema,
   },
   safeHandler(async (args) => {
@@ -1478,7 +1491,7 @@ server.registerTool(
 server.registerTool(
   'mem_registry',
   {
-    description: 'Manage tool resource registry: search for skills/agents by need, list resources, view stats, import/remove tools, reindex FTS5.',
+    description: 'Manage tool resource registry. Use when: looking for a skill or agent to solve a problem, importing tools from a repository, checking what resources are available, or managing installed tools.',
     inputSchema: memRegistrySchema,
   },
   safeHandler(async (args) => {
@@ -1511,13 +1524,30 @@ server.registerTool(
       if (results.length === 0) {
         return { content: [{ type: 'text', text: `No matching resources for: "${args.query}"` }] };
       }
+      const home = homedir();
+      const toPortable = (p) => p && p.startsWith(home) ? '~' + p.slice(home.length) : (p || '');
       const lines = results.map(r => {
         const qualityBadge = r.quality_tier === 'installed' ? '[✓]' : r.quality_tier === 'verified' ? '[★]' : '[○]';
         const categoryLabel = r.category ? ` [${r.category}]` : '';
-        const howToUse = r.type === 'skill'
-          ? (r.invocation_name ? `Skill tool: skill="${r.invocation_name}"` : `Community skill: ${r.name}`)
-          : `Agent tool: subagent_type="${r.invocation_name || r.name}"`;
-        return `${qualityBadge} ${r.type === 'skill' ? 'S' : 'A'} **${r.name}**${categoryLabel} — ${truncate(r.capability_summary || '', 80)}\n  Use: ${howToUse}`;
+        const isManaged = r.local_path && r.local_path.includes('/.claude-mem-lite/managed/');
+        const portablePath = isManaged ? toPortable(r.local_path) : '';
+        let howToUse;
+        if (isManaged) {
+          // Managed: use Read(path) or mem_use — Skill() won't work for managed resources
+          // Agents always have complete .md paths (e.g., agents/group/agents/name.md)
+          // Only skills can be directory paths (9 cases) — resolve to /SKILL.md
+          const resolvedPath = portablePath.endsWith('.md') ? portablePath : `${portablePath}/SKILL.md`;
+          howToUse = `Read("${resolvedPath}") or mem_use(name="${r.name}"${r.type === 'agent' ? ', type="agent"' : ''})`;
+        } else if (r.invocation_name) {
+          // Native plugin/user skill: Skill() with full invocation name
+          howToUse = r.type === 'skill'
+            ? `Skill("${r.invocation_name}")`
+            : `Agent(subagent_type="${r.invocation_name}")`;
+        } else {
+          howToUse = `mem_use(name="${r.name}"${r.type === 'agent' ? ', type="agent"' : ''})`;
+        }
+        const pathLine = portablePath ? `\n  Path: ${portablePath}` : '';
+        return `${qualityBadge} ${r.type === 'skill' ? 'S' : 'A'} **${r.name}**${categoryLabel} — ${truncate(r.capability_summary || '', 80)}${pathLine}\n  Use: ${howToUse}`;
       });
       return { content: [{ type: 'text', text: `Found ${results.length} resource(s) for "${args.query}":\n\n${lines.join('\n\n')}` }] };
     }
@@ -1597,16 +1627,160 @@ server.registerTool(
       return { content: [{ type: 'text', text: `FTS5 reindexed. ${count.c} active resources.` }] };
     }
 
-    return { content: [{ type: 'text', text: `Unknown action: ${action}. Valid: search, list, stats, import, remove, reindex` }], isError: true };
+    if (action === 'import_url') {
+      if (!args.url) {
+        return { content: [{ type: 'text', text: 'import_url requires a url parameter' }], isError: true };
+      }
+      const { importFromGitHub } = await import('./registry-importer.mjs');
+      try {
+        const results = await importFromGitHub(rdb, args.url);
+        if (results.length === 0) {
+          return { content: [{ type: 'text', text: `No skills/agents found in: ${args.url}` }] };
+        }
+
+        let enrichMsg = '';
+        if (args.enrich) {
+          const { enrichResource } = await import('./registry-enricher.mjs');
+          let ok = 0;
+          for (const r of results) {
+            const row = rdb.prepare('SELECT local_path FROM resources WHERE id = ?').get(r.id);
+            if (!row?.local_path) continue;
+            try {
+              const content = readFileSync(row.local_path, 'utf8');
+              if (await enrichResource(rdb, r.name, r.type, content)) ok++;
+            } catch {}
+          }
+          enrichMsg = `\nEnriched: ${ok}/${results.length}`;
+        }
+
+        const lines = results.map(r => `${r.type === 'skill' ? 'S' : 'A'} ${r.name} (id=${r.id})`);
+        return { content: [{ type: 'text', text: `Imported ${results.length} resource(s) from ${args.url}:\n${lines.join('\n')}${enrichMsg}` }] };
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Import failed: ${e.message}` }], isError: true };
+      }
+    }
+
+    if (action === 'enrich') {
+      if (!args.name) {
+        return { content: [{ type: 'text', text: 'enrich requires a name parameter' }], isError: true };
+      }
+      const row = rdb.prepare("SELECT name, type, local_path FROM resources WHERE name = ? AND status = 'active'").get(args.name);
+      if (!row) {
+        return { content: [{ type: 'text', text: `Resource not found: ${args.name}` }], isError: true };
+      }
+      if (!row.local_path) {
+        return { content: [{ type: 'text', text: `No local_path for ${args.name}` }], isError: true };
+      }
+      const enrichBase = join(homedir(), '.claude-mem-lite');
+      if (!isPathConfined(row.local_path, enrichBase)) {
+        return { content: [{ type: 'text', text: `Access denied: path outside managed directory` }], isError: true };
+      }
+
+      const { enrichResource } = await import('./registry-enricher.mjs');
+      try {
+        const content = readFileSync(row.local_path, 'utf8');
+        const ok = await enrichResource(rdb, row.name, row.type, content);
+        return { content: [{ type: 'text', text: ok ? `Enriched: ${args.name}` : `Enrichment failed for ${args.name}` }] };
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Enrich error: ${e.message}` }], isError: true };
+      }
+    }
+
+    return { content: [{ type: 'text', text: `Unknown action: ${action}. Valid: search, list, stats, import, remove, reindex, import_url, enrich` }], isError: true };
   })
 );
 
+// ─── Tool: mem_use ──────────────────────────────────────────────────────────
+
+server.registerTool(
+  'mem_use',
+  {
+    description: 'Load and activate a skill or agent from the managed registry. '
+      + 'Returns the full skill/agent content for execution. '
+      + 'Use when: you found a skill via mem_registry search and want to use it, '
+      + 'or you know a managed skill/agent name and want to load its instructions.',
+    inputSchema: memUseSchema,
+  },
+  safeHandler(async (args) => {
+    const rdb = getRegistryDb();
+    if (!rdb) {
+      return { content: [{ type: 'text', text: 'Registry DB not available.' }], isError: true };
+    }
+
+    const name = args.name.trim();
+    const type = args.type || 'skill';
+
+    // 1. Exact match by name or invocation_name
+    let row = rdb.prepare(`
+      SELECT id, name, type, local_path, invocation_name, capability_summary
+      FROM resources
+      WHERE status = 'active' AND type = ?
+        AND (name = ? OR invocation_name = ?)
+      LIMIT 1
+    `).get(type, name, name);
+
+    // 2. Fuzzy fallback: FTS5 search, take top result
+    if (!row) {
+      const results = searchResources(rdb, name, { type, limit: 1 });
+      if (results.length > 0) {
+        row = rdb.prepare(`SELECT id, name, type, local_path, invocation_name, capability_summary FROM resources WHERE name = ? AND type = ? AND status = 'active'`).get(results[0].name, results[0].type);
+      }
+    }
+
+    if (!row) {
+      return { content: [{ type: 'text', text: `No ${type} found for "${name}". Try mem_registry(action="search", query="${name}") to browse.` }] };
+    }
+
+    // 3. Resolve path: directory skills → SKILL.md (agents always have full .md paths)
+    let skillPath = row.local_path || '';
+    if (skillPath && !skillPath.endsWith('.md')) {
+      for (const candidate of [
+        join(skillPath, 'SKILL.md'),
+        join(skillPath, `skills/${row.name}/SKILL.md`),
+      ]) {
+        if (existsSync(candidate)) { skillPath = candidate; break; }
+      }
+    }
+
+    // 4. Path confinement check — prevent reading arbitrary files via crafted local_path
+    const managedBase = join(homedir(), '.claude-mem-lite');
+    if (skillPath && !isPathConfined(skillPath, managedBase)) {
+      return { content: [{ type: 'text', text: `Access denied: path "${skillPath}" is outside managed directory` }], isError: true };
+    }
+
+    // 5. Read content
+    let content;
+    try {
+      content = readFileSync(skillPath, 'utf8');
+    } catch {
+      const msg = skillPath.endsWith('.md')
+        ? `Found ${type} "${row.name}" but cannot read file: ${skillPath}`
+        : `Found ${type} "${row.name}" but no .md file in: ${skillPath}`;
+      return { content: [{ type: 'text', text: msg }], isError: true };
+    }
+
+    // 5. Record invocation
+    try {
+      rdb.prepare(`
+        INSERT INTO invocations (resource_id, session_id, trigger, adopted, outcome)
+        VALUES (?, ?, 'user_explicit', 1, 'success')
+      `).run(row.id, process.env.CLAUDE_SESSION_ID || 'unknown');
+    } catch { /* non-critical */ }
+
+    const _home = homedir();
+    const portablePath = skillPath && skillPath.startsWith(_home) ? '~' + skillPath.slice(_home.length) : (skillPath || '');
+    const pathAttr = portablePath ? ` path="${portablePath}"` : '';
+    const reloadHint = portablePath ? ` Reload: Read("${portablePath}")` : '';
+    return { content: [{ type: 'text', text: `<skill-loaded name="${row.name}" type="${row.type}"${pathAttr}>\n${content}\n</skill-loaded>\n\nFollow the instructions above to execute this ${row.type}.${reloadHint}` }] };
+  }),
+);
+
 // ─── Tool: mem_update ────────────────────────────────────────────────────────
 
 server.registerTool(
   'mem_update',
   {
-    description: 'Update an existing observation in-place. Preserves original ID and references.',
+    description: 'Update an existing observation in-place. Use when: an observation needs correction, additional context was discovered later, or the user asks to update a specific memory. Preserves original ID and references.',
     inputSchema: memUpdateSchema,
   },
   safeHandler(async (args) => {
@@ -1658,7 +1832,7 @@ server.registerTool(
 server.registerTool(
   'mem_export',
   {
-    description: 'Export observations as JSON or JSONL for backup or migration.',
+    description: 'Export observations as JSON or JSONL. Use when: backing up memory before migration, sharing observations between machines, or creating a snapshot before major changes.',
     inputSchema: memExportSchema,
   },
   safeHandler(async (args) => {
@@ -1698,7 +1872,7 @@ server.registerTool(
 server.registerTool(
   'mem_recall',
   {
-    description: 'Recall observations related to a file. Use before editing a file to recall past bugfixes, decisions, and context.',
+    description: 'Recall observations related to a file. Use when: about to edit a file, investigating a file with past issues, or before refactoring to recall past bugfixes, decisions, and context.',
     inputSchema: memRecallSchema,
   },
   safeHandler(async (args) => {
@@ -1724,7 +1898,9 @@ server.registerTool(
     // Update access_count for recalled observations
     const recalledIds = rows.map(r => r.id);
     const ph = recalledIds.map(() => '?').join(',');
-    db.prepare(`UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id IN (${ph})`).run(Date.now(), ...recalledIds);
+    try {
+      db.prepare(`UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id IN (${ph})`).run(Date.now(), ...recalledIds);
+    } catch { /* non-critical: FTS5 trigger may fail on corrupted index */ }
 
     const lines = [`History for ${filename} (${rows.length} observation${rows.length !== 1 ? 's' : ''}):\n`];
     for (const r of rows) {
@@ -1741,7 +1917,7 @@ server.registerTool(
 server.registerTool(
   'mem_fts_check',
   {
-    description: 'Check FTS5 index integrity or rebuild indexes. Use when search results seem wrong or after database recovery.',
+    description: 'Check FTS5 index integrity or rebuild indexes. Use when: search results seem wrong or missing, after database recovery, or after manual DB edits.',
     inputSchema: memFtsCheckSchema,
   },
   safeHandler(async (args) => {
@@ -1767,7 +1943,7 @@ server.registerTool(
 server.registerTool(
   'mem_browse',
   {
-    description: 'Tier-grouped memory dashboard. Shows observations organized by memory tier (working/active/archive).',
+    description: 'Tier-grouped memory dashboard. Use when: getting an overview of memory health, seeing how observations are distributed across tiers, or assessing what to compress or clean up.',
     inputSchema: memBrowseSchema,
   },
   safeHandler(async (args) => {

package/tfidf.mjs

@@ -381,7 +381,7 @@ export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit
 
   // Fallback: if time-window yields too few, scan without time constraint
   if (rows.length < VECTOR_MIN_RESULTS) {
-    params.push(limit);
+    const fallbackParams = [...params, limit];
     rows = db.prepare(`
       SELECT ov.observation_id, ov.vector
       FROM observation_vectors ov
@@ -389,7 +389,7 @@ export function vectorSearch(db, queryVec, { project, type, vocabVersion, limit
       WHERE ${wheres.join(' AND ')}
       ORDER BY o.created_at_epoch DESC
       LIMIT ?
-    `).all(...params);
+    `).all(...fallbackParams);
   }
 
   const results = [];

package/tool-schemas.mjs

@@ -130,12 +130,12 @@ export const memFtsCheckSchema = {
 };
 
 export const memRegistrySchema = {
-  action: z.enum(['list', 'stats', 'search', 'import', 'remove', 'reindex']).describe('Registry operation'),
+  action: z.enum(['list', 'stats', 'search', 'import', 'remove', 'reindex', 'import_url', 'enrich']).describe('Registry operation'),
   query: z.string().optional().describe('Search query — keywords describing what you need (for search)'),
   type: z.enum(['skill', 'agent']).optional().describe('Filter by resource type (for list/search)'),
   name: z.string().optional().describe('Resource name (for import/remove)'),
   resource_type: z.enum(['skill', 'agent']).optional().describe('Resource type (for import/remove)'),
-  source: z.enum(['preinstalled', 'user']).optional().describe('Source (for import, default: user)'),
+  source: z.enum(['preinstalled', 'user', 'github']).optional().describe('Source (for import, default: user)'),
   repo_url: z.string().optional().describe('GitHub repository URL (for import)'),
   local_path: z.string().optional().describe('Local file path (for import)'),
   invocation_name: z.string().optional().describe('Invocation name like "plugin:skill" (for import)'),
@@ -146,10 +146,17 @@ export const memRegistrySchema = {
   keywords: z.string().optional().describe('Search keywords (for import)'),
   tech_stack: z.string().optional().describe('Technology stack tags (for import)'),
   use_cases: z.string().optional().describe('Usage scenarios (for import)'),
+  url: z.string().optional().describe('GitHub repository URL (for import_url action)'),
+  enrich: coerceBool.optional().describe('Auto-enrich imported resources (for import_url action)'),
   category: z.string().optional().describe("Filter by category (e.g., 'testing', 'code-quality', 'debugging')"),
   quality: z.enum(['installed', 'verified', 'community']).optional().describe('Filter by quality tier (default: all)'),
 };
 
+export const memUseSchema = {
+  name: z.string().min(1).describe('Skill or agent name to load (exact name or search query)'),
+  type: z.enum(['skill', 'agent']).optional().describe('Resource type (default: skill)'),
+};
+
 export const memBrowseSchema = {
   project: z.string().optional().describe('Filter by project (default: inferred from CWD)'),
   tier: z.enum(['working', 'active', 'archive']).optional().describe('Show only this tier'),

package/utils.mjs

@@ -2,7 +2,7 @@
 // Used by server.mjs, hook.mjs, and tests
 
 
-import { basename, dirname } from 'path';
+import { basename, dirname, resolve, sep } from 'path';
 import { execSync } from 'child_process';
 
 // ─── Re-exports from extracted modules ──────────────────────────────────────
@@ -27,6 +27,21 @@ export const COMPRESSED_AUTO = -1;
 /** compressed_into sentinel: pending user-confirmed purge (marked by idle cleanup) */
 export const COMPRESSED_PENDING_PURGE = -2;
 
+// ─── Path Safety ──────────────────────────────────────────────────────────
+
+/**
+ * Check if a resolved path is confined within an allowed base directory.
+ * Prevents path traversal attacks via '../' sequences.
+ * @param {string} candidate Path to check
+ * @param {string} allowedBase Base directory the path must stay within
+ * @returns {boolean} true if safe
+ */
+export function isPathConfined(candidate, allowedBase) {
+  const resolved = resolve(candidate);
+  const base = resolve(allowedBase);
+  return resolved === base || resolved.startsWith(base + sep);
+}
+
 // ─── Token Estimation ─────────────────────────────────────────────────────
 
 /**
@@ -157,9 +172,11 @@ export function isRelatedToEpisode(episode, newFiles) {
  * @param {string} toolName Name of the tool (Edit, Write, Bash, etc.)
  * @param {object} input Tool input parameters
  * @param {string} resp Tool response text
+ * @param {object} [opts] Optional signals from detectBashSignificance
+ * @param {boolean} [opts.isError] If provided, overrides inline error regex detection
  * @returns {string} Concise description of the action
  */
-export function makeEntryDesc(toolName, input, resp) {
+export function makeEntryDesc(toolName, input, resp, opts) {
   switch (toolName) {
     case 'Edit':
       return `${basename(input.file_path || '')}: "${truncate(input.old_string || '', 40)}" → "${truncate(input.new_string || '', 40)}"`;
@@ -169,7 +186,9 @@ export function makeEntryDesc(toolName, input, resp) {
       return `Notebook cell: ${truncate(input.new_source || '', 60)}`;
     case 'Bash': {
       const cmd = truncate(input.command || '', 50);
-      const isErr = /error|fail|exception|panic/i.test(resp) && resp.length > 30;
+      // Use caller-provided bashSig.isError (word-boundary aware) when available;
+      // fall back to inline regex only for standalone callers (tests, etc.)
+      const isErr = opts?.isError ?? (/\berror\b|\bfail(ed|ure)?\b|\bexception\b|\bpanic\b/i.test(resp) && resp.length > 30);
       const snippet = truncate(resp, 60);
       return isErr ? `${cmd} → ERROR: ${snippet}` : `${cmd} → ${snippet}`;
     }