claude-mem-lite 2.2.3 → 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/install.mjs

@@ -564,6 +564,27 @@ const RESOURCE_METADATA = {
     capability_summary: 'Autonomous skill extraction and continuous learning from Claude Code work sessions',
     trigger_patterns: 'when user wants to extract reusable skills from work sessions or enable continuous learning',
   },
+  'skill:mem-memory': {
+    intent_tags: 'memory,save,store,remember,note,record,persist,auto-save',
+    domain_tags: 'memory,ai,claude',
+    capability_summary: 'Save content to memory — with explicit content, instructions, or auto-summarize current session',
+    trigger_patterns: 'when user wants to save something to memory or auto-save session highlights',
+    invocation_name: 'claude-mem-lite:memory',
+  },
+  'skill:mem-update': {
+    intent_tags: 'maintenance,cleanup,deduplicate,decay,optimize,reindex,health',
+    domain_tags: 'memory,registry,maintenance',
+    capability_summary: 'Auto-maintain memory and resource registry — deduplicate, merge, decay, cleanup, reindex',
+    trigger_patterns: 'when user wants to clean up memory database or maintain the tool registry',
+    invocation_name: 'claude-mem-lite:update',
+  },
+  'skill:mem-tools': {
+    intent_tags: 'import,tools,github,skills,agents,registry,add,discover',
+    domain_tags: 'memory,registry,github,tools',
+    capability_summary: 'Import skills and agents from GitHub repositories into the tool resource registry',
+    trigger_patterns: 'when user wants to import or add new skills and agents from GitHub to the tool registry',
+    invocation_name: 'claude-mem-lite:tools',
+  },
   'skill:anthropic-architect': {
     intent_tags: 'anthropic,architecture,system-design,claude,patterns,best-practices',
     domain_tags: 'anthropic,architecture,ai',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.2.3",
+  "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",

package/server.mjs

@@ -5,9 +5,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { jaccardSimilarity, truncate, typeIcon, sanitizeFtsQuery, relaxFtsQueryToOr, inferProject, computeMinHash, scrubSecrets, fmtDate, isoWeekKey, debugLog, debugCatch } from './utils.mjs';
-import { ensureDb, DB_PATH } from './schema.mjs';
+import { ensureDb, DB_PATH, DB_DIR } from './schema.mjs';
 import { reRankWithContext, markSuperseded, extractPRFTerms, expandQueryByConcepts } from './server-internals.mjs';
-import { memSearchSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema } from './tool-schemas.mjs';
+import { memSearchSchema, memTimelineSchema, memGetSchema, memDeleteSchema, memSaveSchema, memStatsSchema, memCompressSchema, memMaintainSchema, memRegistrySchema } from './tool-schemas.mjs';
+import { ensureRegistryDb, upsertResource } from './registry.mjs';
+import { join } from 'path';
 
 // ─── Database ───────────────────────────────────────────────────────────────
 
@@ -34,6 +36,22 @@ try {
 // Server process uses longer busy_timeout for concurrent MCP requests
 db.pragma('busy_timeout = 5000');
 
+// ─── Registry Database (lazy-loaded on first mem_registry call) ─────────────
+
+const REGISTRY_DB_PATH = join(DB_DIR, 'resource-registry.db');
+let registryDb = null;
+
+function getRegistryDb() {
+  if (registryDb) return registryDb;
+  try {
+    registryDb = ensureRegistryDb(REGISTRY_DB_PATH);
+    registryDb.pragma('busy_timeout = 3000');
+  } catch (e) {
+    debugLog('WARN', 'server', `Registry DB not available: ${e.message}`);
+  }
+  return registryDb;
+}
+
 // inferProject, jaccardSimilarity, sanitizeFtsQuery, typeIcon, truncate, fmtDate imported from utils.mjs
 
 // ─── Scoring Model Constants ────────────────────────────────────────────────
@@ -977,6 +995,245 @@ server.registerTool(
   })
 );
 
+// ─── Tool: mem_maintain ──────────────────────────────────────────────────────
+
+server.registerTool(
+  'mem_maintain',
+  {
+    description: 'Memory maintenance: scan for duplicates/stale/broken items, then execute cleanup/decay/boost/dedup operations.',
+    inputSchema: memMaintainSchema,
+  },
+  safeHandler(async (args) => {
+    const STALE_AGE_MS = 30 * 86400000;
+    const SIMILARITY_THRESHOLD = 0.7;
+    const SCAN_LIMIT = 500;
+    const DUPLICATE_LIMIT = 50;
+    const DUPLICATE_DISPLAY = 15;
+
+    const action = args.action;
+    const project = args.project;
+    const projectFilter = project ? 'AND project = ?' : '';
+    const baseParams = project ? [project] : [];
+
+    if (action === 'scan') {
+      // 1. Find near-duplicate titles (pre-compute word sets, then O(n²) Jaccard)
+      const recent = db.prepare(`
+        SELECT id, title, project, importance, access_count, created_at_epoch
+        FROM observations
+        WHERE COALESCE(compressed_into, 0) = 0 ${projectFilter}
+        ORDER BY created_at_epoch DESC
+        LIMIT ${SCAN_LIMIT}
+      `).all(...baseParams);
+
+      const wordSets = recent.map(r => new Set((r.title || '').toLowerCase().split(/\s+/).filter(w => w.length > 2)));
+      const duplicates = [];
+      for (let i = 0; i < recent.length && duplicates.length < DUPLICATE_LIMIT; i++) {
+        if (wordSets[i].size === 0) continue;
+        for (let j = i + 1; j < recent.length; j++) {
+          if (wordSets[j].size === 0) continue;
+          const sim = jaccardSimilarity(wordSets[i], wordSets[j]);
+          if (sim > SIMILARITY_THRESHOLD) {
+            duplicates.push({
+              a: { id: recent[i].id, title: recent[i].title, importance: recent[i].importance },
+              b: { id: recent[j].id, title: recent[j].title, importance: recent[j].importance },
+              similarity: sim.toFixed(2),
+            });
+          }
+          if (duplicates.length >= DUPLICATE_LIMIT) break;
+        }
+      }
+
+      // 2. Consolidated stats query (single table scan instead of 4 separate COUNTs)
+      const staleAge = Date.now() - STALE_AGE_MS;
+      const stats = db.prepare(`
+        SELECT
+          COUNT(*) as total,
+          SUM(CASE WHEN COALESCE(importance, 1) = 1 AND COALESCE(access_count, 0) = 0
+                        AND created_at_epoch < ? THEN 1 ELSE 0 END) as stale,
+          SUM(CASE WHEN (title IS NULL OR title = '') AND (narrative IS NULL OR narrative = '')
+                   THEN 1 ELSE 0 END) as broken,
+          SUM(CASE WHEN COALESCE(access_count, 0) > 3 AND COALESCE(importance, 1) < 3
+                   THEN 1 ELSE 0 END) as boostable
+        FROM observations
+        WHERE COALESCE(compressed_into, 0) = 0 ${projectFilter}
+      `).get(staleAge, ...baseParams);
+
+      const lines = [
+        `Memory maintenance scan:`,
+        `  Total active observations: ${stats.total}`,
+        `  Near-duplicate pairs: ${duplicates.length}`,
+        `  Stale (>30d, imp=1, no access): ${stats.stale}`,
+        `  Broken (no title/narrative): ${stats.broken}`,
+        `  Boostable (accessed>3, imp<3): ${stats.boostable}`,
+      ];
+      if (duplicates.length > 0) {
+        lines.push('', 'Top duplicates:');
+        for (const d of duplicates.slice(0, DUPLICATE_DISPLAY)) {
+          lines.push(`  [${d.a.id}] "${truncate(d.a.title, 40)}" <-> [${d.b.id}] "${truncate(d.b.title, 40)}" (${d.similarity})`);
+        }
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+
+    if (action === 'execute') {
+      const ops = args.operations || [];
+      const results = [];
+      const staleAge = Date.now() - STALE_AGE_MS;
+
+      db.transaction(() => {
+        if (ops.includes('cleanup')) {
+          const deleted = db.prepare(`
+            DELETE FROM observations
+            WHERE COALESCE(compressed_into, 0) = 0
+              AND (title IS NULL OR title = '')
+              AND (narrative IS NULL OR narrative = '')
+              ${projectFilter}
+          `).run(...baseParams);
+          results.push(`Cleaned up ${deleted.changes} broken observations`);
+        }
+
+        if (ops.includes('decay')) {
+          const decayed = db.prepare(`
+            UPDATE observations SET importance = MAX(1, COALESCE(importance, 1) - 1)
+            WHERE COALESCE(compressed_into, 0) = 0
+              AND COALESCE(importance, 1) > 1
+              AND COALESCE(access_count, 0) = 0
+              AND created_at_epoch < ?
+              ${projectFilter}
+          `).run(staleAge, ...baseParams);
+          results.push(`Decayed ${decayed.changes} stale observations`);
+        }
+
+        if (ops.includes('boost')) {
+          const boosted = db.prepare(`
+            UPDATE observations SET importance = MIN(3, COALESCE(importance, 1) + 1)
+            WHERE COALESCE(compressed_into, 0) = 0
+              AND COALESCE(access_count, 0) > 3
+              AND COALESCE(importance, 1) < 3
+              ${projectFilter}
+          `).run(...baseParams);
+          results.push(`Boosted ${boosted.changes} frequently-accessed observations`);
+        }
+
+        if (ops.includes('dedup') && args.merge_ids) {
+          let totalMerged = 0;
+          const mergeStmt = db.prepare('UPDATE observations SET compressed_into = ? WHERE id = ? AND COALESCE(compressed_into, 0) = 0');
+          for (const group of args.merge_ids) {
+            if (group.length < 2) continue;
+            const [keepId, ...removeIds] = group;
+            for (const removeId of removeIds) mergeStmt.run(keepId, removeId);
+            totalMerged += removeIds.length;
+          }
+          results.push(`Merged ${totalMerged} duplicate observations`);
+        }
+      })();
+
+      // FTS5 optimize (outside transaction)
+      db.exec("INSERT INTO observations_fts(observations_fts) VALUES('optimize')");
+      results.push('FTS5 index optimized');
+
+      return { content: [{ type: 'text', text: results.join('\n') }] };
+    }
+
+    return { content: [{ type: 'text', text: `Unknown action: ${action}. Use "scan" or "execute".` }], isError: true };
+  })
+);
+
+// ─── Tool: mem_registry ─────────────────────────────────────────────────────
+
+server.registerTool(
+  'mem_registry',
+  {
+    description: 'Manage tool resource registry: list resources, view stats, import/remove tools, reindex FTS5.',
+    inputSchema: memRegistrySchema,
+  },
+  safeHandler(async (args) => {
+    const rdb = getRegistryDb();
+    if (!rdb) {
+      return { content: [{ type: 'text', text: 'Registry DB not available. Run install first.' }], isError: true };
+    }
+
+    const action = args.action;
+
+    if (action === 'list') {
+      const typeFilter = args.type;
+      const where = typeFilter ? 'WHERE type = ? AND status = ?' : 'WHERE status = ?';
+      const params = typeFilter ? [typeFilter, 'active'] : ['active'];
+      const resources = rdb.prepare(`
+        SELECT name, type, invocation_name, recommend_count, adopt_count, capability_summary
+        FROM resources ${where} ORDER BY type, name
+      `).all(...params);
+
+      if (resources.length === 0) return { content: [{ type: 'text', text: 'No resources found.' }] };
+
+      const lines = resources.map(r =>
+        `${r.type === 'skill' ? 'S' : 'A'} ${r.name}${r.invocation_name ? ` (${r.invocation_name})` : ''} — rec:${r.recommend_count} adopt:${r.adopt_count} — ${truncate(r.capability_summary || '', 60)}`
+      );
+      return { content: [{ type: 'text', text: `Resources (${resources.length}):\n${lines.join('\n')}` }] };
+    }
+
+    if (action === 'stats') {
+      const total = rdb.prepare('SELECT COUNT(*) as c FROM resources WHERE status = ?').get('active');
+      const byType = rdb.prepare('SELECT type, COUNT(*) as c FROM resources WHERE status = ? GROUP BY type').all('active');
+      const topAdopted = rdb.prepare(`
+        SELECT name, type, adopt_count, recommend_count
+        FROM resources WHERE status = ? AND adopt_count > 0
+        ORDER BY adopt_count DESC LIMIT 10
+      `).all('active');
+      const zeroAdopt = rdb.prepare(`
+        SELECT COUNT(*) as c FROM resources
+        WHERE status = ? AND recommend_count > 0 AND adopt_count = 0
+      `).get('active');
+      const userAdded = rdb.prepare(`
+        SELECT COUNT(*) as c FROM resources WHERE status = ? AND source = 'user'
+      `).get('active');
+
+      const lines = [
+        `Registry Stats:`,
+        `  Total active: ${total.c}`,
+        ...byType.map(t => `  ${t.type}: ${t.c}`),
+        `  User-added: ${userAdded.c}`,
+        `  Zero adoption (recommended but never adopted): ${zeroAdopt.c}`,
+      ];
+      if (topAdopted.length > 0) {
+        lines.push('', 'Top adopted:');
+        for (const r of topAdopted) {
+          lines.push(`  ${r.name} (${r.type}): ${r.adopt_count}/${r.recommend_count}`);
+        }
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+
+    if (action === 'import') {
+      if (!args.name || !args.resource_type) {
+        return { content: [{ type: 'text', text: 'import requires name and resource_type' }], isError: true };
+      }
+      const IMPORT_STRING_FIELDS = ['repo_url', 'local_path', 'invocation_name', 'intent_tags',
+        'domain_tags', 'trigger_patterns', 'capability_summary', 'keywords', 'tech_stack', 'use_cases'];
+      const fields = { name: args.name, type: args.resource_type, status: 'active', source: args.source || 'user' };
+      for (const f of IMPORT_STRING_FIELDS) fields[f] = args[f] || '';
+      const id = upsertResource(rdb, fields);
+      return { content: [{ type: 'text', text: `Imported: ${args.resource_type}:${args.name} (id=${id})` }] };
+    }
+
+    if (action === 'remove') {
+      if (!args.name || !args.resource_type) {
+        return { content: [{ type: 'text', text: 'remove requires name and resource_type' }], isError: true };
+      }
+      const result = rdb.prepare('DELETE FROM resources WHERE type = ? AND name = ?').run(args.resource_type, args.name);
+      return { content: [{ type: 'text', text: result.changes > 0 ? `Removed: ${args.resource_type}:${args.name}` : 'Not found.' }] };
+    }
+
+    if (action === 'reindex') {
+      rdb.exec("INSERT INTO resources_fts(resources_fts) VALUES('rebuild')");
+      const count = rdb.prepare('SELECT COUNT(*) as c FROM resources WHERE status = ?').get('active');
+      return { content: [{ type: 'text', text: `FTS5 reindexed. ${count.c} active resources.` }] };
+    }
+
+    return { content: [{ type: 'text', text: `Unknown action: ${action}. Valid: list, stats, import, remove, reindex` }], isError: true };
+  })
+);
+
 // ─── WAL Checkpoint (periodic) ───────────────────────────────────────────────
 
 // Checkpoint WAL every 5 minutes to prevent unbounded growth
@@ -1042,6 +1299,7 @@ function shutdown(exitCode = 0) {
   clearInterval(idleTimer);
   try { db.pragma('wal_checkpoint(TRUNCATE)'); } catch {}
   try { db.close(); } catch {}
+  try { if (registryDb) registryDb.close(); } catch {}
   process.exit(exitCode);
 }
 process.on('SIGINT', () => shutdown(0));

package/tool-schemas.mjs

@@ -54,3 +54,30 @@ export const memCompressSchema = {
   age_days: z.number().int().min(30).max(365).optional().describe('Min age in days (default: 60)'),
   project: z.string().optional().describe('Filter by project'),
 };
+
+export const memMaintainSchema = {
+  action: z.enum(['scan', 'execute']).describe('scan=analyze candidates, execute=apply changes'),
+  operations: z.array(z.enum(['dedup', 'decay', 'cleanup', 'boost'])).optional()
+    .describe('Operations to execute (for action=execute)'),
+  merge_ids: z.array(z.array(z.number().int()).min(2)).optional()
+    .describe('For dedup: [[keepId, removeId1, removeId2], ...] — first ID in each group is kept'),
+  project: z.string().optional().describe('Filter by project'),
+};
+
+export const memRegistrySchema = {
+  action: z.enum(['list', 'stats', 'import', 'remove', 'reindex']).describe('Registry operation'),
+  type: z.enum(['skill', 'agent']).optional().describe('Filter by resource type (for list)'),
+  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)'),
+  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)'),
+  intent_tags: z.string().optional().describe('Comma-separated intent tags (for import)'),
+  domain_tags: z.string().optional().describe('Comma-separated domain/tech tags (for import)'),
+  trigger_patterns: z.string().optional().describe('When to recommend this tool (for import)'),
+  capability_summary: z.string().optional().describe('What this tool does (for import)'),
+  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)'),
+};