claude-mem-lite 2.3.0 → 2.3.1

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,37 @@
+---
+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)
+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
+
+### 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-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/hook-handoff.mjs

@@ -0,0 +1,222 @@
+// claude-mem-lite: Cross-session handoff extraction, detection, and injection
+// Extracted for testability — hook.mjs has module-level side effects
+
+import { basename } from 'path';
+import { truncate, extractMatchKeywords, tokenizeHandoff, isSpecificTerm } from './utils.mjs';
+import {
+  HANDOFF_EXPIRY_CLEAR, HANDOFF_EXPIRY_EXIT, HANDOFF_MATCH_THRESHOLD, CONTINUE_KEYWORDS,
+} from './hook-shared.mjs';
+
+/**
+ * Build and save a handoff snapshot to session_handoffs table.
+ * Called synchronously during handleStop (/exit) or handleSessionStart (/clear).
+ * @param {Database} db Opened main database
+ * @param {string} sessionId Session being handed off
+ * @param {string} project Project identifier
+ * @param {'clear'|'exit'} type Handoff type
+ * @param {object|null} episodeSnapshot Episode buffer captured before flushing
+ */
+export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapshot) {
+  // 1. Working objective — from user prompts
+  const prompts = db.prepare(`
+    SELECT prompt_text FROM user_prompts
+    WHERE content_session_id = ?
+    ORDER BY prompt_number ASC LIMIT 5
+  `).all(sessionId);
+  if (prompts.length === 0) return;  // Empty session — nothing to hand off
+
+  const workingOn = prompts.map(p => truncate(p.prompt_text, 200)).join(' → ');
+
+  // 2. Completed — from observations (include narrative for richer handoff)
+  const completed = db.prepare(`
+    SELECT title, type, narrative FROM observations
+    WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0
+    ORDER BY created_at_epoch DESC LIMIT 15
+  `).all(sessionId);
+
+  // 3. Unfinished — episode snapshot + full session edit history from narratives
+  let unfinished = '';
+  if (episodeSnapshot?.entries) {
+    const pendingDescs = episodeSnapshot.entries
+      .filter(e => e.isSignificant || e.isError)
+      .map(e => e.desc);
+    if (pendingDescs.length > 0) unfinished = pendingDescs.join('; ');
+  }
+  // Only the most recent bugfix is an "unfinished" signal (earlier ones are likely resolved)
+  if (!unfinished) {
+    const lastBugfix = completed.find(o => o.type === 'bugfix');
+    if (lastBugfix) unfinished = lastBugfix.title;
+  }
+  // Enrich unfinished with full session edit history from observation narratives.
+  // Since handoff is UPSERT (max 2 rows per project), storing more data is free.
+  const narratives = completed
+    .filter(c => c.narrative)
+    .map(c => c.narrative);
+  if (narratives.length > 0) {
+    const editHistory = narratives.join('\n');
+    unfinished = [unfinished, editHistory].filter(Boolean).join('\n---\n');
+  }
+
+  // 4. Key files — from episode snapshot + observations
+  const fileSet = new Set();
+  if (episodeSnapshot?.files) episodeSnapshot.files.forEach(f => fileSet.add(f));
+  const obsFiles = db.prepare(`
+    SELECT files_modified FROM observations
+    WHERE memory_session_id = ? AND files_modified IS NOT NULL
+    ORDER BY created_at_epoch DESC LIMIT 10
+  `).all(sessionId);
+  for (const row of obsFiles) {
+    try { JSON.parse(row.files_modified).forEach(f => fileSet.add(f)); } catch {}
+  }
+
+  // 5. Key decisions — high importance observations
+  const decisions = db.prepare(`
+    SELECT title FROM observations
+    WHERE memory_session_id = ? AND COALESCE(importance, 1) >= 2
+      AND COALESCE(compressed_into, 0) = 0
+    ORDER BY created_at_epoch DESC LIMIT 5
+  `).all(sessionId);
+
+  // 6. Match keywords
+  const allText = [workingOn, ...completed.map(c => c.title).filter(Boolean), unfinished].join(' ');
+  const keywords = extractMatchKeywords(allText, [...fileSet]);
+
+  // UPSERT
+  db.prepare(`
+    INSERT INTO session_handoffs (project, type, session_id, working_on, completed, unfinished, key_files, key_decisions, match_keywords, created_at_epoch)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(project, type) DO UPDATE SET
+      session_id = excluded.session_id,
+      working_on = excluded.working_on,
+      completed = excluded.completed,
+      unfinished = excluded.unfinished,
+      key_files = excluded.key_files,
+      key_decisions = excluded.key_decisions,
+      match_keywords = excluded.match_keywords,
+      created_at_epoch = excluded.created_at_epoch
+  `).run(
+    project, type, sessionId,
+    truncate(workingOn, 1000),
+    completed.map(c => `[${c.type}] ${c.title}`).join('\n'),
+    truncate(unfinished, 3000),
+    JSON.stringify([...fileSet].slice(0, 20)),
+    decisions.map(d => d.title).join('\n'),
+    keywords,
+    Date.now()
+  );
+}
+
+/**
+ * Detect if user's prompt indicates continuation of previous work.
+ * Stage 1: Explicit keyword match (zero false positives).
+ * Stage 2: FTS5-style term overlap with handoff keywords.
+ * @param {Database} db Opened main database
+ * @param {string} promptText User's prompt text
+ * @param {string} project Project identifier
+ * @returns {boolean}
+ */
+export function detectContinuationIntent(db, promptText, project) {
+  // Stage 1: Explicit keyword match — always works, even without handoff
+  if (CONTINUE_KEYWORDS.test(promptText)) return true;
+
+  // Stage 2: FTS5-style term overlap with handoff keywords
+  const handoffs = db.prepare(`
+    SELECT type, match_keywords, created_at_epoch FROM session_handoffs
+    WHERE project = ? ORDER BY created_at_epoch DESC
+  `).all(project);
+  if (handoffs.length === 0) return false;
+
+  // Filter expired handoffs
+  const now = Date.now();
+  const validHandoffs = handoffs.filter(h => {
+    const age = now - h.created_at_epoch;
+    const maxAge = h.type === 'clear' ? HANDOFF_EXPIRY_CLEAR : HANDOFF_EXPIRY_EXIT;
+    return age <= maxAge;
+  });
+  if (validHandoffs.length === 0) return false;
+
+  // Use the most recent valid handoff for keyword matching
+  const handoff = validHandoffs[0];
+  const promptTokens = tokenizeHandoff(promptText);
+  const handoffTokens = new Set(tokenizeHandoff(handoff.match_keywords));
+
+  let score = 0;
+  for (const token of promptTokens) {
+    if (handoffTokens.has(token)) {
+      score += isSpecificTerm(token) ? 2 : 1;
+    }
+  }
+
+  return score >= HANDOFF_MATCH_THRESHOLD;
+}
+
+/**
+ * Render handoff injection text for stdout.
+ * Reads the most recent handoff + optional session summary.
+ * @param {Database} db Opened main database
+ * @param {string} project Project identifier
+ * @returns {string|null} Injection text or null if no handoff
+ */
+export function renderHandoffInjection(db, project) {
+  const now = Date.now();
+  // Fetch recent handoffs and find the most recent non-expired one.
+  // A newer but expired 'clear' handoff (1h) must not shadow a still-valid 'exit' handoff (7d).
+  const handoffs = db.prepare(`
+    SELECT * FROM session_handoffs
+    WHERE project = ? ORDER BY created_at_epoch DESC LIMIT 5
+  `).all(project);
+  const handoff = handoffs.find(h => {
+    const age = now - h.created_at_epoch;
+    const maxAge = h.type === 'clear' ? HANDOFF_EXPIRY_CLEAR : HANDOFF_EXPIRY_EXIT;
+    return age <= maxAge;
+  });
+  if (!handoff) return null;
+
+  const ageSec = Math.round((Date.now() - handoff.created_at_epoch) / 1000);
+  const ageStr = ageSec < 60 ? `${ageSec}s` :
+    ageSec < 3600 ? `${Math.round(ageSec / 60)}m` :
+    ageSec < 86400 ? `${Math.round(ageSec / 3600)}h` :
+    `${Math.round(ageSec / 86400)}d`;
+
+  const lines = [`<session-handoff source="${handoff.type}" age="${ageStr}">`];
+
+  if (handoff.working_on) {
+    lines.push('## Working On', handoff.working_on, '');
+  }
+  if (handoff.completed) {
+    lines.push('## Completed', ...handoff.completed.split('\n').map(l => `- ${l}`), '');
+  }
+  if (handoff.unfinished) {
+    lines.push('## Unfinished', ...handoff.unfinished.split('; ').map(l => `- ${l}`), '');
+  }
+  if (handoff.key_files) {
+    try {
+      const files = JSON.parse(handoff.key_files);
+      if (files.length > 0) lines.push('## Key Files', files.map(f => basename(f)).join(', '), '');
+    } catch {}
+  }
+  if (handoff.key_decisions) {
+    lines.push('## Key Decisions', ...handoff.key_decisions.split('\n').map(l => `- ${l}`), '');
+  }
+
+  lines.push('</session-handoff>');
+
+  // Append session summary if available (long-gap enrichment)
+  try {
+    const summary = db.prepare(`
+      SELECT completed, next_steps, remaining_items FROM session_summaries
+      WHERE memory_session_id = ? AND project = ?
+      ORDER BY created_at_epoch DESC LIMIT 1
+    `).get(handoff.session_id, project);
+    if (summary && (summary.completed || summary.next_steps || summary.remaining_items)) {
+      lines.push('');
+      lines.push('<session-summary source="haiku">');
+      if (summary.completed) lines.push(summary.completed);
+      if (summary.remaining_items) lines.push(`Remaining: ${summary.remaining_items}`);
+      if (summary.next_steps) lines.push(`Next steps: ${summary.next_steps}`);
+      lines.push('</session-summary>');
+    }
+  } catch {}
+
+  return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {
@@ -32,10 +32,12 @@
     "hook-semaphore.mjs",
     "hook-episode.mjs",
     "hook-context.mjs",
+    "hook-handoff.mjs",
     "haiku-client.mjs",
     "dispatch.mjs",
     "dispatch-inject.mjs",
     "dispatch-feedback.mjs",
+    "dispatch-workflow.mjs",
     "registry.mjs",
     "registry-retriever.mjs",
     "registry-indexer.mjs",
@@ -47,6 +49,9 @@
     "schema.mjs",
     "skill.md",
     "commands/mem.md",
+    "commands/memory.md",
+    "commands/update.md",
+    "commands/tools.md",
     "hooks/hooks.json",
     "scripts/launch.mjs",
     "scripts/setup.sh",