claude-mem-lite 2.3.0 → 2.3.3

package/.claude-plugin/marketplace.json

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

package/.mcp.json

@@ -1,8 +1,3 @@
 {
-  "mcpServers": {
-    "mem": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/launch.mjs"]
-    }
-  }
-}
+  "mcpServers": {}
+}

package/commands/mem.md

@@ -1,4 +1,5 @@
 ---
+name: mem
 description: Search and manage project memory (observations, sessions, prompts)
 ---
 
@@ -13,6 +14,9 @@ Search and browse your project memory efficiently.
 - `/mem save <text>` — Save a manual memory/note
 - `/mem stats` — Show memory statistics
 - `/mem timeline <query>` — Browse timeline around a matching observation
+- `/mem cleanup` — Scan and interactively purge stale data
+- `/mem cleanup [N]d` — Purge stale data older than N days (e.g. `cleanup 60d`)
+- `/mem cleanup keep [N]d` — Purge stale data but retain last N days (e.g. `cleanup keep 14d`)
 
 ## Efficient Search Workflow (3 steps, saves 10x tokens)
 
@@ -29,6 +33,9 @@ When the user invokes `/mem`, parse their intent:
 - `/mem save <text>` → call `mem_save` with the text as content
 - `/mem stats` → call `mem_stats`
 - `/mem timeline <query>` → call `mem_timeline` with the query
+- `/mem cleanup` → run `mem_maintain(action="scan")`, report pending purge count and stale items to user, ask for confirmation, then run `mem_maintain(action="execute", operations=["purge_stale"])` if confirmed
+- `/mem cleanup Nd` (e.g. `60d`) → same as above but use `retain_days=N` to only purge items older than N days
+- `/mem cleanup keep Nd` (e.g. `keep 14d`) → same as above with `retain_days=N`
 - `/mem <query>` (no subcommand) → treat as search, call `mem_search`
 
 Always use the compact index from mem_search first, then mem_get for details only when needed. This minimizes token usage.

package/commands/memory.md

@@ -0,0 +1,51 @@
+---
+name: memory
+description: Save content to memory — with explicit content, instructions, or auto-summarize current session
+---
+
+# Memory Save
+
+Save important content to your long-term memory database.
+
+## Commands
+
+- `/mem:memory <content>` — Save the given content directly to memory
+- `/mem:memory` (no args) — Auto-summarize recent session highlights and save key findings
+
+## Instructions
+
+When the user invokes `/mem:memory`, determine the intent:
+
+### With explicit content
+
+If the user provides content after the command:
+
+1. Analyze the content to determine appropriate type (decision, bugfix, feature, refactor, discovery, change)
+2. Generate a concise title from the content
+3. Call `mem_save` with:
+   - `content`: the provided text
+   - `title`: auto-generated title
+   - `type`: inferred type (default: "discovery")
+   - `importance`: 2 (notable — user explicitly requested save)
+
+### With instructions/prompt
+
+If the user provides instructions like "save the database schema we discussed" or "remember the fix for the auth bug":
+
+1. Review recent conversation context
+2. Extract the relevant information per the user's instruction
+3. Call `mem_save` with extracted content, appropriate title and type, importance=2
+
+### No arguments (auto-save)
+
+If no content is provided:
+
+1. Review the current session's recent key findings
+2. Identify: decisions made, bugs fixed, patterns discovered, important code changes
+3. For each significant finding (max 5), call `mem_save` with:
+   - Clear title and structured content
+   - Appropriate type and importance level (1=routine, 2=notable)
+4. Skip trivial or already-saved items
+5. Report what was saved in a concise summary
+
+Always set importance=2 for explicit saves (user chose to save), importance=1 for auto-saves of routine items, importance=2 for auto-saves of notable discoveries.

package/commands/tools.md

@@ -0,0 +1,78 @@
+---
+name: tools
+description: Import skills and agents from GitHub repositories into the tool resource registry
+---
+
+# Tool Import
+
+Import skills and agents from GitHub repositories into the resource registry for intelligent dispatch.
+
+## Commands
+
+- `/mem:tools <github-url>` — Import all skills/agents from a GitHub repo
+- `/mem:tools <github-url> <instructions>` — Import with specific instructions (add/remove specific items)
+- `/mem:tools <instructions>` — Directly add/remove/modify tools by prompt (no URL needed)
+- `/mem:tools` (no args) — Show current registry stats and import help
+
+## Instructions
+
+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
+
+### With GitHub URL + instructions
+
+If the user provides instructions after the URL:
+- "only add the TDD skill" → import only matching tools from that repo
+- "remove the old testing tool" → call `mem_registry(action="remove", ...)`
+- Follow user instructions for selective add/remove/modify operations
+
+### With instructions only (no URL)
+
+If the user provides a prompt without a GitHub URL, parse the intent:
+
+**Adding a tool:**
+- "添加一个叫 my-linter 的 skill" or "add a skill called my-linter"
+- → Ask for metadata (or infer from context): capability_summary, intent_tags, domain_tags, trigger_patterns
+- → Call `mem_registry(action="import", name="my-linter", resource_type="skill", ...)`
+
+**Removing a tool:**
+- "删除 old-testing skill" or "remove the old-testing agent"
+- → Call `mem_registry(action="remove", name="old-testing", resource_type="skill")`
+
+**Listing/searching:**
+- "有哪些 testing 相关的工具" or "list all agents"
+- → Call `mem_registry(action="list", type="agent")` or search by keywords
+
+**Modifying a tool:**
+- "更新 my-linter 的描述" or "update tags for my-tool"
+- → Call `mem_registry(action="import", ...)` with updated metadata (upsert)
+
+Always call `mem_registry(action="reindex")` after any add/remove/modify operations.
+
+### Without URL or instructions
+
+If no arguments provided:
+1. Call `mem_registry(action="stats")` to show current registry state
+2. Call `mem_registry(action="list")` to show all registered tools
+3. Explain usage examples

package/commands/update.md

@@ -0,0 +1,38 @@
+---
+name: update
+description: Auto-maintain memory and resource registry — deduplicate, merge, decay, cleanup, reindex
+---
+
+# Memory & Registry Maintenance
+
+Run intelligent maintenance on both the memory database and tool resource registry.
+
+## Usage
+
+- `/mem:update` — Run full maintenance cycle
+
+## Instructions
+
+When the user invokes `/mem:update`, perform the following maintenance cycle:
+
+### Phase 1: Memory Maintenance
+
+1. Call `mem_maintain(action="scan")` to analyze maintenance candidates
+2. Report scan results to the user (duplicates, stale items, broken items, boostable items, **pending purge** items)
+3. Call `mem_maintain(action="execute", operations=["cleanup","decay","boost"])` to apply safe automatic changes
+4. If duplicates were found in scan, review them and call `mem_maintain(action="execute", operations=["dedup"], merge_ids=[[keepId, removeId1, ...], ...])` — keep the more important/recent observation in each pair
+5. Run `mem_compress(preview=false)` for old low-value observations
+6. **If pending purge items > 0**: Report the count to the user and ask for confirmation. If confirmed, call `mem_maintain(action="execute", operations=["purge_stale"])`. User may optionally specify `retain_days` (default 30) to control how many days of data to keep. Do NOT purge without explicit user confirmation.
+
+### Phase 2: Registry Maintenance
+
+1. Call `mem_registry(action="stats")` to get registry overview
+2. Call `mem_registry(action="reindex")` to rebuild FTS5 search index
+3. Report updated stats
+
+### Phase 3: Summary
+
+Summarize all maintenance actions taken in zh-CN:
+- Memory: observations cleaned, decayed, boosted, deduplicated, compressed
+- Registry: total resources, adoption rates, reindex status
+- Overall health assessment

package/dispatch-inject.mjs

@@ -2,7 +2,7 @@
 // Formats resource recommendations for Claude Code's additionalContext
 
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { homedir } from 'os';
 import { truncate } from './utils.mjs';
 import { DB_DIR } from './schema.mjs';
@@ -18,13 +18,14 @@ function truncateContent(str, max) {
 
 // Allowed base directories for resource file reads (defense-in-depth)
 const ALLOWED_BASES = [
-  join(homedir(), '.claude'),
-  join(DB_DIR, 'managed'),
+  resolve(join(homedir(), '.claude')),
+  resolve(join(DB_DIR, 'managed')),
 ];
 
 function isAllowedPath(filePath) {
   if (!filePath) return false;
-  return ALLOWED_BASES.some(base => filePath === base || filePath.startsWith(base + '/'));
+  const resolved = resolve(filePath);
+  return ALLOWED_BASES.some(base => resolved === base || resolved.startsWith(base + '/'));
 }
 
 // ─── Template Detection ──────────────────────────────────────────────────────

package/dispatch-workflow.mjs

@@ -0,0 +1,155 @@
+// claude-mem-lite: Workflow-aware dispatch intelligence
+// Suite auto-flow protection, explicit request detection, stage model
+
+// ─── Stage Model ─────────────────────────────────────────────────────────────
+
+export const STAGES = ['ANALYZE', 'PLAN', 'REVIEW_PLAN', 'EXECUTE', 'TEST', 'REVIEW_CODE', 'COMMIT'];
+
+// Skill invocation name → workflow stage
+const SKILL_STAGE_MAP = {
+  'superpowers:brainstorming': 'ANALYZE',
+  'superpowers:writing-plans': 'PLAN',
+  'gsd:start': 'PLAN',
+  'gsd:prd': 'PLAN',
+  'superpowers:executing-plans': 'EXECUTE',
+  'superpowers:subagent-driven-development': 'EXECUTE',
+  'gsd:resume': 'EXECUTE',
+  'superpowers:test-driven-development': 'TEST',
+  'superpowers:systematic-debugging': 'EXECUTE',
+  'superpowers:verification-before-completion': 'TEST',
+  'superpowers:requesting-code-review': 'REVIEW_CODE',
+  'superpowers:receiving-code-review': 'REVIEW_CODE',
+  'superpowers:finishing-a-development-branch': 'COMMIT',
+  'commit-commands:commit': 'COMMIT',
+  'commit-commands:commit-push-pr': 'COMMIT',
+  'commit-commands:clean_gone': 'COMMIT',
+};
+
+// User intent → stage mapping (for stage inference from prompt)
+export const INTENT_STAGE_MAP = {
+  'plan': 'PLAN',
+  'review': 'REVIEW_CODE',
+  'test': 'TEST',
+  'fix': 'EXECUTE',
+  'clean': 'EXECUTE',
+  'commit': 'COMMIT',
+  'deploy': 'COMMIT',
+  'design': 'ANALYZE',
+  'doc': 'COMMIT',
+  'build': 'EXECUTE',
+  'fast': 'EXECUTE',
+  'lint': 'EXECUTE',
+  'db': 'EXECUTE',
+  'api': 'EXECUTE',
+  'secure': 'EXECUTE',
+  'infra': 'EXECUTE',
+};
+
+// ─── Suite Auto-Flow Protection ──────────────────────────────────────────────
+
+export const SUITE_AUTO_FLOWS = {
+  superpowers: {
+    stages: ['ANALYZE', 'PLAN', 'EXECUTE', 'TEST', 'REVIEW_CODE', 'COMMIT'],
+    gaps: ['REVIEW_PLAN'],
+  },
+  gsd: {
+    stages: ['PLAN', 'EXECUTE', 'TEST', 'REVIEW_CODE'],
+    gaps: ['ANALYZE', 'REVIEW_PLAN', 'COMMIT'],
+  },
+  'feature-dev': {
+    stages: ['ANALYZE', 'EXECUTE', 'REVIEW_CODE'],
+    gaps: ['PLAN', 'REVIEW_PLAN', 'TEST', 'COMMIT'],
+  },
+  'commit-commands': {
+    stages: ['COMMIT'],
+    gaps: ['ANALYZE', 'PLAN', 'REVIEW_PLAN', 'EXECUTE', 'TEST', 'REVIEW_CODE'],
+  },
+};
+
+/**
+ * Detect if a suite auto-flow is active based on recent Skill tool events.
+ * Scans backwards to find the most recent Skill invocation from a known suite.
+ * @param {object[]} sessionEvents Array of tool events
+ * @returns {{suite: string, flow: object, lastSkill: string}|null}
+ */
+export function detectActiveSuite(sessionEvents) {
+  if (!sessionEvents || sessionEvents.length === 0) return null;
+
+  for (let i = sessionEvents.length - 1; i >= 0; i--) {
+    const e = sessionEvents[i];
+    if (e.tool_name === 'Skill' && e.tool_input?.skill) {
+      const skill = e.tool_input.skill;
+      const suite = skill.split(':')[0];
+      if (SUITE_AUTO_FLOWS[suite]) {
+        return { suite, flow: SUITE_AUTO_FLOWS[suite], lastSkill: skill };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Determine if a recommendation should be made for the current stage.
+ * @param {{suite: string, flow: object}|null} activeSuite Active suite info
+ * @param {string} currentStage Current workflow stage
+ * @returns {{shouldRecommend: boolean, reason: string}}
+ */
+export function shouldRecommendForStage(activeSuite, currentStage) {
+  if (!activeSuite) return { shouldRecommend: true, reason: 'no_suite' };
+
+  const { flow } = activeSuite;
+  if (flow.stages.includes(currentStage)) {
+    return { shouldRecommend: false, reason: 'suite_covers_stage' };
+  }
+  if (flow.gaps.includes(currentStage)) {
+    return { shouldRecommend: true, reason: 'suite_gap' };
+  }
+  return { shouldRecommend: true, reason: 'unknown_stage' };
+}
+
+/**
+ * Infer the current workflow stage from intent or from the last skill used.
+ * @param {string} primaryIntent Primary intent from signal extraction
+ * @param {{lastSkill: string}|null} activeSuite Active suite info
+ * @returns {string|null} Stage name or null
+ */
+export function inferCurrentStage(primaryIntent, activeSuite) {
+  if (activeSuite?.lastSkill && SKILL_STAGE_MAP[activeSuite.lastSkill]) {
+    return SKILL_STAGE_MAP[activeSuite.lastSkill];
+  }
+  return INTENT_STAGE_MAP[primaryIntent] || null;
+}
+
+// ─── Explicit Request Detection ──────────────────────────────────────────────
+
+const EXPLICIT_REQUEST_PATTERNS = [
+  // EN: "use the playwright skill", "try the ppt skill"
+  /(?:use|try|invoke|run|activate|load)\s+(?:the\s+)?(\S+?)\s+(?:skill|agent|tool|plugin)\b/i,
+  // CN: "用ppt的技能", "帮我用playwright的skill"
+  /(?:用|使用|帮我用|试试|启用)\s*(\S+?)\s*(?:的|的技能|的skill|的agent|技能|skill|agent|工具|插件)/,
+  // "有没有xxx的skill", "is there a xxx agent"
+  /(?:有没有|有无|是否有|do you have|is there)\s*(?:一个|a|an)?\s*(\S+?)\s*(?:的|skill|agent|技能|工具)/i,
+  // "推荐一个xxx", "recommend a xxx agent"
+  /(?:推荐|suggest|recommend)\s*(?:一个|a|an)?\s*(\S+?)\s*(?:的|skill|agent|技能|工具)/i,
+];
+
+/**
+ * Detect if the user is explicitly requesting a specific tool/skill.
+ * Highest priority — bypasses all dispatch restrictions.
+ * @param {string} userPrompt User's prompt text
+ * @returns {{isExplicit: boolean, searchTerm?: string}}
+ */
+export function detectExplicitRequest(userPrompt) {
+  if (!userPrompt) return { isExplicit: false };
+
+  for (const pattern of EXPLICIT_REQUEST_PATTERNS) {
+    const match = userPrompt.match(pattern);
+    if (match && match[1]) {
+      const term = match[1].replace(/['"]/g, '').trim();
+      if (term.length >= 2 && term.length <= 30) {
+        return { isExplicit: true, searchTerm: term };
+      }
+    }
+  }
+  return { isExplicit: false };
+}

package/dispatch.mjs

@@ -32,22 +32,28 @@ export const BM25_MIN_THRESHOLD = 1.5;
 // ─── Haiku Circuit Breaker ──────────────────────────────────────────────────
 // Prevents cascading latency when Haiku API is down or slow.
 // After BREAKER_THRESHOLD consecutive failures, disable for BREAKER_RESET_MS.
+// KNOWN LIMITATION: File-based state has a TOCTOU race under concurrent hook
+// processes. Worst case: breaker trips on failure N+1 instead of N. This is
+// acceptable — the breaker is a latency guard, not a correctness mechanism.
 
 const BREAKER_THRESHOLD = 3;
 const BREAKER_RESET_MS = 5 * 60 * 1000; // 5 minutes
-const BREAKER_FILE = join(RUNTIME_DIR, 'haiku-breaker.json');
+let breakerFile = join(RUNTIME_DIR, 'haiku-breaker.json');
 
 function _readBreakerState() {
   try {
-    if (!existsSync(BREAKER_FILE)) return { failures: 0, openUntil: 0 };
-    return JSON.parse(readFileSync(BREAKER_FILE, 'utf8'));
+    if (!existsSync(breakerFile)) return { failures: 0, openUntil: 0 };
+    return JSON.parse(readFileSync(breakerFile, 'utf8'));
   } catch { return { failures: 0, openUntil: 0 }; }
 }
 
 function _writeBreakerState(state) {
-  try { writeFileSync(BREAKER_FILE, JSON.stringify(state)); } catch {}
+  try { writeFileSync(breakerFile, JSON.stringify(state)); } catch {}
 }
 
+/** Override breaker file path (for testing isolation). */
+export function _setBreakerFile(path) { breakerFile = path; }
+
 function isHaikuCircuitOpen() {
   const state = _readBreakerState();
   if (state.openUntil > 0 && Date.now() < state.openUntil) return true;
@@ -636,15 +642,27 @@ JSON: {"query":"search keywords for finding the right skill or agent","type":"sk
 
 // ─── Cooldown & Dedup (DB-persisted, survives process restarts) ─────────────
 
+/**
+ * Check if session has hit the recommendation cap.
+ * Separated from per-resource check so callers in filter loops can hoist this.
+ * @param {Database} db Registry database
+ * @param {string} sessionId Session identifier
+ * @returns {boolean} true if session cap is reached
+ */
+export function isSessionCapped(db, sessionId) {
+  if (!sessionId) return false;
+  const sessionCount = db.prepare(
+    'SELECT COUNT(*) as cnt FROM invocations WHERE session_id = ? AND recommended = 1'
+  ).get(sessionId);
+  return sessionCount.cnt >= SESSION_RECOMMEND_CAP;
+}
+
 export function isRecentlyRecommended(db, resourceId, sessionId) {
-  // Check 1 & 2: Session-scoped checks (cap + dedup) — only when sessionId is available
+  // Check 1: Session cap (loop-invariant — callers should prefer isSessionCapped for filter loops)
   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;
+    if (isSessionCapped(db, sessionId)) return true;
 
-    // Already recommended in this session (session dedup)
+    // Check 2: Already recommended in this session (session dedup)
     const sessionHit = db.prepare(
       'SELECT 1 FROM invocations WHERE resource_id = ? AND session_id = ? AND recommended = 1 LIMIT 1'
     ).get(resourceId, sessionId);
@@ -857,7 +875,8 @@ export async function dispatchOnSessionStart(db, userPrompt, sessionId, { hasHan
 
     if (results.length === 0) return null;
 
-    // Filter by DB-persisted cooldown + session dedup
+    // Filter by DB-persisted cooldown + session dedup (hoisted cap check avoids N queries)
+    if (sessionId && isSessionCapped(db, sessionId)) return null;
     const viable = sessionId
       ? results.filter(r => !isRecentlyRecommended(db, r.id, sessionId))
       : results;
@@ -895,12 +914,13 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
   if (!userPrompt || !db) return null;
 
   try {
-    // 1. Explicit request → highest priority, bypass all restrictions
+    // 1. Explicit request → highest priority, bypass cooldown but apply adoption decay
     const explicit = detectExplicitRequest(userPrompt);
     if (explicit.isExplicit) {
       const textQuery = buildQueryFromText(explicit.searchTerm);
       if (textQuery) {
-        const explicitResults = retrieveResources(db, textQuery, { limit: 3, projectDomains: detectProjectDomains() });
+        let explicitResults = retrieveResources(db, textQuery, { limit: 3, projectDomains: detectProjectDomains() });
+        explicitResults = applyAdoptionDecay(explicitResults, db);
         if (explicitResults.length > 0) {
           const best = explicitResults[0];
           if (!sessionId || !isRecentlyRecommended(db, best.id, sessionId)) {
@@ -960,7 +980,8 @@ export async function dispatchOnUserPrompt(db, userPrompt, sessionId, { sessionE
     // Low confidence → skip (no Haiku in user_prompt path — stay fast)
     if (needsHaikuDispatch(results)) return null;
 
-    // Filter by cooldown + session dedup (prevents double-recommend with SessionStart)
+    // Filter by cooldown + session dedup (hoisted cap check avoids N queries)
+    if (sessionId && isSessionCapped(db, sessionId)) return null;
     const viable = sessionId
       ? results.filter(r => !isRecentlyRecommended(db, r.id, sessionId))
       : results;
@@ -1028,8 +1049,9 @@ export async function dispatchOnPreToolUse(db, event, sessionCtx = {}) {
     // Low-confidence results: skip recommendation rather than suggest unreliable match
     if (needsHaikuDispatch(results)) return null;
 
-    // Apply DB-persisted cooldown and session dedup (filter all, not just top)
+    // Apply DB-persisted cooldown and session dedup (hoisted cap check avoids N queries)
     const sid = sessionCtx.sessionId || null;
+    if (sid && isSessionCapped(db, sid)) return null;
     const viable = sid
       ? results.filter(r => !isRecentlyRecommended(db, r.id, sid))
       : results;