feat: merge memory:compact and memory:tips into unified memory-capture skill

Consolidate two separate commands into a single skill with router pattern. The skill auto-detects user intent and routes to compact or tips phase, with AskUserQuestion fallback for ambiguous input.
2026-02-15 02:42:45 +08:00 · 2026-02-13 17:42:41 +08:00
parent bcb736709f
commit d750290f84
5 changed files with 589 additions and 715 deletions
--- a/.claude/skills/memory-capture/SKILL.md
+++ b/.claude/skills/memory-capture/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: memory-capture
+description: Unified memory capture with routing - session compact or quick tips. Triggers on "memory capture", "compact session", "save session", "quick tip", "memory tips", "记录", "压缩会话".
+allowed-tools: mcp__ccw-tools__core_memory(*), Read(*), AskUserQuestion
+---
+
+# Memory Capture Skill
+
+Unified memory capture skill that routes to two execution modes:
+- **Compact**: Compress full session memory into structured text for recovery
+- **Tips**: Quick note-taking for ideas, snippets, and insights
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Memory Capture (Router)                            │
+│  → Parse input → Detect mode → Route to phase       │
+└───────────────┬─────────────────────────────────────┘
+                │
+        ┌───────┴───────┐
+        ↓               ↓
+  ┌───────────┐   ┌───────────┐
+  │  Compact  │   │   Tips    │
+  │  (Phase1) │   │  (Phase2) │
+  │  Full     │   │  Quick    │
+  │  Session  │   │  Note     │
+  └─────┬─────┘   └─────┬─────┘
+        │               │
+        └───────┬───────┘
+                ↓
+        ┌───────────────┐
+        │  core_memory  │
+        │   (import)    │
+        └───────────────┘
+```
+
+## Execution Flow
+
+### Step 1: Parse Input & Route
+
+Detect execution mode from user input:
+
+**Auto-Route Rules** (priority order):
+
+| Signal | Route | Examples |
+|--------|-------|---------|
+| Keyword: compact, session, 压缩, recovery, 保存会话 | → Compact | "compact current session" |
+| Keyword: tip, note, 记录, 快速 | → Tips | "记录一个想法" |
+| Has `--tag` or `--context` flags | → Tips | `"note content" --tag bug` |
+| Short text (<100 chars) + no session keywords | → Tips | "Remember to use Redis" |
+| Ambiguous or no arguments | → **AskUserQuestion** | `/memory-capture` |
+
+**When ambiguous**, use AskUserQuestion:
+
+```
+Question: "选择记忆捕获模式"
+Options:
+  1. Compact - 压缩当前完整会话记忆（用于会话恢复）
+  2. Tips - 快速记录一条笔记/想法/提示
+```
+
+### Step 2: Execute Selected Phase
+
+Based on routing result, read and execute the corresponding phase:
+
+- **Compact mode** → Ref: [phases/01-compact.md](phases/01-compact.md)
+- **Tips mode** → Ref: [phases/02-tips.md](phases/02-tips.md)
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Mode | Document | Purpose |
+|------|----------|---------|
+| Compact | [phases/01-compact.md](phases/01-compact.md) | Full session memory compression and structured export |
+| Tips | [phases/02-tips.md](phases/02-tips.md) | Quick note-taking with tags and context |
+
+### Step 3: Save via core_memory
+
+Both phases converge on the same storage mechanism:
+
+```javascript
+mcp__ccw-tools__core_memory({
+  operation: "import",
+  text: structuredText  // Generated by the selected phase
+})
+```
+
+## Core Rules
+
+1. **Single Phase Execution**: Only ONE phase executes per invocation - never both
+2. **Content Faithful**: Phase files contain full execution detail - follow them verbatim
+3. **Absolute Paths**: All file paths in output must be absolute
+4. **No Summarization**: Compact mode preserves complete plan verbatim - never abbreviate
+5. **Speed Priority**: Tips mode should be fast - minimal analysis overhead
+
+## Input Processing
+
+### Compact Mode Input
+- Optional: `"session description"` as supplementary context
+- Example: `/memory-capture compact` or `/memory-capture "completed auth module"`
+
+### Tips Mode Input
+- Required: `<note content>` - the tip/note text
+- Optional: `--tag <tag1,tag2>` for categorization
+- Optional: `--context <context>` for related code/feature reference
+- Example: `/memory-capture tip "Use Redis for rate limiting" --tag config`
+
+## Data Flow
+
+```
+User Input
+    │
+    ├─ [compact detected] → Read phases/01-compact.md
+    │                        → Analyze session → Generate structured text
+    │                        → core_memory import → Report Recovery ID
+    │
+    └─ [tips detected] → Read phases/02-tips.md
+                         → Parse args → Gather context → Generate tip text
+                         → core_memory import → Confirm with ID + tags
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| core_memory import fails | Retry once, then report error with structured text for manual save |
+| No session context (compact) | Warn user, generate with available info |
+| Empty note content (tips) | Ask user to provide content via AskUserQuestion |
+| Ambiguous routing | Default to AskUserQuestion - never guess |
--- a/.claude/skills/memory-capture/phases/01-compact.md
+++ b/.claude/skills/memory-capture/phases/01-compact.md
@@ -0,0 +1,254 @@
+# Phase 1: Compact - Session Memory Compression
+
+Compress current session working memory into structured text optimized for session recovery, extract critical information, and save to persistent storage via MCP `core_memory` tool.
+
+## Objective
+
+- Capture everything needed to resume work seamlessly in a new session
+- Minimize re-exploration by including file paths, decisions, and state
+- Preserve train of thought for complex debugging
+- Record actionable state (last action, known issues, pending)
+
+## Input
+
+- `sessionDescription` (Optional): User-provided session description string
+  - Example: `"completed core-memory module"`
+  - Example: `"debugging JWT refresh - suspected memory leak"`
+
+## Execution
+
+### Step 1.1: Analyze Current Session
+
+Extract the following from conversation history:
+
+```javascript
+const sessionAnalysis = {
+  sessionId: "",       // WFS-* if workflow session active, null otherwise
+  projectRoot: "",     // Absolute path: D:\Claude_dms3
+  objective: "",       // High-level goal (1-2 sentences)
+  executionPlan: {
+    source: "workflow" | "todo" | "user-stated" | "inferred",
+    content: ""        // Full plan content - ALWAYS preserve COMPLETE and DETAILED form
+  },
+  workingFiles: [],    // {absolutePath, role} - modified files
+  referenceFiles: [],  // {absolutePath, role} - read-only context files
+  lastAction: "",      // Last significant action + result
+  decisions: [],       // {decision, reasoning}
+  constraints: [],     // User-specified limitations
+  dependencies: [],    // Added/changed packages
+  knownIssues: [],     // Deferred bugs
+  changesMade: [],     // Completed modifications
+  pending: [],         // Next steps
+  notes: ""            // Unstructured thoughts
+}
+```
+
+**Core Philosophy**:
+- **Session Recovery First**: Capture everything needed to resume work seamlessly
+- **Minimize Re-exploration**: Include file paths, decisions, and state to avoid redundant analysis
+- **Preserve Train of Thought**: Keep notes and hypotheses for complex debugging
+- **Actionable State**: Record last action result and known issues
+
+### Step 1.2: Plan Detection (Priority Order)
+
+**Priority 1: Workflow Session (IMPL_PLAN.md)**
+```javascript
+// Check for active workflow session
+const manifest = await mcp__ccw-tools__session_manager({
+  operation: "list",
+  location: "active"
+});
+
+if (manifest.sessions?.length > 0) {
+  const session = manifest.sessions[0];
+  const plan = await mcp__ccw-tools__session_manager({
+    operation: "read",
+    session_id: session.id,
+    content_type: "plan"
+  });
+  sessionAnalysis.sessionId = session.id;
+  sessionAnalysis.executionPlan.source = "workflow";
+  sessionAnalysis.executionPlan.content = plan.content;
+}
+```
+
+**Priority 2: TodoWrite (Current Session Todos)**
+```javascript
+// Extract from conversation - look for TodoWrite tool calls
+// Preserve COMPLETE todo list with all details
+const todos = extractTodosFromConversation();
+if (todos.length > 0) {
+  sessionAnalysis.executionPlan.source = "todo";
+  sessionAnalysis.executionPlan.content = todos.map(t =>
+    `- [${t.status === 'completed' ? 'x' : t.status === 'in_progress' ? '>' : ' '}] ${t.content}`
+  ).join('\n');
+}
+```
+
+**Priority 3: User-Stated Plan**
+```javascript
+// Look for explicit plan statements in user messages:
+// - "Here's my plan: 1. ... 2. ... 3. ..."
+// - "I want to: first..., then..., finally..."
+// - Numbered or bulleted lists describing steps
+const userPlan = extractUserStatedPlan();
+if (userPlan) {
+  sessionAnalysis.executionPlan.source = "user-stated";
+  sessionAnalysis.executionPlan.content = userPlan;
+}
+```
+
+**Priority 4: Inferred Plan**
+```javascript
+// If no explicit plan, infer from:
+// - Task description and breakdown discussion
+// - Sequence of actions taken
+// - Outstanding work mentioned
+const inferredPlan = inferPlanFromDiscussion();
+if (inferredPlan) {
+  sessionAnalysis.executionPlan.source = "inferred";
+  sessionAnalysis.executionPlan.content = inferredPlan;
+}
+```
+
+### Step 1.3: Generate Structured Text
+
+```javascript
+const generateExecutionPlan = (plan) => {
+  const sourceLabels = {
+    'workflow': 'workflow (IMPL_PLAN.md)',
+    'todo': 'todo (TodoWrite)',
+    'user-stated': 'user-stated',
+    'inferred': 'inferred'
+  };
+
+  // CRITICAL: Preserve complete plan content verbatim - DO NOT summarize
+  return `### Source: ${sourceLabels[plan.source] || plan.source}
+
+<details>
+<summary>Full Execution Plan (Click to expand)</summary>
+
+${plan.content}
+
+</details>`;
+};
+
+const structuredText = `## Session ID
+${sessionAnalysis.sessionId || '(none)'}
+
+## Project Root
+${sessionAnalysis.projectRoot}
+
+## Objective
+${sessionAnalysis.objective}
+
+## Execution Plan
+${generateExecutionPlan(sessionAnalysis.executionPlan)}
+
+## Working Files (Modified)
+${sessionAnalysis.workingFiles.map(f => `- ${f.absolutePath} (role: ${f.role})`).join('\n') || '(none)'}
+
+## Reference Files (Read-Only)
+${sessionAnalysis.referenceFiles.map(f => `- ${f.absolutePath} (role: ${f.role})`).join('\n') || '(none)'}
+
+## Last Action
+${sessionAnalysis.lastAction}
+
+## Decisions
+${sessionAnalysis.decisions.map(d => `- ${d.decision}: ${d.reasoning}`).join('\n') || '(none)'}
+
+## Constraints
+${sessionAnalysis.constraints.map(c => `- ${c}`).join('\n') || '(none)'}
+
+## Dependencies
+${sessionAnalysis.dependencies.map(d => `- ${d}`).join('\n') || '(none)'}
+
+## Known Issues
+${sessionAnalysis.knownIssues.map(i => `- ${i}`).join('\n') || '(none)'}
+
+## Changes Made
+${sessionAnalysis.changesMade.map(c => `- ${c}`).join('\n') || '(none)'}
+
+## Pending
+${sessionAnalysis.pending.length > 0
+  ? sessionAnalysis.pending.map(p => `- ${p}`).join('\n')
+  : '(none)'}
+
+## Notes
+${sessionAnalysis.notes || '(none)'}`;
+```
+
+### Step 1.4: Import to Core Memory
+
+```javascript
+mcp__ccw-tools__core_memory({
+  operation: "import",
+  text: structuredText
+})
+```
+
+### Step 1.5: Report Recovery ID
+
+After successful import, display the Recovery ID:
+
+```
+============================================================================+
+|  Session Memory Saved                                                      |
+|                                                                            |
+|  Recovery ID: CMEM-YYYYMMDD-HHMMSS                                        |
+|                                                                            |
+|  To restore: "Please import memory <ID>"                                   |
+|  (MCP: core_memory export | CLI: ccw core-memory export --id <ID>)         |
+============================================================================+
+```
+
+## Path Resolution Rules
+
+### Project Root Detection
+1. Check current working directory from environment
+2. Look for project markers: `.git/`, `package.json`, `.claude/`
+3. Use the topmost directory containing these markers
+
+### Absolute Path Conversion
+```javascript
+const toAbsolutePath = (relativePath, projectRoot) => {
+  if (path.isAbsolute(relativePath)) return relativePath;
+  return path.join(projectRoot, relativePath);
+};
+```
+
+### Reference File Categories
+| Category | Examples | Priority |
+|----------|----------|----------|
+| Project Config | `.claude/CLAUDE.md`, `package.json`, `tsconfig.json` | High |
+| Type Definitions | `src/types/*.ts`, `*.d.ts` | High |
+| Related Modules | Parent/sibling modules with shared interfaces | Medium |
+| Test Files | Corresponding test files for modified code | Medium |
+| Documentation | `README.md`, `ARCHITECTURE.md` | Low |
+
+## Quality Checklist
+
+Before generating:
+- [ ] Session ID captured if workflow session active (WFS-*)
+- [ ] Project Root is absolute path (e.g., D:\Claude_dms3)
+- [ ] Objective clearly states the "North Star" goal
+- [ ] Execution Plan: COMPLETE plan preserved VERBATIM (no summarization)
+- [ ] Plan Source: Clearly identified (workflow | todo | user-stated | inferred)
+- [ ] Plan Details: ALL phases, tasks, file paths, dependencies, status markers included
+- [ ] All file paths are ABSOLUTE (not relative)
+- [ ] Working Files: 3-8 modified files with roles
+- [ ] Reference Files: Key context files (CLAUDE.md, types, configs)
+- [ ] Last Action captures final state (success/failure)
+- [ ] Decisions include reasoning, not just choices
+- [ ] Known Issues separates deferred from forgotten bugs
+- [ ] Notes preserve debugging hypotheses if any
+
+## Output
+
+- **Variable**: `structuredText` - the generated markdown string
+- **MCP Result**: `{ operation: "import", id: "CMEM-YYYYMMDD-HHMMSS" }`
+- **User Display**: Recovery ID banner with restore instructions
+
+## Next Phase
+
+N/A - Compact is a terminal phase. Return to SKILL.md orchestrator.
--- a/.claude/skills/memory-capture/phases/02-tips.md
+++ b/.claude/skills/memory-capture/phases/02-tips.md
@@ -0,0 +1,206 @@
+# Phase 2: Tips - Quick Note Taking
+
+Quick note-taking for capturing ideas, snippets, reminders, and insights with optional tagging and context linking.
+
+## Objective
+
+- Provide minimal-friction note capture
+- Support tagging for categorization and search
+- Auto-detect context from current conversation
+- Save to core_memory for persistent retrieval
+
+## Input
+
+- `noteContent` (Required): The tip/note content to save
+- `tags` (Optional): Comma-separated tags for categorization
+- `context` (Optional): Related context (file, module, feature)
+
+**Examples**:
+```bash
+"Use Zod for runtime validation - better DX than class-validator"
+"Redis connection pool: max 10, min 2" --tag config,redis
+"Fix needed: race condition in payment processor" --tag bug,payment --context src/payments
+```
+
+## Execution
+
+### Step 2.1: Parse Arguments
+
+```javascript
+const parseTipsCommand = (input) => {
+  // Extract note content (everything before flags)
+  const contentMatch = input.match(/^"([^"]+)"|^([^\s-]+)/);
+  const content = contentMatch ? (contentMatch[1] || contentMatch[2]) : '';
+
+  // Extract tags
+  const tagsMatch = input.match(/--tag\s+([^\s-]+)/);
+  const tags = tagsMatch ? tagsMatch[1].split(',').map(t => t.trim()) : [];
+
+  // Extract context
+  const contextMatch = input.match(/--context\s+([^\s-]+)/);
+  const context = contextMatch ? contextMatch[1] : '';
+
+  return { content, tags, context };
+};
+```
+
+### Step 2.2: Gather Context
+
+```javascript
+const gatherTipContext = async () => {
+  // Get project root
+  const projectRoot = process.cwd(); // or detect from environment
+
+  // Get current session if active
+  const manifest = await mcp__ccw-tools__session_manager({
+    operation: "list",
+    location: "active"
+  });
+  const sessionId = manifest.sessions?.[0]?.id || null;
+
+  // Auto-detect files from recent conversation
+  const recentFiles = extractRecentFilesFromConversation(); // Last 5 messages
+
+  return {
+    projectRoot,
+    sessionId,
+    autoDetectedContext: recentFiles
+  };
+};
+```
+
+### Step 2.3: Generate Structured Text
+
+```javascript
+const generateTipText = (parsed, context) => {
+  const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  const tipId = `TIP-${new Date().toISOString().slice(0,10).replace(/-/g, '')}-${new Date().toTimeString().slice(0,8).replace(/:/g, '')}`;
+
+  return `## Tip ID
+${tipId}
+
+## Timestamp
+${timestamp}
+
+## Project Root
+${context.projectRoot}
+
+## Content
+${parsed.content}
+
+## Tags
+${parsed.tags.length > 0 ? parsed.tags.join(', ') : '(none)'}
+
+## Context
+${parsed.context || '(none)'}
+
+## Session Link
+${context.sessionId || '(none)'}
+
+## Auto-Detected Context
+${context.autoDetectedContext.length > 0
+  ? context.autoDetectedContext.map(f => `- ${f}`).join('\n')
+  : '(none)'}`;
+};
+```
+
+### Step 2.4: Save to Core Memory
+
+```javascript
+mcp__ccw-tools__core_memory({
+  operation: "import",
+  text: structuredText
+})
+```
+
+### Step 2.5: Confirm to User
+
+```
+Tip saved successfully
+
+  ID: CMEM-YYYYMMDD-HHMMSS
+  Tags: architecture, auth
+  Context: src/auth/**
+
+  To retrieve: core_memory(operation="search", query="<keyword>")
+```
+
+## Tag Categories (Suggested)
+
+**Technical**:
+- `architecture` - Design decisions and patterns
+- `performance` - Optimization insights
+- `security` - Security considerations
+- `bug` - Bug notes and fixes
+- `config` - Configuration settings
+- `api` - API design patterns
+
+**Development**:
+- `testing` - Test strategies and patterns
+- `debugging` - Debugging techniques
+- `refactoring` - Refactoring notes
+- `documentation` - Doc improvements
+
+**Domain Specific**:
+- `auth` - Authentication/authorization
+- `database` - Database patterns
+- `frontend` - UI/UX patterns
+- `backend` - Backend logic
+- `devops` - Infrastructure and deployment
+
+**Organizational**:
+- `reminder` - Follow-up items
+- `research` - Research findings
+- `idea` - Feature ideas
+- `review` - Code review notes
+
+## Search Integration
+
+Tips can be retrieved using:
+
+```javascript
+// Via MCP tool
+mcp__ccw-tools__core_memory({
+  operation: "search",
+  query: "rate limiting",
+  source_type: "core_memory",
+  top_k: 10
+})
+
+// Via CLI
+// ccw core-memory search --query "rate limiting" --top-k 10
+```
+
+## Quality Checklist
+
+Before saving:
+- [ ] Content is clear and actionable
+- [ ] Tags are relevant and consistent
+- [ ] Context provides enough reference
+- [ ] Auto-detected context is accurate
+- [ ] Project root is absolute path
+- [ ] Timestamp is properly formatted
+
+## Best Practices
+
+### Good Tips
+
+- **Specific and Actionable**: `"Use connection pooling for Redis: { max: 10, min: 2, acquireTimeoutMillis: 30000 }" --tag config,redis`
+- **With Context**: `"Auth middleware must validate both access and refresh tokens" --tag security,auth --context src/middleware/auth.ts`
+- **Problem + Solution**: `"Memory leak fixed by unsubscribing event listeners in componentWillUnmount" --tag bug,react --context src/components/Chat.tsx`
+
+### Poor Tips (Avoid)
+
+- Too Vague: `"Fix the bug" --tag bug`
+- Too Long (use Compact instead): Multi-paragraph implementation plans
+- No Context: `"Remember to update this later"`
+
+## Output
+
+- **Variable**: `structuredText` - the generated tip markdown string
+- **MCP Result**: `{ operation: "import", id: "CMEM-YYYYMMDD-HHMMSS" }`
+- **User Display**: Confirmation with ID, tags, and retrieval hint
+
+## Next Phase
+
+N/A - Tips is a terminal phase. Return to SKILL.md orchestrator.