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