Memory Capture

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):

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
• Tips mode → Ref: phases/02-tips.md

Phase Reference Documents (read on-demand when phase executes):

Step 3: Save via core_memory

Both phases converge on the same storage mechanism:

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

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:

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)

// 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)

// 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

// 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

// 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

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

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

const toAbsolutePath = (relativePath, projectRoot) => {
  if (path.isAbsolute(relativePath)) return relativePath;
  return path.join(projectRoot, relativePath);
};

Reference File Categories

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.

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:

"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

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

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

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

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:

// 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.