COA Goldfish MCP

Instructions

Implementation Reference

• archive/src/tools/session.ts:26-159 (handler)

  Main handler function for restore_session tool. Handles session restoration with configurable depth (minimal, highlights, full). Fetches memories/checkpoints, formats output progressively, supports specific sessionId or latest checkpoint.
  async restoreSession(args: { sessionId?: string; depth?: 'minimal' | 'highlights' | 'full'; workspace?: string; format?: OutputMode; } = {}) { const { sessionId, depth = 'highlights', workspace, format } = args; try { let targetMemories: GoldfishMemory[] = []; if (sessionId) { // Restore specific session targetMemories = await this.getSessionMemories(sessionId, workspace); } else { // Get latest checkpoint const recentMemories = await this.searchEngine.searchMemories({ type: 'checkpoint', workspace, scope: 'current', limit: 1 }); if (recentMemories.length === 0) { return { content: [ { type: 'text', text: '❓ No recent checkpoints found. Create your first checkpoint to establish session state!' } ] }; } targetMemories = recentMemories; // Using latest checkpoint } if (targetMemories.length === 0) { return { content: [ { type: 'text', text: `❓ No session found${sessionId ? ` with ID "${sessionId}"` : ''}. It may have expired or was never saved.` } ] }; } // Format output based on depth const output = [ '═══════════════════════════════════════════════════════════', '📍 RESUMING FROM CHECKPOINT', '═══════════════════════════════════════════════════════════', '' ]; if (depth === 'minimal') { // Just the latest checkpoint const latest = targetMemories[0]; if (latest) { output.push(this.formatCheckpoint(latest, true)); } } else if (depth === 'highlights') { // Latest checkpoint + session highlights const latest = targetMemories[0]; if (latest) { output.push(this.formatCheckpoint(latest, true)); // Get session highlights if (typeof latest.content === 'object' && latest.content && 'highlights' in latest.content) { const contentObj = latest.content as { highlights?: string[] }; if (Array.isArray(contentObj.highlights) && contentObj.highlights.length > 0) { output.push('\n🌟 **Session Highlights:**'); contentObj.highlights.slice(-5).forEach((highlight: string) => { output.push(` ✨ ${highlight}`); }); } } } } else if (depth === 'full') { // All checkpoints from session output.push(`📊 Found ${targetMemories.length} checkpoints:\n`); targetMemories.slice(0, 10).forEach((memory, index) => { output.push(`**Checkpoint ${index + 1}** (${this.formatAge(memory.timestamp)})`); output.push(this.formatCheckpoint(memory, false)); output.push(''); }); if (targetMemories.length > 10) { output.push(`... and ${targetMemories.length - 10} more checkpoints`); } } output.push(''); output.push('═══════════════════════════════════════════════════════════'); output.push('✅ Session restored successfully'); output.push('📝 Ready to continue where you left off!'); output.push('🚀 What would you like to work on?'); output.push('═══════════════════════════════════════════════════════════'); const formatted = output.join('\n'); const data = { sessionId: sessionId || 'latest', depth, checkpointsFound: targetMemories.length, highlightsFound: targetMemories.filter((m: GoldfishMemory) => typeof m.content === 'object' && m.content && 'highlights' in m.content && Array.isArray((m.content as { highlights?: string[] }).highlights) && (m.content as { highlights?: string[] }).highlights!.length > 0 ).length, workspace, sample: targetMemories.slice(0, 3) as unknown as Record<string, unknown> } as const; return buildToolContent('session-restore', formatted, data as any, format); } catch (error) { return { content: [ { type: 'text', text: `❌ Session restoration failed: ${error instanceof Error ? error.message : String(error)}` } ] }; } }
• archive/src/tools/session.ts:428-454 (schema)

  Input schema definition for the restore_session tool, including parameters for sessionId, depth, workspace, and format.
  { name: 'restore_session', description: 'IMMEDIATELY restore context after any break or /clear. ALWAYS use at conversation start if continuing previous work. Critical for continuity. Use depth: "full" when returning after days away.', inputSchema: { type: 'object', properties: { sessionId: { type: 'string', description: 'Specific session ID to restore (optional - defaults to latest)' }, depth: { type: 'string', enum: ['minimal', 'highlights', 'full'], description: 'Restoration depth: minimal=last checkpoint only, highlights=last+key points, full=entire session' }, workspace: { type: 'string', description: 'Workspace name or path (e.g., "coa-goldfish-mcp" or "C:\\source\\COA Goldfish MCP"). Will be normalized automatically.' }, format: { type: 'string', enum: ['plain', 'emoji', 'json', 'dual'], description: 'Output format override (defaults to env GOLDFISH_OUTPUT_MODE or dual)' } } } },
• archive/src/index.ts:87-88 (registration)

  Comment indicating that restore_session has been replaced by the unified checkpoint tool in the main server registration.
  // Unified checkpoint tool (replaces checkpoint, restore_session, and search functionality) UnifiedCheckpointTool.getToolSchema(),
• archive/src/tools/checkpoint-unified.ts:296-297 (helper)

  Error handling in unified checkpoint tool references 'restore_session' as fallback tool name.
  'restore_session', args.outputFormat