compact

Memory Compact 命令（/memory:compact）

1. 概述

memory:compact 命令会将当前会话工作记忆压缩为适合会话恢复的结构化文本，提取关键信息，并通过 MCP core_memory 工具将其保存到持久化存储中。

核心理念：

• 优先恢复会话：记录无缝恢复工作所需的全部信息
• 尽量减少重新探索：包含文件路径、决策和状态，避免重复分析
• 保留思维过程：为复杂调试保留笔记和假设
• 记录可执行状态：记录上一步操作结果和已知问题

2. 参数

• --description：自定义会话描述（可选）
  • 示例：“已完成 core-memory 模块”
  • 示例：“正在调试 JWT 刷新——怀疑存在内存泄漏”
• --tags：用于分类的逗号分隔标签（可选）
• --force：跳过确认，直接保存

3. 结构化输出格式

## 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
- [x] 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
- [Decision]: [Reasoning]
- [Decision]: [Reasoning]

## 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. 字段定义

字段	用途	恢复价值
Session ID	工作流会话标识符（WFS-*）	将记忆关联到特定的有状态任务执行
Project Root	项目目录的绝对路径	确保在新会话中正确解析路径
Objective	会话的最终目标	避免忘记更宏观的功能目标
Execution Plan	来自任何来源的完整计划（原文照录）	保留完整的计划上下文，避免重新规划
Working Files	正在修改的文件（绝对路径）	立即确定当前工作的文件位置
Reference Files	只读上下文文件（绝对路径）	无需重新探索关键上下文
Last Action	最终工具输出／状态	立即了解状态（成功／失败）
Decisions	架构选择及其理由	避免重新争论已确定的决策
Constraints	用户施加的限制	保持个性化的编码风格
Dependencies	软件包／环境变更	避免出现依赖缺失错误
Known Issues	延后处理的错误／边缘情况	确保不会遗忘问题
Changes Made	已完成的修改	清楚记录已完成的工作
Pending	后续步骤	可立即执行的待办事项
Notes	假设、调试过程记录	保留“思维过程”

5. 执行流程

步骤 1：分析当前会话

从对话历史中提取以下内容：

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
}

步骤 2：生成结构化文本

// 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)'}`

步骤 3：通过 MCP 导入核心记忆

使用 MCP core_memory 工具保存结构化文本：

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

或者通过 CLI（将结构化文本通过管道传入以进行导入）：

# 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

响应格式：

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

步骤 4：报告恢复 ID

导入成功后，向用户清晰显示恢复 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>)         ║
╚════════════════════════════════════════════════════════════════════════════╝

6. 质量检查清单

生成前请确认：

• 如果工作流会话处于活动状态，已记录 Session ID（WFS-*）
• Project Root 是绝对路径（例如，D:\Claude_dms3）
• Objective 清晰说明“北极星”目标
• Execution Plan：完整保留计划原文（不得概述）
• Plan Source：明确标注来源（workflow | todo | user-stated | inferred）
• Plan Details：包含所有阶段、任务、文件路径、依赖项和状态标记
• 所有文件路径均为绝对路径（而非相对路径）
• Working Files：列出 3-8 个已修改文件及其作用
• Reference Files：列出关键上下文文件（CLAUDE.md、类型定义、配置）
• Last Action 记录最终状态（成功／失败）
• Decisions 包含理由，而不仅是选择
• Known Issues 区分延后处理的问题与遗忘的问题
• Notes 在存在调试假设时予以保留

7. 路径解析规则

项目根目录检测

1. 从环境中检查当前工作目录
2. 查找项目标记：.git/、package.json、.claude/
3. 使用包含这些标记的最上层目录

绝对路径转换

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

参考文件类别

类别	示例	优先级
项目配置	.claude/CLAUDE.md、package.json、tsconfig.json	高
类型定义	src/types/*.ts、*.d.ts	高
相关模块	具有共享接口的父级/同级模块	中
测试文件	与修改的代码对应的测试文件	中
文档	README.md、ARCHITECTURE.md	低

8. 计划检测（按优先级排序）

优先级 1：工作流会话（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;
}

优先级 2：TodoWrite（当前会话待办事项）

// 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');
}

优先级 3：用户提出的计划

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

优先级 4：推断的计划

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

• 时机：在任务完成时或切换上下文前执行
• 频率：每个独立任务或里程碑执行一次
• 恢复：新会话可立即基于完整上下文继续
• 知识图谱：自动提取实体关系以供可视化
• 绝对路径：对于在不同机器间跨会话恢复至关重要