Memory Compact Command (/memory:compact)

1. Overview

The memory:compact command compresses current session working memory into structured text optimized for session recovery, extracts critical information, and saves it to persistent storage via MCP core_memory tool.

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

2. Parameters

• --description : Custom session description (optional)

• Example: "completed core-memory module"

• Example: "debugging JWT refresh - suspected memory leak"

• --tags : Comma-separated tags for categorization (optional)

• --force : Skip confirmation, save directly

3. Structured Output Format

Session ID

[WFS-ID if workflow session active, otherwise (none)]

Project Root

[Absolute path to project root, e.g., D:\Claude_dms3]

Objective

[High-level goal - the "North Star" of this session]

Execution Plan

[CRITICAL: Embed the LATEST plan in its COMPLETE and DETAILED form]

Source: [workflow | todo | user-stated | inferred]

<details> <summary>Full Execution Plan (Click to expand)</summary>

[PRESERVE COMPLETE PLAN VERBATIM - DO NOT SUMMARIZE]

• ALL phases, tasks, subtasks
• ALL file paths (absolute)
• ALL dependencies and prerequisites
• ALL acceptance criteria
• ALL status markers ([x] done, [ ] pending)
• ALL notes and context

Example:

Phase 1: Setup

• Initialize project structure
  • Created D:\Claude_dms3\src\core\index.ts
  • Added dependencies: lodash, zod
• Configure TypeScript
  • Update tsconfig.json for strict mode

Phase 2: Implementation

• Implement core API
  • Target: D:\Claude_dms3\src\api\handler.ts
  • Dependencies: Phase 1 complete
  • Acceptance: All tests pass

</details>

Working Files (Modified)

[Absolute paths to actively modified files]

• D:\Claude_dms3\src\file1.ts (role: main implementation)
• D:\Claude_dms3\tests\file1.test.ts (role: unit tests)

Reference Files (Read-Only)

[Absolute paths to context files - NOT modified but essential for understanding]

• D:\Claude_dms3.claude\CLAUDE.md (role: project instructions)
• D:\Claude_dms3\src\types\index.ts (role: type definitions)
• D:\Claude_dms3\package.json (role: dependencies)

Last Action

[Last significant action and its result/status]

Decisions

Constraints

• [User-specified limitation or preference]

Dependencies

• [Added/changed packages or environment requirements]

Known Issues

• [Deferred bug or edge case]

Changes Made

• [Completed modification]

Pending

• [Next step] or (none)

Notes

[Unstructured thoughts, hypotheses, debugging trails]

4. Field Definitions

Field Purpose Recovery Value

Session ID Workflow session identifier (WFS-*) Links memory to specific stateful task execution

Project Root Absolute path to project directory Enables correct path resolution in new sessions

Objective Ultimate goal of the session Prevents losing track of broader feature

Execution Plan Complete plan from any source (verbatim) Preserves full planning context, avoids re-planning

Working Files Actively modified files (absolute paths) Immediately identifies where work was happening

Reference Files Read-only context files (absolute paths) Eliminates re-exploration for critical context

Last Action Final tool output/status Immediate state awareness (success/failure)

Decisions Architectural choices + reasoning Prevents re-litigating settled decisions

Constraints User-imposed limitations Maintains personalized coding style

Dependencies Package/environment changes Prevents missing dependency errors

Known Issues Deferred bugs/edge cases Ensures issues aren't forgotten

Changes Made Completed modifications Clear record of what was done

Pending Next steps Immediate action items

Notes Hypotheses, debugging trails Preserves "train of thought"

5. Execution Flow

Step 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 }

Step 2: Generate Structured Text

// Helper: Generate execution plan section 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 3: Import to Core Memory via MCP

Use the MCP core_memory tool to save the structured text:

mcp__ccw-tools__core_memory({ operation: "import", text: structuredText })

Or via CLI (pipe structured text to import):

Write structured text to temp file, then import

echo "$structuredText" | ccw core-memory import

Or from a file

ccw core-memory import --file /path/to/session-memory.md

Response Format:

{ "operation": "import", "id": "CMEM-YYYYMMDD-HHMMSS", "message": "Created memory: CMEM-YYYYMMDD-HHMMSS" }

Step 4: Report Recovery ID

After successful import, clearly display the Recovery ID to the user:

╔════════════════════════════════════════════════════════════════════════════╗ ║ ✓ 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>) ║ ╚════════════════════════════════════════════════════════════════════════════╝

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

7. Path Resolution Rules

Project Root Detection

• Check current working directory from environment

• Look for project markers: .git/ , package.json , .claude/

• Use the topmost directory containing these markers

Absolute Path Conversion

// Convert relative to absolute const toAbsolutePath = (relativePath, projectRoot) => { if (path.isAbsolute(relativePath)) return relativePath; return path.join(projectRoot, relativePath); };

// Example: "src/api/auth.ts" → "D:\Claude_dms3\src\api\auth.ts"

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

8. 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"; // Format todos with full context - preserve status markers 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; }

9. Notes

• Timing: Execute at task completion or before context switch

• Frequency: Once per independent task or milestone

• Recovery: New session can immediately continue with full context

• Knowledge Graph: Entity relationships auto-extracted for visualization

• Absolute Paths: Critical for cross-session recovery on different machines